Document Retrieval

Topograph gives you access to official company documents (trade register extracts, financial statements, articles of association, UBO certificates, and more) directly from government registers across 30+ countries.

For live document coverage, country-specific availability, and pricing, see Coverage and pricing.

Key things to know before you start:

The document list is dynamic. It depends on what the register actually holds for each company. A company may have 10 financial statements or none.
Document categories are a fixed set. Every document is returned under one of the fixed keys of the documents object (financialStatements, tradeRegisterExtract, etc.), with a subType that classifies it more precisely. See Document categories.
Retrieval is asynchronous because we query real government registers, not a cache. Use webhooks or polling.
Documents are sorted newest first within each category. This is guaranteed.
Document IDs are opaque. Always discover them via availableDocuments before requesting a download. IDs are generally stable across consecutive requests but we do not guarantee long-term stability, so do not store them permanently.
Prices are shown upfront. Each listed document includes a price in credits (or a priceMarkup when the price depends on the register’s fee). You are only charged when you request the download.
Documents arrive progressively. A company’s documents may come from multiple underlying sources (e.g., trade register + financial filings authority). Results are delivered incrementally via webhooks or polling. You don’t need to wait for the full list: act as soon as the document you need appears.
Every document names its issuing register. Each document carries a source object identifying the register it comes from, in the same format as dataSources. See Document source.

How it works

Document retrieval follows a two-step process:

Always request availableDocuments first to get valid document IDs. Document IDs are opaque identifiers (typically UUIDs) specific to each company. While they are generally stable short-term, do not hardcode them or rely on long-term persistence.

Progressive delivery

For many countries, Topograph queries multiple underlying sources to build the full document list. For example, France combines the INPI register (for trade register extracts and articles of association) and the JOAFE (for official publications of associations). This means availableDocuments results arrive incrementally. Each webhook (or polling response) may contain more documents than the previous one. You don’t need to wait for the availableDocuments status to reach succeeded before acting: if the document you need is already in the list, you can request it immediately.

Build your integration to process documents as they arrive rather than waiting for the full list. This is especially useful for slow countries where the complete list can take minutes.

Step 1: List available documents

Request the availableDocuments data point to discover which documents the register holds for a given company:

curl --request POST \
  --url https://api.topograph.co/v2/company \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "countryCode": "FR",
    "id": "928020932",
    "dataPoints": ["availableDocuments"]
  }'

The listed documents are returned in the documents object of the response, grouped by category (see Document categories). Each entry describes a document. Listed documents that you have not requested yet carry no url:

{
  "documents": {
    "financialStatements": [
      {
        "id": "1c932de4-4610-5506-b48d-4e62529d58e8",
        "name": "Bilan annuel 2024",
        "description": "Annual financial statement for fiscal year 2024",
        "format": "pdf",
        "date": "2024-12-31",
        "price": 0,
        "estimatedDeliverySeconds": 15,
        "source": {
          "type": "live_from_registry",
          "register": "inpi"
        }
      }
    ],
    "tradeRegisterExtract": {
      "id": "a7f3b2c1-9e8d-4a5f-b6c0-d1e2f3a4b5c6",
      "name": "Certificat INPI",
      "description": "Uncertified trade register extract from INPI",
      "format": "pdf",
      "price": 0,
      "estimatedDeliverySeconds": 5,
      "source": {
        "type": "live_from_registry",
        "register": "inpi"
      }
    }
  }
}

Step 2: Request specific documents

Use the id values from step 1 to request the documents you need:

curl --request POST \
  --url https://api.topograph.co/v2/company \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "countryCode": "FR",
    "id": "928020932",
    "documents": [
      "1c932de4-4610-5506-b48d-4e62529d58e8"
    ]
  }'

Each requested document appears in the documents object of the response, grouped by category (see Document categories below). The document includes a temporary download URL.

You can combine both steps in a single request by including both dataPoints: ["availableDocuments"] and documents: ["doc-id"]. The available documents list will arrive first, and the requested documents will follow.

Document categories

Documents carry no type field. Their category is the key they sit under in the documents object, both when listed and when downloaded:

Field	Type	Description
`tradeRegisterExtract`	Single document	Latest uncertified trade register extract
`certifiedTradeRegisterExtract`	Single document	Latest certified trade register extract
`tradeRegisterHistory`	Single document	Historical trade register extract (full record of changes), where the register publishes one
`financialStatements`	Array	Financial statements, sorted newest first
`articlesOfAssociation`	Array	Articles of association / statutes, sorted newest first
`ultimateBeneficialOwnersCertificate`	Single document	Latest UBO certificate
`officialPublications`	Array	Official publications, sorted newest first
`annualReturns`	Array	Annual returns, sorted newest first
`certificateOfGoodStanding`	Single document	Latest certificate of good standing
`otherDocuments`	Array	Other documents

Within each array category, documents are always sorted by date descending (most recent first), so the most recent financial statement is financialStatements[0]. The one exception is otherDocuments in Ireland, which follows the register’s own priority order. Array categories can hold documents of several kinds. Each document carries a subType, a stable per-country classifier of the document kind. Use it rather than name to tell documents apart or to match them against the country’s documents catalog.

While the categories are fixed, the list of documents for a given company is dynamic. A company may have zero financial statements or ten. It depends entirely on what the register holds. This is why the availableDocuments step exists.

Document source

Every document in the documents object (listed or downloaded) carries a source field identifying the register that issues it. This is the same format as the dataSources section for company data:

{
  "source": {
    "type": "live_from_registry",
    "register": "companies_house"
  }
}

Field	Description
`register`	Machine-readable code of the issuing register (e.g. `companies_house`, `inpi`, `handelsregister`). The registers behind each country are listed on the country’s coverage page.
`type`	How the document is obtained: `live_from_registry` (retrieved live from the register), `cached_from_registry` (served from data the register publishes, such as an open data extract), or `private_source` (obtained through a partner).

Use source.register to display the issuing authority to your users, or to apply per-register logic in countries where documents come from more than one register (e.g. France, where extracts come from INPI and certified K-bis extracts from Infogreffe).

Documents downloaded before this field was introduced may omit source when re-read via GET /v2/company/{requestId}. Re-running the request returns the attributed version.

Document IDs

Document IDs are opaque identifiers, typically UUIDs like 1c932de4-4610-5506-b48d-4e62529d58e8. They are:

Generated when you request availableDocuments for a company
Generally stable across consecutive requests for the same company, so you can reuse them short-term
Not guaranteed to be stable long-term. If you need a document days or weeks later, call availableDocuments again to get fresh IDs

The correct flow is always: list available documents, then pick the IDs you need.

Downloading documents

Document download links are signed URLs with a 15-minute lifespan. To handle this:

Download immediately after receiving the URL, or
Refresh the URL by calling GET /v2/company/{requestId}. This regenerates fresh signed URLs at no additional cost

curl --request GET \
  --url https://api.topograph.co/v2/company/253299d1-e8d0-4268-945b-f175f98bc114 \
  --header 'x-api-key: <api-key>'

Re-fetching a request by requestId is free and will not be billed again. Store your request IDs to refresh download links as needed.

Document pricing

Each listed document includes a price field indicating its cost in credits. Many documents are free (price = 0), while others (typically certified extracts or documents from paid registers) have a cost. For documents priced on the register’s fee, price can be absent until the fee is known; priceMarkup then gives the percentage applied to it. You can check the price before purchasing by inspecting the documents listed after an availableDocuments request. Credits are only charged when you actually request the document for download. Some documents are included at no extra cost when the matching data block is requested in the same call (or linked via 24-hour deduplication). Coverage is country-specific; see GET /v2/pricing and Coverage and pricing. For details on blocks, deduplication, and budgets, see Pricing & Caching.

Automatic PDF conversion

Some registers publish documents in non-PDF formats. Topograph automatically converts them to PDF. Supported source formats:

Images: JPG, JPEG, PNG, TIFF, TIF
Spreadsheets: CSV, XLS, XLSX
Documents: DOC, DOCX, RTF, TXT, XPS
Presentations: PPT, PPTX
Web pages: HTML, HTM
Signed containers: EDOC, ASiC-E

When conversion is needed, the document status stays in_progress until processing completes (typically ~20 seconds). Once done, the document includes:

url: the original file from the register
pdfUrl: the PDF generated by Topograph

If the source is already a PDF, both fields point to the same file.

AI-powered financial data extraction

Financial statements are automatically parsed using AI to extract structured data: revenue, assets, liabilities, ratios, and more. This happens during document post-processing with no additional configuration. For the full data model and available fields, see Financial Data Extraction.

Performance expectations

Document retrieval speed depends on the country and the register being queried:

Fast countries (France, Finland, Estonia…): available documents listed in seconds, documents downloaded in under a minute
Medium countries (Belgium, Netherlands, Ireland…): 10-30 seconds for available documents, 1-2 minutes for downloads
Slow countries (Germany, Spain…): available documents can take several minutes due to slow government registers

If you have tight response time requirements, request availableDocuments as a separate step and handle the wait asynchronously. Use webhooks rather than polling for the best experience with slower countries.

For country-specific details on available documents and expected response times, browse the Country Guides.

Best practices

Always start with availableDocuments: This ensures you have valid, current document IDs and know what’s available before purchasing.
Store request IDs: Keep the requestId to refresh download URLs for free within 24 hours.
Monitor document status: Check request.dataStatus.documents[docId].status. Documents may be in_progress while being fetched or converted.
Handle timeouts gracefully: For slower registers, use webhooks or increase your polling timeout rather than abandoning the request.
Check prices before downloading: Inspect the price (or priceMarkup) field of the listed documents to avoid unexpected charges.

For a broader picture of how document retrieval fits into the company data flow, see the Verification Data guide.

Getting Started

AI Agents

Integration Guides

Core Features

Behavior & Operations

Document Retrieval

How it works

Progressive delivery

Step 1: List available documents

Step 2: Request specific documents

Document categories

Document source

Document IDs

Downloading documents

Document pricing

Automatic PDF conversion

AI-powered financial data extraction

Performance expectations

Best practices

​How it works

​Progressive delivery

​Step 1: List available documents

​Step 2: Request specific documents

​Document categories

​Document source

​Document IDs

​Downloading documents

​Document pricing

​Automatic PDF conversion

​AI-powered financial data extraction

​Performance expectations

​Best practices

How it works

Progressive delivery

Step 1: List available documents

Step 2: Request specific documents

Document categories

Document source

Document IDs

Downloading documents

Document pricing

Automatic PDF conversion

AI-powered financial data extraction

Performance expectations

Best practices