Verification vs Onboarding Mode

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

Question	Verification	Onboarding
Default?	Yes. Omit `mode` or pass `"verification"`.	No. Pass `mode: "onboarding"`.
Best for	Final KYB checks, compliance review, due diligence.	Sign-up forms, prefill, early screening, conversion-sensitive flows.
Data source	Authoritative official sources for the requested datapoint.	The fastest compatible source for the requested datapoint. It may be authoritative or non-authoritative depending on country.
Speed	Can take seconds, minutes, or longer for slow registers.	Has a 10-second deadline per datapoint.
Completeness	Optimized for eventual completeness.	Optimized for speed. Unsupported or slow datapoints fail quickly.
How to inspect result	Check `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.

The graph datapoint is verification-only. Traversing an ownership graph fans out live register lookups node by node, which cannot complete within the onboarding deadline, so graph always fails with fast_source_unavailable in onboarding mode. Nothing is fetched and nothing is billed. Request it with the default verification mode.

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:

Search for the company.
Request company and legalRepresentatives with mode: "onboarding" to prefill the form.
Let the customer confirm or correct the prefilled fields.
Request verification data and documents before final approval.
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.

Getting Started

Integration Guides

Core Features

Behavior & Operations

Verification vs Onboarding Mode

At a glance

Verification mode

Onboarding mode

Timeouts and unsupported datapoints

Staged KYB flow

Country availability

​At a glance

​Verification mode

​Onboarding mode

​Timeouts and unsupported datapoints

​Staged KYB flow

​Country availability

At a glance

Verification mode

Onboarding mode

Timeouts and unsupported datapoints

Staged KYB flow

Country availability