Company Data

The /v2/company endpoint is the single entry point for company data, official documents, and ownership graph traversal. It accepts one company identifier, one country, and the datapoints or documents you want. Use it for company onboarding, KYB verification, shareholder and UBO checks, subsidiary analysis, official document retrieval, and follow-up polling by requestId.

For live country coverage, data block availability, pricing, sources, identifiers, and document catalogs, see Coverage and pricing.

Request shape

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": ["company", "legalRepresentatives", "availableDocuments"]
  }'

Datapoints

Availability varies by country and mode. Use the live pricing pages or GET /v2/pricing for country-specific availability.

Datapoint	What it returns
`company`	Core registration record: legal name, identifiers, legal form, status, address, activity codes, capital, and tax identifiers when available.
`legalRepresentatives`	Directors, managers, officers, and other people or companies with legal authority to represent the company.
`otherKeyPersons`	Non-signing roles such as auditors, supervisory board members, registered agents, or similar roles when the register exposes them separately.
`establishments`	Branches, secondary locations, business premises, or registered establishments.
`shareholders`	Direct shareholders and ownership details as available from the register or official filings.
`subsidiaries`	Companies owned by the queried company, when downstream participation data is available.
`ultimateBeneficialOwners`	Declared beneficial owners and control information where available.
`availableDocuments`	List of official documents available for the company. Use the returned document IDs in a follow-up request.
`graph`	Multi-level ownership traversal across companies and jurisdictions. See Ownership graph.

The legacy companyProfile datapoint is still accepted for existing integrations. New integrations should request explicit datapoints. See the migration guide.

Person identities and role entries

entityId identifies a person or company within a request. It links occurrences of the same entity across datapoints, such as legalRepresentatives, shareholders, and ultimateBeneficialOwners. It is not a permanent identifier to match people across separate requests. An entityId can appear more than once in legalRepresentatives. A person holding several roles can have a separate entry for each appointment, with the same entityId and different role details or appointment dates. For example, a Belgian director can also be a member of the management committee:

Field	First entry	Second entry
`entityId`	`person_001`	`person_001`
`role.localName`	`Administrateur`	`Membre du comité de direction`
`role.englishTranslation`	`Director`	`Member of the management committee`
`role.standardized`	`Director`	`Director`

To import one record per person, group entries by entityId within the request and retain all associated roles and appointment dates. Neither entityId alone nor the combination of entityId and role.standardized is a unique key for a role entry. Different local roles can share a standardized category. If entityId is absent, do not group all entries without an ID into one person.

Choose a mode

/v2/company supports two modes:

Verification mode is the default and prioritizes authoritative data for compliance.
Onboarding mode (mode: "onboarding") prioritizes speed for form prefill and early screening.

Both modes return the same response shape. Read Verification vs onboarding mode before deciding which mode to use in a customer-facing flow.

{
  "countryCode": "DE",
  "id": "HRB123456",
  "dataPoints": ["company", "legalRepresentatives"],
  "mode": "onboarding"
}

Documents

Document retrieval is a two-step flow:

Request availableDocuments.
Pass selected document IDs in the documents array.

{
  "countryCode": "FR",
  "id": "928020932",
  "documents": ["1c932de4-4610-5506-b48d-4e62529d58e8"]
}

Document IDs are opaque and company-specific. Always discover them through availableDocuments before requesting a download. See Document retrieval.

Response lifecycle

Every request returns a request object with the current status of each datapoint and document.

{
  "request": {
    "companyId": "932884117",
    "countryCode": "FR",
    "requestId": "253299d1-e8d0-4268-945b-f175f98bc114",
    "dataPoints": ["company", "legalRepresentatives"],
    "dataStatus": {
      "dataPoints": {
        "company": {
          "status": "succeeded",
          "authoritative": true
        },
        "legalRepresentatives": {
          "status": "in_progress"
        }
      },
      "documents": {}
    }
  }
}

Status	Meaning
`succeeded`	The datapoint or document is available.
`in_progress`	Retrieval is still running. Poll again or wait for a webhook.
`enriching`	A partial result is available while enrichment continues.
`failed`	Retrieval failed. Inspect `error.code` and `error.message`.

The response may be progressive. For example, company can succeed before legalRepresentatives, documents, or ownership datapoints finish.

Not every `failed` is an outage

Two error.code values mean the datapoint is not something we return for this request, rather than something that went wrong:

`error.code`	Meaning	Example
`datapoint_not_applicable`	The datapoint does not apply to this entity.	`shareholders` for a sole trader. A natural person trading in their own name has no share capital, so the owner appears under `legalRepresentatives`.
`datapoint_not_supported`	We do not return this datapoint for this country.	`ultimateBeneficialOwners` where the country publishes no beneficial-owner register, or where we do not yet source it.

Both carry retryable: false. Handle them the way you would handle a successful “nothing to report” answer: don’t retry, don’t alert, don’t block your flow waiting for them. Filter on the code or on retryable. error.message is human-readable and safe to show your own users. To know which datapoints a country returns before you request them, see Coverage and pricing or GET /v2/pricing.

An empty list is an answer

The list-shaped fields — legalRepresentatives, otherKeyPersons, establishments, shareholders, subsidiaries, ultimateBeneficialOwners — follow one rule, in both the API response and the webhook payload:

Shape	Meaning
`[ … ]`	The records the register published.
`[]`	The datapoint succeeded and the register published no records. We looked; there is nothing there.
Key absent	The datapoint was not requested, is still running, or `failed`. Read `dataStatus.dataPoints.<name>` to tell which.

So a datapoint whose dataStatus says succeeded always carries its list. You never have to disambiguate “succeeded with nothing attached” from “never ran” — succeeded plus a missing key cannot happen.

An empty list means the register holds no such record, which is not always the same as the entity has none. Some registers only publish part of a category: the Dutch KVK, for example, registers a shareholder only when a company has a single 100% holder, so a BV with several shareholders returns shareholders: []. Country pages document these limits — see Netherlands.

Polling

Use the requestId to fetch the latest result. This is free and does not create a new billable request.

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

Poll every few seconds until the requested datapoints and documents are terminal (succeeded or failed). In production, use webhooks when possible. Branch on the status itself rather than enumerating the non-terminal ones. A poller that waits for anything other than succeeded or failed will hang if a new intermediate status is ever introduced.

PDF extract

Any request can also be returned as a single-file PDF extract, suitable for attaching to a case file or handing to a reviewer.

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

The extract renders the company profile, legal representatives, shareholders, ultimate beneficial owners, other key persons, establishments and the ownership graph — whichever of those the request asked for and received. Like polling, it is free and never billed again: it renders data the request already paid for, so you can re-download it as often as you need.

Requesting before a request has finished

By default the extract renders whatever has arrived, exactly as GET /v2/company/{requestId} returns partial results while a request is still running. A partial extract says so on its own face, so it can never be mistaken for a complete one:

The seal reads PARTIAL instead of VERIFIED.
A Data completeness section lists every requested datapoint and whether it was included, is still being retrieved, or failed — with the reason.
The X-Topograph-Data-Status response header carries complete or partial, so you can branch without opening the file.

If you would rather have an error than a partial file — for an archival export that must not be a snapshot of a half-finished request — pass requireComplete:

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

That returns 409 while any requested datapoint is still running, naming what it is waiting on:

{
  "code": "extract_data_incomplete",
  "message": "The request is still running, so the extract would be partial.",
  "pendingDataPoints": ["shareholders"]
}

Only datapoints decide completeness. Documents are delivered as separate files and never appear in the extract, so a document still downloading does not hold the PDF back.

Seal states

Seal	Meaning
`VERIFIED`	Every requested datapoint settled, from authoritative register sources.
`PARTIAL`	The request was still running when the extract was generated.
`UNVERIFIED`	A datapoint was served from a non-authoritative source — see Modes.

Viewing in a browser

The response defaults to Content-Disposition: attachment. Pass disposition=inline to render it in place instead:

GET /v2/company/{requestId}/pdf?disposition=inline

Pricing and budget controls

Topograph bills by data block and document. A 24-hour deduplication window prevents duplicate billing for the same block, company, and account. Request ID lookups are always free. Use Pricing and caching for billing mechanics and Coverage and pricing for live country-specific prices and availability.

Getting Started

Integration Guides

Core Features

Behavior & Operations

Request shape

Datapoints

Person identities and role entries

Choose a mode

Documents

Response lifecycle

Not every `failed` is an outage

An empty list is an answer

Polling

PDF extract

Requesting before a request has finished

Seal states

Viewing in a browser

Pricing and budget controls

​Request shape

​Datapoints

​Person identities and role entries

​Choose a mode

​Documents

​Response lifecycle

​Not every failed is an outage

​An empty list is an answer

​Polling

​PDF extract

​Requesting before a request has finished

​Seal states

​Viewing in a browser

​Pricing and budget controls

Request shape

Datapoints

Person identities and role entries

Choose a mode

Documents

Response lifecycle

Not every `failed` is an outage

An empty list is an answer

Polling

PDF extract

Requesting before a request has finished

Seal states

Viewing in a browser

Pricing and budget controls