# Companies

Find a company and retrieve its identifiers and reporting information.

Source: <https://docs.finbar.com/api-mcp/entities>

A company record is called an **entity** in the API. Use company search to
obtain an `entity_id`, then use that ID to retrieve its information, documents,
or financial dataset.

Both endpoints require `entities:read` permission. Examples assume you have
an [access token](https://docs.finbar.com/api-mcp/authentication.md) stored as `ACCESS_TOKEN`.

## Search companies

```text
GET /v1/entities
```

| Query parameter | Required | Meaning                                                       |
| --------------- | -------- | ------------------------------------------------------------- |
| `q`             | Yes      | Company name or ticker to search for                          |
| `limit`         | No       | Requested page size; default 10, effective maximum 25         |
| `cursor`        | No       | Continuation value from the previous response's `next_cursor` |

```bash
curl --fail-with-body --silent --show-error --get \
  'https://api.finbar.com/v1/entities' \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --data-urlencode 'q=AAPL' \
  --data-urlencode 'limit=5'
```

The `entities` array contains `entity_id`, `name` and `score` for each match.
`score` measures search relevance; results are ordered with the most relevant
first. Search only returns companies available to your account. A strong exact
match may be returned on its own.

If `next_cursor` is present, pass it as `cursor` with the same `q` to read the
next page. An empty array means no available matches.

## Read company information

```text
GET /v1/entities/{entity_id}
```

Set `ENTITY_ID` to an ID from search:

```bash
curl --fail-with-body --silent --show-error \
  "https://api.finbar.com/v1/entities/$ENTITY_ID" \
  --header "Authorization: Bearer $ACCESS_TOKEN"
```

The response identifies the company and includes available tickers, security
identifiers, investor-relations website and upcoming reporting information.
An ISIN is an international identifier for a security; a ticker is its trading
symbol. Optional information may be absent.

**GET /v1/entities/{entity\_id} — 200 response**

Example response. IDs and values are illustrative.

```json
{
  "entity_id": "O-03049bdc0cb94012b761a4c3046c2a2d",
  "name": "Apple Inc.",
  "ticker": [
    "AAPL US"
  ],
  "isin": [
    "US0378331005"
  ],
  "ir_website_url": "https://investor.apple.com",
  "next_report_date": "2026-10-29T00:00:00Z",
  "next_report_period": {
    "year": 2026,
    "period_type": "Q",
    "period": 4
  }
}
```

Use the company's ID to [list its documents](https://docs.finbar.com/api-mcp/documents.md) or
[discover its dataset](https://docs.finbar.com/api-mcp/catalogue.md). IDs for documents, paragraphs and
tables cannot be used in place of an `entity_id`.