---
url: /docs/learn/onboarding-links.md
description: >-
  Generate a hosted link so individuals and businesses complete KYC or KYB on a
  BlindPay page and become customers of your instance, without building the form
  yourself.
---

An onboarding link sends an individual or a business to a hosted BlindPay page where they fill in their own KYC or KYB data, upload their documents and accept the terms of service. When they submit, BlindPay creates the [customer](/docs/learn/customers) on your instance, exactly as if you had called the create customer endpoint yourself.

Use onboarding links when you don't want to collect identity data and documents in your own product, or when you onboard people outside your app (for example by email or chat).

## How it works

1. Your server requests an invite token for the customer type and KYC level you need.
2. You build the onboarding link with that token and share it, or embed it in your site.
3. The person opens the link, fills in the form, uploads their documents and accepts the terms of service on the same page. You don't need a `tos_id`.
4. BlindPay creates the customer, emits a `customer.new` [webhook](/docs/learn/webhooks-events) and starts the review. Status changes arrive as `customer.update` webhooks, the same as any other customer.
5. If you set a redirect URL, the person is sent there after submitting. Otherwise the page shows a confirmation message.

The hosted page shows your business name and branding from the instance's business profile.

## Prerequisites

## Generate an invite token

```bash [cURL]
curl --request POST \
  --url https://api.blindpay.com/v1/instances/in_000000000000/external-customer-token \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "individual",
    "kyc_type": "standard"
  }'
```

| Field | Required | Description |
| --- | --- | --- |
| `type` | Yes | `individual` or `business`. Decides which form the hosted page shows. |
| `kyc_type` | Yes | `standard` or `enhanced`. Businesses use `standard`. See [KYC requirements](/docs/kb/kyc) for what each level collects. |

Response:

```json
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

The token is valid for **7 days**. After that the page shows "Invite link not working" and you need to generate a new one.

## Build the onboarding link

Add the token and the same `type` and `kyc_type` you used to generate it to the hosted page URL:

```text
https://app.blindpay.com/e/customers/invite?instanceId=in_000000000000&type=individual&kyc_type=standard&token=<token>
```

| Query parameter | Required | Description |
| --- | --- | --- |
| `instanceId` | Yes | Your instance ID. Must match the instance the token was generated for. |
| `type` | Yes | Must match the `type` in the token. |
| `kyc_type` | Yes | Must match the `kyc_type` in the token. |
| `token` | Yes | The token from the previous step. |
| `email` | No | Prefills the email and locks the field, so the customer is created with the address you already know. |
| `external_id` | No | Your own identifier for this person. It is saved on the customer, so you can match the `customer.new` webhook to the user in your system. |

A token is not single use. Anyone holding the link can submit the form until it expires, and every submission creates a new customer on your instance. Generate a token per person or per campaign, share links privately, and pass `external_id` so you can tell submissions apart.

If `instanceId`, `type` or `kyc_type` in the URL don't match the token, the submission is rejected with `invalid_token`. An expired or tampered token is rejected with `invalid_or_expired_token`.

## Redirect after submission

Set `customer_invite_redirect_url` on the instance to send people back to your product once they submit. It applies to every onboarding link of the instance.

```bash [cURL]
curl --request PUT \
  --url https://api.blindpay.com/v1/instances/in_000000000000 \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "customer_invite_redirect_url": "https://example.com/onboarding/done"
  }'
```

The redirect does not carry the customer ID. Use the `customer.new` webhook (and the `external_id` you passed in the link) to know which customer was created.

You can also set the redirect URL in the dashboard, in the same dialog used to generate links.

## Generate a link from the dashboard

If you don't need to automate it, open **Customers** in the dashboard, open the create menu and choose **Invite link**. Pick the customer type and KYC level, click **Generate link** and copy it. The dashboard calls the same endpoint, so the link behaves the same way and also expires in 7 days.

## Embed the page

The onboarding page can be rendered in an iframe only from the website set in your instance's business profile and its subdomains. Every other origin is blocked by the browser. If you embed from a different domain, update the website in your business profile first.

## Track the customer

The customer created from an onboarding link is a regular customer:

* Listen for `customer.new` and `customer.update` [webhooks](/docs/learn/webhooks-events) to follow the KYC status.
* [Retrieve](/docs/learn/customers#retrieve-a-customer) or [list](/docs/learn/customers#list-customers) customers through the API as usual.
* If BlindPay needs more information, use [RFI](/docs/learn/rfi) to request it.

### Testing scenarios

Customers created in `development` instances are approved automatically, including those created from onboarding links. To test a rejection, use `Fail` as the first name (individuals) or legal name (businesses) on the hosted form.

## Related

* [Customers](/docs/learn/customers) · [Terms of Service](/docs/learn/terms-of-service) · [RFI](/docs/learn/rfi)
* [KYC requirements](/docs/kb/kyc) · [KYB documents](/docs/kb/kyb-documents) · [Webhook events](/docs/learn/webhooks-events)