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.

​
Credit System

Topograph uses a credit-based system. To use the API, you need to purchase credits in advance using the Topograph web app (you need to be administrator of your organization). Each data block or document request uses a specific number of credits from your balance. When your balance becomes negative, API requests will be blocked. If your account remains unfunded for 30 days after going negative, we will invoice you for the negative amount.

​
Block-Based Pricing

Topograph bills per data block. A data block is the unit of billing and corresponds to a specific category of data for a given company:
Data BlockWhat it covers
companyCore company information (name, address, status, activities)
legalRepresentativesDirectors, managers, and other legal representatives
shareholdersShareholder structure and ownership percentages
ultimateBeneficialOwnersUltimate beneficial owners (UBOs)
Each block has a fixed price per country, defined in the country manifest. One block SKU often covers several datapoints at once (for example France includes company, legalRepresentatives, otherKeyPersons, and establishments under a single company-data SKU). Company searches and lists of available documents are always free.
The legacy companyProfile datapoint maps to company + legalRepresentatives. It remains supported for backward compatibility.

​
24-Hour Deduplication

When you request a data block, that block is deduplicated within a 24-hour window per company and per account. If you (or another member of your account) request the same block for the same company within 24 hours, no new charge is incurred — the existing billing event is linked to the new request. This means you can safely make multiple requests for the same company without worrying about duplicate charges.
For high-volume operations, you can also store the requestId from your original request and use it to retrieve the same data at any time, with no additional charge. Unlike deduplication, requestId lookups are free regardless of the time elapsed.

​
Included Documents

Some documents are included at no extra cost when the corresponding data block has already been purchased (or deduplicated) within the 24-hour window. For example:
  • Trade register extract: free when the company block is purchased
  • UBO register extract: free when the ultimateBeneficialOwners block is purchased
This means that if you request company data and a trade register extract in the same call, you only pay for the data block — the document comes for free.
Document inclusion is country-specific. Check the pricing endpoint or country documentation to see which documents are included with each block.

​
Budget Cap

You can set a maxBudget (in credit cents, i.e. hundredths of a credit on your balance) on any request. The resolver includes billable blocks in this order until the budget is exhausted:
  1. Blocks that cover company (highest priority)
  2. Blocks that cover legalRepresentatives
  3. Blocks that cover ultimateBeneficialOwners
  4. Blocks that cover shareholders (lowest priority)
Datapoints outside those blocks (for example otherKeyPersons or establishments) are not part of this priority list. Blocks that exceed the remaining budget are omitted; the response’s dataStatus shows budget_exceeded for the affected datapoints, while fulfilled datapoints complete normally. 
{
  "countryCode": "FR",
  "id": "932884117",
  "dataPoints": ["company", "ultimateBeneficialOwners", "shareholders"],
  "maxBudget": 150
}
In this example with France pricing (company: 50, UBOs: 50, shareholders: 200):
  • company (50) fits → fulfilled
  • ultimateBeneficialOwners (50) fits → fulfilled
  • shareholders (200) exceeds remaining 50 → dropped
If no blocks fit within the budget, the request fails with an insufficient budget error.

​
Retrieving Prices

You can retrieve Topograph unit prices for a specific country using the pricing endpoint. Use cases include:
  • Understanding the price of each data block before making requests
  • Displaying price information to end-users
  • Budgeting and planning purposes

​
Endpoint

GET https://api.topograph.co/v2/pricing?countryCode=FR

​
Request Parameters

ParameterTypeRequiredDescription
countryCodestringYesISO 3166-1 alpha-2 country code (e.g., “FR”)

​
Example Request

curl --request GET \
  --url 'https://api.topograph.co/v2/pricing?countryCode=FR' \
  --header 'x-api-key: <api-key>'

​
Example Response

The payload has two layers:
  1. blocks — indivisible billing units for the country: SKU, which datapoints each block covers, per-mode prices (verification vs onboarding) with an authoritative hint, and optional includedDocuments (document types included when that block is purchased).
  2. Flat fields — per-datapoint availability and verification-mode price for quick lookups, plus legacy companyProfile (maps to the company + legal representatives block).
{
  "blocks": [
    {
      "sku": "fra-company-data",
      "datapoints": [
        "company",
        "legalRepresentatives",
        "otherKeyPersons",
        "establishments"
      ],
      "modes": {
        "verification": { "price": 0.5, "authoritative": true },
        "onboarding": { "price": 0.5, "authoritative": true }
      }
    },
    {
      "sku": "fra-shareholders",
      "datapoints": ["shareholders"],
      "modes": {
        "verification": { "price": 2.0, "authoritative": true },
        "onboarding": null
      }
    },
    {
      "sku": "fra-ubo-data",
      "datapoints": ["ultimateBeneficialOwners"],
      "modes": {
        "verification": { "price": 0.5, "authoritative": true },
        "onboarding": { "price": 0.5, "authoritative": true }
      }
    }
  ],
  "company": { "available": true, "price": 0.5 },
  "legalRepresentatives": { "available": true, "price": 0 },
  "shareholders": { "available": true, "price": 2.0 },
  "ultimateBeneficialOwners": { "available": true, "price": 0.5 },
  "companyProfile": { "available": true, "price": 0.5 },
  "availableDocuments": { "available": true, "price": 0 }
}
Illustrative values for France (countryCode=FR): one paid company block covers company, legalRepresentatives, otherKeyPersons, and establishments together, so the flat legalRepresentatives.price is often 0 (no separate line item). Shapes vary by country. Some responses include includedDocuments on a block (document type enums bundled with that block when the catalog defines them).
  • available: Whether that datapoint (or legacy bundle) can be requested for the country.
  • price: Cost in credits for the verification-style line item (same numeric units as on your balance; onboarding may differ—use blocks[].modes.onboarding).
  • pricingMode: May be fixed or variable when the price is not known until request time (omitted when fixed).
Credit rates may vary based on your subscription plan. Use blocks when you need onboarding prices or included document metadata per SKU.

​
Best Practices

Use the /v2/pricing endpoint to understand the cost of each data block for a given country before making requests.
Request data blocks freely within a 24-hour window for the same company — you will only be charged once per block.
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.
Request documents alongside their corresponding data blocks in the same call to take advantage of included documents at no extra cost.

​
Enterprise Solutions

For high-volume usage, custom solutions are available with custom pricing plans, custom cache periods and dedicated implementation support. Contact sales@topograph.co to discuss your needs.