API quickstart

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 entities: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.

{
  "entities": [
    {
      "entity_id": "O-03049bdc0cb94012b761a4c3046c2a2d",
      "name": "Apple Inc.",
      "score": 0.98
    }
  ],
…

{
  "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

For additional pages of results and failed requests, see errors and pagination.