> ## 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.

# Verification vs Onboarding Mode

> When to use verification mode and when to use the faster 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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

<Warning>
  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.
</Warning>

## 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`.

```json theme={null}
{
  "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.

<Note>
  `availableDocuments` is a document listing datapoint. Its behavior depends on the country document catalog and is not simply a fast-source company-data lookup.
</Note>

## 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.

```bash theme={null}
# 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](/essentials/coverage-and-pricing) for the live matrix, or call `GET /v2/pricing?countryCode=FR` from your application.