Skip to main content

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.

The /v2/company endpoint is the single entry point for company data. One request, one or more datapoints, one response (plus webhooks or polling for progressive updates). Use it for KYB compliance, due diligence, fraud prevention, or customer onboarding. The same endpoint supports two modes:
  • Verification (default) returns live data from the official register.
  • Onboarding (mode: "onboarding") returns the fastest available source for the requested datapoint, subject to a 10-second per-datapoint deadline.
For the tradeoffs and error codes specific to each mode, read the Verification vs Onboarding Mode page. The rest of this page covers the request/response shape that is common to both.

​
Available Data Points

When retrieving company data, you can request the following datapoints (availability varies by country):
  1. company: core company information (name, address, status, legal form, activities)
  2. legalRepresentatives: directors, managers, and signing officers
  3. otherKeyPersons: auditors, supervisory board members, and similar roles (when the register exposes them separately)
  4. establishments: branches and secondary locations
  5. shareholders: shareholder structure and ownership percentages
  6. ultimateBeneficialOwners: information about beneficial owners
  7. availableDocuments: list of available official documents (always free)
The legacy companyProfile datapoint is still supported. For billing it expands to company + legalRepresentatives; many countries still return related sections (e.g. other key persons) inside that legacy response—see the migration guide to request them explicitly. You can request multiple data points in a single request by including them in the dataPoints array: 
{
  "dataPoints": [
    "company",
    "legalRepresentatives",
    "shareholders",
    "ultimateBeneficialOwners",
    "availableDocuments"
  ]
}

​
Choosing a Mode

Add mode: "onboarding" to pick the fastest available source for every requested datapoint. Omit it (or pass mode: "verification") to get live data directly from the register. 
{
  "countryCode": "DE",
  "id": "HRB123456",
  "dataPoints": ["company", "legalRepresentatives"],
  "mode": "onboarding"
}
Both modes share the same response shape. The authoritative flag in dataStatus tells you whether the data came from the official register or from a cached/private source. In onboarding mode each datapoint has a 10-second deadline and will fail with onboarding_timeout if the fast source is slower than that. Read Verification vs Onboarding Mode for the full comparison.
Onboarding mode replaces the legacy /v2/onboarding endpoint. It supports any combination of datapoints, not just companyProfile.

​
Pricing and Deduplication

Each data block has a fixed price per country. A 24-hour deduplication window ensures that requesting the same block for the same company within 24 hours incurs no additional charge. Some documents are included at no extra cost when the corresponding data block is purchased. For example, the trade register extract is free when the company block is already purchased. For full pricing details, see Prices & Caching.

​
Retrieving Documents

You can request specific documents by passing their IDs in the documents array. Discover those IDs first through the availableDocuments datapoint, then reuse the returned IDs in a follow-up request. To understand how document URLs, signed URL refresh, and PDF post-processing behave, read the Document Retrieval Guide.

​
Understanding the Response

​
Request Object

The response includes a request object that provides metadata about your request and the status of each requested data point and document: 
{
  "request": {
    "companyId": "932884117",
    "country": "FR",
    "requestId": "request-12345",
    "dataPoints": ["company", "legalRepresentatives", "ultimateBeneficialOwners"],
    "documents": ["1c932de4-4610-5506-b48d-4e62529d58e8"],
    "dataStatus": {
      "dataPoints": {
        "company": {
          "status": "succeeded",
          "cost": 50
        },
        "legalRepresentatives": {
          "status": "succeeded",
          "cost": 50
        },
        "ultimateBeneficialOwners": {
          "status": "in_progress",
          "costMarkup": 50
        }
      },
      "documents": {
        "1c932de4-4610-5506-b48d-4e62529d58e8": {
          "status": "failed",
          "error": {
            "code": "register_unavailable",
            "message": "The local register could not be reached. Please retry later."
          }
        }
      }
    }
  }
}
The dataStatus field is particularly important as it indicates:
  • Whether data is immediately available (succeeded)
  • If retrieval is still in progress (in_progress)
  • If an intermediate AI enrichment result is available while live retrieval continues (enriching)
  • If there were any errors (failed)
Currently, error messages are generic. We are working on providing more detailed and specific error messages in future updates.

​
Asynchronous Data Retrieval

The time to availability of requested data might vary from seconds or milliseconds, to hours or days in rare cases. Nevertheless, all data retrieval is treated asynchronously. The initial response will indicate in_progress status in the dataStatus object, which will later be updated.

​
Progressive Data Delivery

Data is delivered progressively through webhooks as it becomes available. This can happen:
  1. At the data point level (e.g., company arrives before ultimateBeneficialOwners)
  2. Within a single data point (e.g., basic company info arrives before legal representatives)
Example scenario: 
// Initial response
{
  "company": {
    "id": "123456789",
    "countryCode": "FR",
    "legalName": "Topograph",
    "identifiers": {
      "siren": "123456789"
    }
  }
}

// Later webhook delivery
{
  "company": {
    "id": "123456789",
    "countryCode": "FR",
    "legalName": "Topograph",
    "identifiers": {
      "siren": "123456789"
    }
  },
  "legalRepresentatives": [
    {
      "type": "individual",
      "individual": {
        "name": { "fullName": "John Smith" }
      },
      "role": {
        "localName": "Président",
        "englishTranslation": "Director",
        "standardized": "Director"
      }
    }
  ]
}

​
Webhook Delivery

Webhooks deliver updates in a standardized format: 
{
  "data": {
    // Updated company data
  },
  "requestId": "request-12345"
}
A webhook is always delivered, even for very fast jobs, to ensure consistency in your data processing pipeline.
Webhook delivery follows the Svix retry policy to ensure reliable delivery.

​
Polling Alternative

Instead of using webhooks, you can poll the API using the requestId from the initial response: 
curl --request GET \
  --url https://api.topograph.co/v2/company/253299d1-e8d0-4268-945b-f175f98bc114 \
  --header 'x-api-key: <api-key>'
  1. Call GET /v2/company/{requestId} with the requestId from the initial response
  2. The response will contain the latest available data
  3. Data won’t be rebilled when using requestId
  4. The state will match the original request
Polling recommendations:
  • Maximum rate: 10 requests per second
  • Recommended interval: Every 3 seconds
  • Continue polling until all requested data points show succeeded or failed status
The legacy approach of polling via POST /v2/company with {"requestId": "..."} in the body still works but GET /v2/company/{requestId} is preferred.
For detailed information about our credit-based billing system and how our caching optimizes costs and performance, please see our Pricing & Caching documentation.

​
Example Request

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",
      "shareholders",
      "ultimateBeneficialOwners",
      "availableDocuments"
    ],
    "documents": [
      "1c932de4-4610-5506-b48d-4e62529d58e8"
    ]
  }'
For country-specific information on:
  • Available data points
  • Document types
  • Expected response times
Browse the Country Guides for country-specific details.