Skip to main content
Every data request operates in one of two modes. The mode determines which data source is selected.

​
Modes

​
Verification (default)

Verification is the default request mode. It uses only authoritative sources: live data retrieved directly from the official register for the requested datapoints. It reflects the current state recorded at the register at retrieval time. Registers can lag filings or contain legal fictions, so authoritative data can still differ from the day-to-day reality of the company. 
{
  "countryCode": "IT",
  "id": "00484960588",
  "dataPoints": ["company", "legalRepresentatives"]
}
No mode parameter needed — verification is the default.

​
Onboarding

Onboarding optimizes for fast, lower-cost retrieval. Use it for form prefill, initial screening, and onboarding flows. It will often use the same source as verification when that source is also fast. Depending on the country, Topograph may return data from cache or from a private source instead, which means the result can be non-authoritative. Onboarding never falls back to a slower standard source. If no fast source exists for a requested datapoint, that datapoint fails with fast_source_unavailable. 
{
  "countryCode": "IT",
  "id": "00484960588",
  "dataPoints": ["company", "legalRepresentatives"],
  "mode": "onboarding"
}
If a requested datapoint has no fast source in onboarding mode, that datapoint is marked as failed in dataStatus with error code fast_source_unavailable: 
{
  "request": {
    "dataStatus": {
      "dataPoints": {
        "shareholders": {
          "status": "failed",
          "error": {
            "code": "fast_source_unavailable",
            "message": "No fast source is available for this datapoint in onboarding mode. Retry without onboarding mode or request a different datapoint."
          }
        }
      }
    }
  }
}
Other datapoints in the same request can still succeed if they have a compatible fast source. You can combine onboarding mode with maxBudget to cap spend. When the budget does not cover every requested block, Topograph includes blocks in this order (matching billable data blocks): company, legalRepresentatives, ultimateBeneficialOwners, then shareholders. Datapoints tied to blocks that do not fit are marked as failed in dataStatus with error code budget_exceeded. Separate datapoints such as otherKeyPersons or establishments are outside this block resolver; request them explicitly when needed.

​
How Sources Are Selected

Each country has one or more data sources for company data. Each source has three properties:
PropertyDescription
AuthoritativeLive data sourced directly from the official register
FastData is available within seconds
PriceCost in credits per request
The mode determines the selection logic:
ModeLogic
VerificationOnly authoritative (live register) sources for the requested datapoint.
OnboardingUse the fastest and cheapest compatible fast source for the requested datapoint. If none exists, return fast_source_unavailable.
availableDocuments is an exception to the onboarding routing above. Document listing does not use the fast-only company-data selection logic and still follows the country-specific implementation for that datapoint.

​
Knowing What You Got

The response includes an authoritative flag in dataStatus so you always know whether the data came live from the register: 
{
  "request": {
    "dataStatus": {
      "dataPoints": {
        "company": {
          "status": "succeeded",
          "authoritative": true
        },
        "legalRepresentatives": {
          "status": "succeeded",
          "authoritative": true
        }
      }
    }
  }
}
Use the authoritative flag to decide whether to show a “verified” badge in your UI or whether to trigger a follow-up request.

​
Country Examples

CountryVerificationOnboarding
FranceUses live register data. authoritative: true.Uses the same live register source. authoritative: true.
ItalyUses live register data. authoritative: true.Uses a private source. authoritative: false.
GermanyUses live register data. authoritative: true.Uses cached data. authoritative: false.

​
Staged Verification Flow

A common pattern: start with onboarding for instant qualification. If onboarding returns authoritative: false in dataStatus, make a follow-up verification request. 
# Step 1: Onboarding — instant, cheap
curl -X POST https://api.topograph.co/v2/company \
  -H 'x-api-key: <key>' \
  -d '{
    "countryCode": "IT",
    "id": "00484960588",
    "dataPoints": ["company", "legalRepresentatives"],
    "mode": "onboarding"
  }'

# Step 2: Verification — live register data
curl -X POST https://api.topograph.co/v2/company \
  -H 'x-api-key: <key>' \
  -d '{
    "countryCode": "IT",
    "id": "00484960588",
    "dataPoints": ["company", "legalRepresentatives", "shareholders"]
  }'
Use the returned authoritative flags in dataStatus to decide whether you need the verification follow-up at all.