> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spherepay.co/llms.txt
> Use this file to discover all available pages before exploring further.
# Onboard Customers with a Hosted KYC Link
> Use SpherePay's hosted onboarding link to verify customers without building a custom UI. Redirect customers to complete KYC or KYB in minutes.
The hosted link integration is the fastest way to onboard customers in SpherePay. Instead of building a custom verification UI, you create a customer via the API, retrieve a hosted link, and redirect your customer to complete their full verification on a SpherePay-managed page. The hosted experience handles document upload, face liveness verification, and all required questions in a single flow.
This approach works for both individual customers (KYC) and business customers (KYB).
Use the hosted link approach for the fastest time to integration. It requires minimal frontend work — you only manage the initial API call and the redirect.
## When to use this approach
The hosted link is ideal when:
* You want to integrate quickly without building a custom onboarding UI
* You prefer to delegate document upload, liveness checks, and OTP to SpherePay
* You are prototyping or running an initial launch before investing in a fully custom flow
If you need complete control over the data collection experience or want to embed verification steps directly inside your product, use the [API-based integration](/concepts/onboarding/individual-kyc) instead.
Pick a single integration method for each customer. Do not mix the hosted link and API approaches for the same customer, or fall back to one if the other fails — this will result in an unsuccessful onboarding.
***
## How it works
1. You call `POST /v2/customer` to create a customer record with basic contact details.
2. You call the TOS link endpoint in parallel to generate a Terms of Service acceptance link.
3. You call the KYC/KYB link endpoint to generate a hosted verification link.
4. You redirect or send the link to your customer.
5. The customer completes the entire verification process on the hosted page.
6. You poll `GET /v2/customer/{id}` to detect when the verification profile reaches `approved`.
***
## Step-by-step guide
Call `POST /v2/customer` with the customer's basic contact information and address. For the hosted link path, you do not need to include `personalInformation` — the customer enters that information on the hosted page.
**For individual customers:**
```json theme={"dark"}
{
"type": "individual",
"email": "jane.smith@example.com",
"phone": "+14155550123",
"address": {
"line1": "233 South Wacker Drive",
"line2": "Suite 4700",
"city": "Chicago",
"postalCode": "60606",
"state": "IL",
"country": "USA"
}
}
```
**For business customers:**
```json theme={"dark"}
{
"type": "business",
"email": "contact@acmecorp.example.com",
"phone": "+14155551234",
"addresses": [
{
"type": "registered",
"country": "USA",
"line1": "123 Main Street",
"city": "Chicago",
"state": "IL",
"postalCode": "60601"
},
{
"type": "operating",
"country": "USA",
"line1": "456 Market Street",
"city": "Chicago",
"state": "IL",
"postalCode": "60602"
}
]
}
```
Save the `id` from the response — you'll need it in the next steps.
Generate a TOS link and redirect the customer to accept the Terms and Conditions. This step can be done in parallel with generating the KYC/KYB link.
```bash theme={"dark"}
POST https://api.spherepay.co/v2/customer/{id}/tos-link
```
Redirect the customer to the returned URL to complete TOS acceptance.
In parallel with the TOS step, generate the hosted verification link for your customer.
```bash theme={"dark"}
POST https://api.spherepay.co/v2/customer/{id}/kyc-link
```
This single endpoint works for both individual (KYC) and business (KYB) customers — SpherePay determines the correct flow based on the customer's `type`.
Once the link is generated, redirect the customer to the returned URL. The hosted experience handles:
* Document upload (ID document, proof of address)
* Face liveness verification
* OTP contact verification
* Business document upload and UBO registration (for business customers)
During the KYC/KYB flow, the customer may register a bank account. It will remain in `pending` status until their identity is fully verified and the verification profile reaches `approved`.
Redirect the customer directly from your application, or send them the link via email or SMS. The customer does not need an existing SpherePay account to complete the hosted verification.
After the customer completes the hosted flow, poll `GET /v2/customer/{id}` until `status` in `verificationProfiles` reaches `approved`.
```bash theme={"dark"}
GET https://api.spherepay.co/v2/customer/{id}
```
```json theme={"dark"}
{
"id": "customer_f31121c389624d3697cbf3ea8830b7a4",
"email": "jane.smith@example.com",
"phone": "+14155550123",
"verificationProfiles": [
{
"name": "kyc_profile_a",
"status": "approved",
"criteria": {
"complete": [
"email_address",
"phone_number",
"residential_address",
"tax_identification_number",
"identity_document",
"liveness_report_document"
],
"pending": [],
"required": [],
"errors": []
}
}
],
"createdAt": "2026-03-09T20:46:31.305Z",
"updatedAt": "2026-03-09T20:46:31.305Z",
"type": "individual"
}
```
When `required` is empty and `status` is `approved`, the customer is fully onboarded and ready to transfer.
Poll on a reasonable interval — for example, every 30 seconds — rather than continuously. You can also use webhooks if your integration supports them.
***
## What's next
Once the customer's verification profile is `approved`, register their payment methods and initiate a transfer.
Register a bank account so the customer can send or receive funds via bank rail.
Register a crypto wallet address to enable on-ramp and off-ramp transfers.
Create and manage transfers once the customer has registered their payment methods.
Understand verification statuses, criteria arrays, and what triggers state changes.