# Token Share Onboarding

> Share pre-existing KYC data from an authorised partner organisation using a Sumsub share token, instead of verifying the customer again.

## Overview

Token share onboarding enables you to share pre-existing KYC data for a customer's onboarding session using [Sumsub token sharing](https://docs.sumsub.com/docs/reusable-kyc#how-reusable-kyc-via-api-works), requiring the CustomerID and customer verification information from authorized partner organizations to avoid duplicate verification processes.

Use the [POST `onboarding/:CustomerID/prefill`](../../../api-reference/prefill-customer-details) endpoint to prefill customer data. The endpoint leverages Noah's integration with the [Sumsub identity verification service](../../api-concepts/kyc) through triparty agreements, enabling transfer of verified applicant data via cryptographically secured tokens.

Complete the onboarding process using the [POST `onboarding/:CustomerID`](../../../api-reference/create-onboarding-session) endpoint to collect:

- Missing compliance data through dynamic forms or hosted sessions
- Terms and Conditions acceptance for regulatory compliance
- Fiat currency selection configured during hosted onboarding

**Note:** Noah automatically identifies gaps in compliance data and collects only what's missing. If email is prefilled, it won't be requested again during onboarding.

For more details on this process, see the [Hosted Onboarding](../onboarding/hosted-onboarding.md) recipe.

:::warning Scope and limitations

- **Individual customers only.** Use `SumSubToken` prefill for individual KYC. Business (KYB) onboarding does not support company-level token share. For business customers, start onboarding via [POST `onboarding/:CustomerID`](../../../api-reference/create-onboarding-session) with the appropriate customer type; optionally use [Business Customer Prefill](./business-customer-prefill.md) to pre-submit known KYB data. Prefill alone does not start onboarding—it only saves data until you create a hosted session.
- **T&Cs and gaps via hosted session.** Even when verification data is imported successfully, you must still call [POST `onboarding/:CustomerID`](../../../api-reference/create-onboarding-session) and direct the customer to the returned `HostedURL` for Terms and Conditions acceptance and any remaining compliance steps.
- **Sumsub integration required.** Token sharing requires an existing Sumsub integration and a sharing agreement between your Sumsub client and Noah.

:::

### Example Scenario

Consider a customer who has already completed KYC verification with one of Noah's partners and now wants to use your platform:

**Setup:**

- **CustomerID:** Existing verified customer from partner organization
- **Input:** Sumsub token with verified applicant data
- **Verification Status:** Identity and document checks already completed
- **Missing Data:** Platform-specific information and T&C acceptance

**Key Implementation Features:**

- Cryptographically secured token transfer of verification data
- Automatic gap identification for missing compliance requirements
- Reduced onboarding time by avoiding duplicate verification
- Dynamic form generation for platform-specific data collection

:::caution Enhanced Due Diligence (EDD)
Even after successful onboarding via token share, customers may be subject to [Enhanced Due Diligence](../../api-concepts/compliance-freezes-refunds-reversals.md#what-triggers-enhanced-due-diligence) when they begin transacting. EDD can freeze deposits until documentation is provided. Make sure your integration handles this scenario — see [Compliance Freezes, Refunds & Reversals](../../api-concepts/compliance-freezes-refunds-reversals.md) for details.
:::

## Recipe

Implement a scenario as described above by following the steps below.

<details>

<summary>1. Provide a Sumsub Token</summary>

Provide a Sumsub token via the [POST `onboarding/:CustomerID/prefill`](../../../api-reference/prefill-customer-details) endpoint, as described in [KYC Platform](../../api-concepts/kyc.md). In this step, you query the [POST `onboarding/:CustomerID/prefill`](../../../api-reference/prefill-customer-details) endpoint, selecting the `SumSubToken` type:

```typescript
curl -L 'https://api.sandbox.noah.com/v1/onboarding/:CustomerID/prefill' \
-H 'Content-Type: application/json' \
-H 'X-Api-Key: <X-Api-Key>' \
-d '{
  "Type": "SumSubToken",
  "Token": "string"
}'
```

As can be seen above, in your request, include your API Key in the header, along with a `CustomerID`.

Once compliance profiles are added to Sumsub, any missing information can be requested via [Dynamic Forms](../../api-concepts/dynamic-ui.md) and/or a dynamic Hosted Onboarding session, as defined in the next step. For details, see [KYC Platform](../../api-concepts/kyc.md).

</details>

<details>

<summary>2. Initiate a Hosted Onboarding Session</summary>

Submit a call to the [POST `onboarding/:CustomerID`](../../../api-reference/create-onboarding-session) endpoint, to collect the prerequisite Terms and Conditions acceptance from your customer (and any missing data as per the token share):

```typescript
curl -L 'https://api.sandbox.noah.com/v1/onboarding/:CustomerID' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'X-Api-Key: <X-Api-Key>' \
-d '{
  "Metadata": {},
  "ReturnURL": "https://example.com",
  "FiatOptions": [
    {
      "FiatCurrencyCode": "USD"
    }
  ]
}'
```

As can be seen above, in your request, include your API Key in the header along with a `CustomerID`, the URL to which the user is redirected at the end of the Hosted Onboarding session, and the list of fiat options to be supported by the customer.

:::note

Noah expects a full `ReturnURL` value, including the `https://`.

:::

View the [POST `onboarding/:CustomerID`](../../../api-reference/create-onboarding-session) endpoint for detailed instructions on initiating a session.

The response will consist of a `HostedURL`, where the Hosted Onboarding session is ready for the
customer to enter their details:

```typescript
{"HostedURL":"https://checkout.sandbox.noah.com/kyc?session=xyz"}
```

</details>

<details>

<summary>3. Direct the Customer to Hosted Onboarding</summary>

Redirect your customer to the `HostedURL` to enter their details in the Hosted Onboarding session.

</details>

<details>

<summary>4. Customer Status Updates via Webhooks</summary>

Set up to receive notifications through webhooks about the status of the Hosted Onboarding session,
which can be `Pending`, `Approved`, or `Declined`.

For more details, see [Customer Webhooks](../../api-concepts/webhooks/customer.md).

</details>

<details>

<summary>5. Close the Hosted Onboarding Session</summary>

Noah emits a `postMessage` once the onboarding process is complete. You can listen to this event in your application, as follows:

```typescript
window.addEventListener('message', (event) => {
  if (event.data?.type === 'kycCompleted') {
    closeHostedSession(); // <-- Replace this with platform-specific close method
  }
});
```

:::tip

- The message sent is: `{ type: 'kycCompleted' }`
- It is sent once a valid KYC review status is detected.

:::

</details>