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.

Topograph prices are country-specific and can change as coverage evolves. Use Coverage and pricing for the live human-readable catalog and GET /v2/pricing for application logic.

Live pricing catalog

View current country coverage, data block availability, document coverage, sources, and prices.

​
How billing works

Topograph bills by data block and document. A data block is the smallest billable unit for structured data in a country. A block can cover one or more datapoints, depending on how that country’s sources are packaged. Common datapoints include:
  • company
  • legalRepresentatives
  • otherKeyPersons
  • establishments
  • shareholders
  • subsidiaries
  • ultimateBeneficialOwners
  • availableDocuments
  • graph
Search and request-result polling by requestId are not billed as new company data requests. availableDocuments lists document metadata; document downloads are billed only when you request specific document IDs.

​
24-hour deduplication

When you request the same billable block for the same company within 24 hours, Topograph deduplicates the charge for your account. The later request links to the previous billing event rather than creating a duplicate charge. This matters for multi-step flows: you can request company first, then request documents or additional datapoints later without accidentally rebilling blocks that were already covered inside the deduplication window.
Store requestId values. GET /v2/company/{requestId} retrieves the latest result and refreshes signed document URLs without starting a new billable request.

​
Included documents

Some official documents are included when a matching data block has already been requested or deduplicated. Inclusion is country-specific and document-specific. Use the live pricing page or GET /v2/pricing to know whether a document is included with a block or billed standalone.

​
Budget caps

Use maxBudget to cap total spend for a /v2/company request. If not every requested block fits, Topograph prioritizes blocks in this order:
  1. Blocks that cover company (highest priority)
  2. Blocks that cover legalRepresentatives
  3. Blocks that cover ultimateBeneficialOwners
  4. Blocks that cover shareholders
  5. Blocks that cover subsidiaries
Blocks that exceed the remaining budget are omitted or marked as failed with budget_exceeded, while fulfilled datapoints continue normally. 
{
  "countryCode": "FR",
  "id": "932884117",
  "dataPoints": ["company", "ultimateBeneficialOwners", "shareholders"],
  "maxBudget": 200
}
Use GET /v2/pricing before submitting budget-capped requests when your application needs to predict which blocks will fit.

​
Retrieve pricing programmatically

Use GET /v2/pricing to retrieve country-specific availability and pricing in your application. 
curl --request GET \
  --url 'https://api.topograph.co/v2/pricing?countryCode=FR' \
  --header 'x-api-key: <api-key>'
The response includes:
  • Data blocks and the datapoints each block covers.
  • Mode availability for verification and onboarding.
  • Whether a mode is authoritative.
  • Included document metadata.
  • Flat per-datapoint availability for quick lookups.
  • Variable-pricing markers when final document or register costs are known only at request time.

​
Best Practices

Use the live pricing page for human review and /v2/pricing for runtime decisions.
Split requests across your flow when useful. Duplicate covered blocks within the deduplication window are not charged again.
Always store the requestId from your requests. You can use it to retrieve the same data later at no additional cost, regardless of when you make the follow-up request.
When a document is included with a data block, requesting them together can simplify your flow.

​
Account billing

Manage credits, payment methods, and invoices from the Topograph dashboard. For custom plans or high-volume usage, contact support.