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.

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.

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.

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

Choose a mode

Documents

Response lifecycle

Not every `failed` is an outage

Polling

Pricing and budget controls

​Request shape

​Datapoints

​Choose a mode

​Documents

​Response lifecycle

​Not every failed is an outage

​Polling

​Pricing and budget controls

Request shape

Datapoints

Choose a mode

Documents

Response lifecycle

Not every `failed` is an outage

Polling

Pricing and budget controls