> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trusset.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Start Onboarding

> Start or resume the onboarding of one customer

Starts the onboarding of a customer, or returns the one that is already running. Call it from your backend when the customer begins verification in your app. The same call is safe to repeat: it never opens a second identity check for a customer whose check is still open.

For the `TRUSSET` provider the answer carries `sdk.token`, which your app passes to the Sumsub WebSDK or MobileSDK. For a `KYC_SOURCE` it names the source the record is expected from. See [Onboarding](https://docs.trusset.org/endpoints/customers/onboarding.md) for the whole path.

## Who the customer is

Name the customer with one of `customerId`, `referenceKey`, `externalId` or `walletAddress`. They are tried in that order.

An `externalId` or a wallet that matches no customer creates the customer record, with the profile, the country and the wallet you send. A `customerId` or `referenceKey` that matches nothing is refused with `404 CUSTOMER_NOT_FOUND`. The record is written only once the profile, the country and the provider are accepted, so a start refused for one of them leaves nothing behind.

A wallet held by an archived customer record of your instance, as its primary or as a linked wallet, is refused with `409 WALLET_IN_USE`, as on [Bind Wallet](https://docs.trusset.org/endpoints/customers/bind-onboarding-wallet.md): restore that record, or bind another wallet. The start does not restore the archived record.

A new customer whose wallet your instance already verified on its register starts as `verified`, and the onboarding answers `COMPLETED` without a check.

## Body Parameters

**customerId** `string`

The `id` of an existing customer.

**referenceKey** `string`

The reference key of an existing customer, `ref_...`.

**externalId** `string`

Your own ID for the customer: a string of 1 to 128 characters with no leading or trailing spaces and no control or invisible characters, such as a zero-width space or a line break. Created when it is new. It must not look like a wallet address (`0x` followed by 40 hex characters) or start with `ref_`, because the `/:customer` routes read such an identifier as a wallet or a reference key, and a new one must not be the ID of a customer record of your instance, because those routes try an identifier as a record ID first. Each is refused with `400 INVALID_INPUT` and `error.details.field: "externalId"`. A 40-character hex value without `0x` is not a wallet address and is accepted. [Create Customer](https://docs.trusset.org/endpoints/customers/create.md) applies the same rule.

**walletAddress** `string`

The customer's wallet. It is bound at the start when the customer has none, under the rules of [Bind Wallet](https://docs.trusset.org/endpoints/customers/bind-onboarding-wallet.md). A customer who already holds another wallet is refused with `409 CUSTOMER_WALLET_MISMATCH`, and a wallet held by an archived customer record with `409 WALLET_IN_USE`.

**profile** `string`

The `key` of an enabled [verification profile](https://docs.trusset.org/endpoints/customers/list-verification-profiles.md), matched exactly. `investorType` is accepted as another name for it. Defaults to the profile of the running onboarding, then to the customer's investor type, then to `RETAIL`.

**country** `string`

ISO 3166-1 alpha-2, alpha-3 or numeric. A country the profile blocks is refused with `403 COUNTRY_BLOCKED` before anything is created. Defaults to the customer's country.

**provider** `string`

`TRUSSET` or `KYC_SOURCE`. Without it, a running onboarding keeps its provider, a profile with an active KYC source uses that source, and every other profile uses `TRUSSET`.

**sourceId** `string`

The KYC source to go through. It implies `provider: KYC_SOURCE`. Required when several active sources verify for the profile (`400 SOURCE_REQUIRED`, with the sources in `error.details.sources`).

**company** `object`

For a profile whose `entityType` is `COMPANY`: `name` and `registrationNumber`, both strings. They pre-fill the company applicant, and `name` names a customer record created by this call.

**restart** `boolean` (default: false)

Replaces a running onboarding that can still be replaced, or runs a new check for a customer who is `COMPLETED` or `REJECTED`. See [What a start replaces](https://docs.trusset.org/endpoints/customers/onboarding.md#what-a-start-replaces).

**expiryDays** `integer` (default: 30)

Days the identity check stays open, from 1 to 365. Used by the `TRUSSET` provider only.

## Response Fields

The call answers `201` when it started something and `200` when it returned an onboarding as it was. Every answer carries `Cache-Control: no-store`, because it can carry an applicant access token.

**data** `object`

**created** `boolean`

`true` only when this call inserted the customer record. A start that found the record, because a concurrent start created it a moment earlier for example, answers `false`.

**started** `boolean`

`true` when a new identity check was opened or a new wait for a record began.

**providerReason** `string`

`REQUESTED` when you named the provider, `PROFILE_SOURCE` when the profile's KYC source decided, `DEFAULT` for the Trusset check, `RESUMED` when a running onboarding was returned.

**onboarding** `object`

The onboarding. [Get Onboarding](https://docs.trusset.org/endpoints/customers/get-onboarding.md#response-fields) describes every field.

**sdk** `object`

The Sumsub access token, present while the status is `IDENTITY_CHECK` or `RESUBMISSION`, otherwise `null`: `token`, `expiresInSeconds` (`1200`), `levelName` and `applicantType`.

**sdkError** `object`

Present only when the onboarding stands but no token could be issued just now: `code` and `message`. [Issue SDK Token](https://docs.trusset.org/endpoints/customers/issue-onboarding-token.md) retries it.

**warnings** `array`

Present only when the applicant could not be created in advance. The check still opens.

```bash cURL theme={null}
curl -X POST "https://api.trusset.org/customers/api/onboarding" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: trusset_your_key_here" \
  -d '{
    "externalId": "client-48213",
    "profile": "RETAIL",
    "country": "DE"
  }'
```

```typescript TypeScript theme={null}
const response = await fetch('https://api.trusset.org/customers/api/onboarding', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'trusset_your_key_here'
  },
  body: JSON.stringify({ externalId: 'client-48213', profile: 'RETAIL', country: 'DE' })
});
const { success, data, error } = await response.json();
if (!success) throw new Error(`${error.code}: ${error.message}`);
const accessToken = data.sdk?.token;
```

```json Started theme={null}
{
  "success": true,
  "data": {
    "created": true,
    "started": true,
    "providerReason": "DEFAULT",
    "onboarding": {
      "customerId": "cmwgx2e5l000giinmq96qvnzr",
      "externalId": "client-48213",
      "referenceKey": "ref_35453b0bf8faf7a3c9abffea18eb235b",
      "walletAddress": null,
      "profile": { "key": "RETAIL", "name": "Retail", "entityType": "INDIVIDUAL", "professionalOnly": false },
      "country": "DEU",
      "provider": "TRUSSET",
      "status": "IDENTITY_CHECK",
      "reason": null,
      "nextAction": {
        "type": "RUN_IDENTITY_CHECK",
        "actor": "CUSTOMER",
        "method": "POST",
        "endpoint": "/customers/api/onboarding/cmwgx2e5l000giinmq96qvnzr/token",
        "message": "Run the identity check in your app: request a token and pass it to the Sumsub WebSDK or MobileSDK."
      },
      "identityCheck": {
        "provider": "SUMSUB",
        "linkId": "cmwgx2e5t000kiinmzg44d012",
        "applicantType": "individual",
        "review": { "status": null, "answer": null, "rejectLabels": null },
        "expiresAt": "2026-12-14T21:27:22.671Z",
        "hostedUrl": "https://verify.trusset.org/link/3dce38cd5aa5f829fa461074d82ccfc58ed20a0cbd95b5dd04a1a66280a4beb6"
      },
      "kycSource": null,
      "kycRecord": null,
      "registration": null,
      "registrationSkipped": null,
      "admissions": [],
      "customerStatus": "pending",
      "verifiedAt": null,
      "startedAt": "2026-11-14T21:27:22.676Z"
    },
    "sdk": {
      "token": "_act-sbx-jwt-eyJhbGciOiJub25lIn0...",
      "expiresInSeconds": 1200,
      "levelName": "basic-kyc-level",
      "applicantType": "individual"
    }
  },
  "error": null,
  "metadata": {
    "requestId": "a0062f94-1284-4eec-bf64-f7016ac90790",
    "timestamp": "2026-11-14T21:27:22.683Z"
  }
}
```

```json Error - In Progress theme={null}
{
  "success": false,
  "data": null,
  "error": {
    "code": "ONBOARDING_IN_PROGRESS",
    "message": "This customer has an onboarding that is IN_REVIEW under the RETAIL profile. Send restart: true to replace it with this one, or cancel it first.",
    "details": { "status": "IN_REVIEW", "provider": "TRUSSET", "profileKey": "RETAIL" }
  },
  "metadata": {
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "timestamp": "2026-11-14T21:31:02.000Z"
  }
}
```

## Error Codes

| Code | HTTP | Cause |
| - | - | - |
| `MISSING_IDENTIFIER` | `400` | No `customerId`, `referenceKey`, `externalId` or `walletAddress` |
| `INVALID_INPUT` | `400` | A field has the wrong type or length, `sourceId` was sent with `provider: TRUSSET`, or `externalId` has leading or trailing spaces or a control or invisible character, looks like a wallet address, starts with `ref_` or is the ID of a customer record of your instance (`error.details.field: "externalId"`) |
| `INVALID_ADDRESS` | `400` | `walletAddress` is not a 42-character `0x` address, or is the zero address |
| `INVALID_COUNTRY` | `400` | `country` is not an ISO 3166-1 code |
| `INVALID_PROVIDER` | `400` | `provider` is neither `TRUSSET` nor `KYC_SOURCE` |
| `INVALID_INVESTOR_TYPE` | `400` | `profile` is not the key of an enabled profile of your instance |
| `INVALID_EXPIRY` | `400` | `expiryDays` is not a whole number from 1 to 365 |
| `SOURCE_REQUIRED` | `400` | Several active KYC sources verify for the profile and none was named |
| `COUNTRY_BLOCKED` | `403` | The profile blocks the country |
| `CUSTOMER_NOT_FOUND` | `404` | No customer has this `customerId` or `referenceKey` |
| `SOURCE_NOT_FOUND` | `404` | No KYC source of your instance has this `sourceId` |
| `CUSTOMER_EXISTS` | `409` | The `externalId` is new, but the wallet belongs to another customer |
| `CUSTOMER_WALLET_MISMATCH` | `409` | The customer already holds another wallet |
| `WALLET_IN_USE` | `409` | The wallet belongs to another customer of your instance, an archived one included, as its primary or as a linked wallet. Restore that record, or bind another wallet |
| `ONBOARDING_IN_PROGRESS` | `409` | An onboarding is running that this start would replace. `error.details` carries its `status`, `provider` and `profileKey` |
| `RESTART_REQUIRED` | `409` | The customer is settled under another profile or provider. Send `restart: true` |
| `KYC_SOURCE_NOT_CONFIGURED` | `409` | `provider: KYC_SOURCE`, and no active source verifies for the profile |
| `SOURCE_PROFILE_MISMATCH` | `409` | The source verifies for another profile |
| `SOURCE_PAUSED` | `409` | The named source is paused |
| `SOURCE_UNAVAILABLE` | `409` | The source a running onboarding goes through is paused or removed |
| `RECIPIENT_KEY_NOT_SET` | `409` | `KYC_SOURCE`, and your instance has no [record key](https://docs.trusset.org/endpoints/customers/set-kyc-record-key.md) |
| `SEALED_KYC_NOT_ENABLED` | `409` | `KYC_SOURCE` on a production instance that sealed KYC records are not enabled for |
| `SUMSUB_LEVEL_UNKNOWN` | `409` | The profile names a Sumsub level that does not exist. Correct it in the Issuer Portal |
| `RATE_LIMIT_EXCEEDED` | `429` | More than 120 onboarding writes in the minute |
| `ONBOARDING_START_FAILED` | `500` | The start failed on the server |
| `KYC_UNAVAILABLE` | `503` | The Trusset identity check is not available. Retry shortly |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.