Sign in
latestOpenAPI 3.1.0Proprietary2026-08-201536391.5 MB

4f1f6b937f93

KYC/KYB Verifications

Generate a hosted KYC/KYB link for an existing customer

Generate a single-use hosted URL the customer can complete to verify their identity, and (where supported) a provider-specific token for embedding the verification flow directly via the provider's SDK.

The customer must already exist — create them with POST /customers first. Calling this endpoint does not change the customer's verification status; the customer remains at their current status until they complete (or fail) the hosted flow.

This endpoint generates the link for both customer types; customerType selects which flow the provider runs. INDIVIDUAL runs identity verification (KYC), tracked on kycStatus. BUSINESS runs business verification (KYB), tracked on kybStatus — the flow confirms the company details, collects formation, ownership, and proof-of-address documents, and gathers the control person and every beneficial owner holding 25% or more. Business information already supplied via POST /customers or PATCH /customers/{customerId} is prefilled, so send what you have before generating the link.

The hosted link is one of two ways to verify a customer. To collect the data yourself instead, submit it through POST /customers, POST /beneficial-owners (business customers), and POST /documents, then call POST /verifications. Both paths produce the same status transitions and the same CUSTOMER.KYC_* / CUSTOMER.KYB_* webhooks.

Each call returns a fresh link. Previously-issued links are not invalidated, but they remain single-use and will expire on their own. For request-level retry safety, include an Idempotency-Key header.

post/customers/{customerId}/kyc-link

Headers

Idempotency-Keystring
Example:<uuid>

A unique identifier for the request. If the same key is sent multiple times, the server will return the same response as the first request.

Request body

redirectUristring uri

URI the customer is redirected to after completing the hosted KYC flow. Must start with https:// (or http:// for local development). Embedded in the returned kycUrl.

Example request

{
  "redirectUri": "https://app.example.com/onboarding/completed"
}

Response

KYC link generated

kycUrlstring required

Hosted URL the customer should be sent to in order to complete verification. The URL is single-use and expires at expiresAt. To generate a new link (for example, after the previous one expires or is abandoned), call this endpoint again.

expiresAtstring date-time required

Time at which the hosted link expires and can no longer be used.

provider'SUMSUB' required

The KYC provider that will perform identity verification for the customer. Grid selects the provider based on the customer's region and platform configuration; the value is informational for platforms that want to integrate directly with the provider's SDK.

tokenstring

Provider-specific token that can be used in place of the hosted URL — for example, to embed the provider's SDK directly in your application. Only returned for providers that support direct SDK integration. Whether to use the hosted URL or the embedded SDK is up to you; both flows result in the same kycStatus update on the customer.

Example response

{
  "kycUrl": "https://kyc.lightspark.com/onboard/abc123def456",
  "expiresAt": "2027-01-15T14:32:00Z",
  "provider": "SUMSUB",
  "token": "_act-sbx-jwt-eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}