API quickstart
Authenticate and make your first company search request.
The REST API accepts HTTPS requests and returns JSON. Its base URL is:
https://api.finbar.com/v1
This walkthrough uses curl from a terminal. You need a Finbar account with
API access and a REST API credential from the web app's API panel.
1. Get an access token
Follow Authentication to create a credential and
exchange its client ID and secret for an access token. Request
read permission for this example.
Set ACCESS_TOKEN in your terminal to the returned access_token.
2. Search for a company
curl --fail-with-body --silent --show-error --get \
'https://api.finbar.com/v1/entities' \
--header "Authorization: Bearer $ACCESS_TOKEN" \
--data-urlencode 'q=Apple' \
--data-urlencode 'limit=5'
GET /entities searches the companies available to your account. q is the
search text; limit is the requested number of matches. The authorization
header supplies your token.
GET /v1/entities — 200 response
Example response. IDs and values are illustrative.
Show less
{
"entities": [
{
"entity_id": "O-03049bdc0cb94012b761a4c3046c2a2d",
"name": "Apple Inc.",
"score": 0.98
}
],
"next_cursor": "eyJ2IjoxLCJiaW5kaW5nIjoiLi4uIn0"
}
3. Select the company
Check the name in the returned entities array and save the matching
entity_id. “Entity” is the API's term for a company record. Its ID is used
in subsequent requests; a company name or ticker cannot replace it.
If entities is empty, no available company matched. Try a different name
or ticker. If there are several matches, read company details
to confirm the one you need.
Make the next request
| Task | Guide | Additional permission |
|---|---|---|
| Read company information | Companies | None |
| Read company wiki | Companies | None |
| Find reports and read their content | Documents | read |
| Check request usage | Usage and limits | read |
| Create and maintain company lists | Watchlists | read, write |
| Start jobs when new documents arrive | Webhooks | read and write |
| Build or update historical rows | Build/Update Dataset | read, write |
For additional pages of results and failed requests, see errors and pagination.