Skip to main content
Every /v2/company request runs in either verification mode or onboarding mode. The mode changes the product tradeoff: verification prioritizes authoritative data, while onboarding prioritizes fast responses for form prefill.

​
At a glance

QuestionVerificationOnboarding
Default?Yes. Omit mode or pass "verification".No. Pass mode: "onboarding".
Best forFinal KYB checks, compliance review, due diligence.Sign-up forms, prefill, early screening, conversion-sensitive flows.
Data sourceAuthoritative official sources for the requested datapoint.The fastest compatible source for the requested datapoint. It may be authoritative or non-authoritative depending on country.
SpeedCan take seconds, minutes, or longer for slow registers.Has a 10-second deadline per datapoint.
CompletenessOptimized for eventual completeness.Optimized for speed. Unsupported or slow datapoints fail quickly.
How to inspect resultCheck request.dataStatus.dataPoints[datapoint].authoritative.Same. If authoritative: false, follow up with verification before final decisions.

​
Verification mode

Verification is the default. Use it when you need data that can support a compliance decision. 
{
  "countryCode": "IT",
  "id": "00484960588",
  "dataPoints": ["company", "legalRepresentatives"]
}
Verification reflects what the relevant official source records at retrieval time. Register data can still lag filings or reflect local legal conventions, so treat it as authoritative register data, not a guarantee that every real-world fact changed at the same time.

​
Onboarding mode

Onboarding mode is for fast customer-facing flows. It helps you prefill forms and run early checks without making every prospect wait for slower register retrieval. 
{
  "countryCode": "IT",
  "id": "00484960588",
  "dataPoints": ["company", "legalRepresentatives"],
  "mode": "onboarding"
}
Onboarding may use the same official source as verification when that source is fast enough. In other countries it may use a faster non-authoritative source. Always inspect the authoritative flag before using the response for final verification.
Onboarding is not a shortcut for compliance. Use it to reduce friction early in the flow, then verify when the customer reaches a decision point.

​
Timeouts and unsupported datapoints

Onboarding mode applies a 10-second deadline to each requested datapoint. If a datapoint cannot finish in time, it fails with onboarding_timeout. If the country has no fast source for that datapoint, it fails with fast_source_unavailable. 
{
  "request": {
    "dataStatus": {
      "dataPoints": {
        "company": {
          "status": "succeeded",
          "authoritative": true
        },
        "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. Retry without mode: "onboarding" when you need the slower verification path.
availableDocuments is a document listing datapoint. Its behavior depends on the country document catalog and is not simply a fast-source company-data lookup.

​
Staged KYB flow

A common integration pattern is:
  1. Search for the company.
  2. Request company and legalRepresentatives with mode: "onboarding" to prefill the form.
  3. Let the customer confirm or correct the prefilled fields.
  4. Request verification data and documents before final approval.
  5. Use webhooks or polling to process slower verification results.
# Step 1: fast prefill
curl -X POST https://api.topograph.co/v2/company \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: <key>' \
  -d '{
    "countryCode": "IT",
    "id": "00484960588",
    "dataPoints": ["company", "legalRepresentatives"],
    "mode": "onboarding"
  }'

# Step 2: authoritative verification
curl -X POST https://api.topograph.co/v2/company \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: <key>' \
  -d '{
    "countryCode": "IT",
    "id": "00484960588",
    "dataPoints": ["company", "legalRepresentatives", "shareholders", "availableDocuments"]
  }'

​
Country availability

Mode availability is country-specific. Some countries use the same authoritative source in both modes; others have a faster onboarding source with fewer fields; some datapoints are verification-only. Use Coverage and pricing for the live matrix, or call GET /v2/pricing?countryCode=FR from your application.