> ## Documentation Index
> Fetch the complete documentation index at: https://docs.topograph.co/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`.

<Info>
  For live country coverage, data block availability, pricing, sources, identifiers, and document catalogs, see [Coverage and pricing](/essentials/coverage-and-pricing).
</Info>

## Request shape

```bash theme={null}
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](/essentials/ownership-graph).                       |

The legacy `companyProfile` datapoint is still accepted for existing integrations. New integrations should request explicit datapoints. See the [migration guide](/guides/migration-data-product-model).

## 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](/essentials/modes) before deciding which mode to use in a customer-facing flow.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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](/essentials/document-guide).

## Response lifecycle

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

```json theme={null}
{
  "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](/essentials/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.

```bash theme={null}
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](/guides/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](/essentials/pricing-and-caching) for billing mechanics and [Coverage and pricing](/essentials/coverage-and-pricing) for live country-specific prices and availability.