Documents | Finbar Docs

A document is a company report. Each document has a document_id and contains readable items: paragraphs and tables, each with its own ID. Search locates items within documents; reading an item returns its content.

All endpoints on this page require documents:read. First find a company and set ENTITY_ID to its entity_id. The examples use an access token as ACCESS_TOKEN.

List reports

GET /v1/entities/{entity_id}/documents

curl --fail-with-body --silent --show-error --get \
  "https://api.finbar.com/v1/entities/$ENTITY_ID/documents" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --data-urlencode 'document_types=FULL_FINANCIAL_REPORT' \
  --data-urlencode 'limit=5'

Query parameter	Meaning
`document_types`	Filter by document type; `FULL_FINANCIAL_REPORT` selects financial reports
`start_period`, `end_period`	Inclusive reporting-period bounds, such as `2024Y` and `2025Y`
`tags`	Filter by document tags
`limit`	Reports per page, from 1 to 100; default 50
`cursor`	Continuation value from `next_cursor`

The documents array includes document IDs, types and reporting periods. Results are ordered by report date, most recent first. Period filters refer to the period covered by a report, not its publication date.

GET /v1/entities/{entity_id}/documents — 200 response

Example response. IDs and values are illustrative.

{
  "documents": [
    {
      "document_id": "D-d15ec8e059d94a2f8aa352025f57f7bb",
      "entity_id": "O-03049bdc0cb94012b761a4c3046c2a2d",
      "period": {
        "year": 2025,
        "period_type": "Y",
…

Show full responseShow less

{
  "documents": [
    {
      "document_id": "D-d15ec8e059d94a2f8aa352025f57f7bb",
      "entity_id": "O-03049bdc0cb94012b761a4c3046c2a2d",
      "period": {
        "year": 2025,
        "period_type": "Y",
        "period": 0
      },
      "publish_date": "2025-10-31T00:00:00Z",
      "report_date": "2025-09-27T00:00:00Z",
      "status": "PARSED",
      "type": "FULL_FINANCIAL_REPORT",
      "tag": "20F"
    }
  ],
  "next_cursor": "eyJ2IjoxLCJxIjoiLi4uIn0"
}

Search report content

POST /v1/document-search

Search all available reports for a company:

curl --fail-with-body --silent --show-error \
  'https://api.finbar.com/v1/document-search' \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header 'Content-Type: application/json' \
  --data "{\"entity_id\":\"$ENTITY_ID\",\"query\":\"revenue growth\",\"limit\":5}"

Body field	Meaning
`query`	Required search text
`entity_id` or `document_id`	Required search target; supply exactly one
`start_period`, `end_period`	Optional inclusive reporting-period bounds; only valid with `entity_id`
`limit`	Matches per page, from 1 to 20; default 5
`cursor`	Continuation value from `next_cursor`

To search one report, replace entity_id with its document_id. The results array contains matching paragraphs and tables. Each has an id, document_id and preview. A preview is an excerpt; read the matching item before using it as evidence for an answer.

Read a paragraph or table

GET /v1/document-items/{item_id}

Set ITEM_ID to a search result's id or a dataset source's item_id:

curl --fail-with-body --silent --show-error \
  "https://api.finbar.com/v1/document-items/$ITEM_ID" \
  --header "Authorization: Bearer $ACCESS_TOKEN"

The response's chunks array contains rendered text or table content in each chunk's content field. A chunk is one bounded piece of content returned by a document read. is_truncated: true means content has been shortened.

For a large table, the optional table_subslice query parameter selects a smaller range while retaining header context. For example, R0C0:R4C3 selects rows 0–4 and columns 0–3; indices start at zero. Use a table ID for this parameter; if a paragraph links to a table, read its returned table_id directly. raw_data=true requests raw table values where available.

Read through a report

GET /v1/documents/{document_id}/chunks

Set DOCUMENT_ID to an ID from the document list:

curl --fail-with-body --silent --show-error --get \
  "https://api.finbar.com/v1/documents/$DOCUMENT_ID/chunks" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --data-urlencode 'start_index=0' \
  --data-urlencode 'limit=5'

start_index is the zero-based paragraph position at which to start reading. limit is required and accepts 1–10 chunks. To continue, send cursor with the returned next_cursor in place of start_index, keeping limit.

For lists and searches, also follow next_cursor until it is absent. Keep the same target and filters. See pagination for the common pattern.