KYC Links for New Clients

Instead of integrating the Client API directly to onboard and verify (KYC/KYB) individual or business clients, you can use KYC Links for a faster setup.

KYC Links support both U.S. and international customers. Once a link is generated, simply share it with your customer—allowing them to complete the KYC process through a prebuilt, hosted flow.

This approach eliminates the need to design and build your own compliance forms, enabling you to accelerate go-to-market while still meeting regulatory requirements.

1. Generate KYC Link

See API Reference

curl --request POST \
  --url https://api.sandbox.keyrails.com/api/v1/clients/kyc-links \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {{AccessToken}}'  \
  --data '{
  "firstName": "John", // required when type=individual
  "lastName": "Smith", // required when type=individual
  "businessName": "string", // required when type=business
  "email": "[email protected]",
  "type": "individual", // or "business",
  "redirectUri": "https://example.com/success" // optional
}'

Response:

{
 "id": "6fe6375a-a128-419b-b35b-ceca924a74cc", // clientId
 "firstName": "John",
 "lastName": "Smith",
 "businessName": "string",
 "kycLink": "www.kyclink.com/blah",
 "tosLink": "www.toslink.com/blah",
 "status": "NotStarted"
}

Check status:

You can check the status of your clients by using the following endpoints

Check Individual Client Status

curl --request GET \
  --url https://api.sandbox.keyrails.com/api/v1/clients/{clientId}/individual \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {{AccessToken}}'

Or check Business Client Status

curl --request GET \
  --url https://api.sandbox.keyrails.com/api/v1/clients/{clientId}/business \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {{AccessToken}}'

Webhooks Examples

Before proceeding, ensure that your webhook configuration is set up. Refer to the setup guide for detailed instructions.

Webhook types: - Identity

Client approved

{
  "tenantId": "64790ea8-f9b1-4b52-aff6-f6177bb3fcee",
  "action": "Update",
  "id": "cfc05dcb-5983-413b-8d8b-f8ef69a14787",
  "resourceId": "d8d01119-4b78-41a6-b868-0849b9ecf2ff",
  "resourceType": "Identity",
  "createdAtUtc": "0001-01-01T00:00:00",
  "changes": {
    "complianceStatus": "Approved"
  }
}

Client rejected

{
  "tenantId": "47dce736-7fe1-42f9-a317-2676733823fe",
  "action": "Update",
  "id": "fa85e3f4-99cb-46be-bbd3-4faad0bf565d",
  "resourceId": "51777f07-8b43-468f-8808-c7cb1405f254",
  "resourceType": "Identity",
  "createdAtUtc": "0001-01-01T00:00:00",
  "changes": {
    "complianceStatus": "Rejected",
    "rejectionReasons": [
      "Failed to verify proof of address",
      "Poor quality of the document"
    ]
  }
}