Company Data

How to request company data from public registers via /v2/company

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:

1. Request availableDocuments.
2. 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.

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.

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.