Skip to main content
POST
/
v0
/
end-users
curl -X POST 'https://api.karmapay.xyz/v0/end-users' \
  -H 'Authorization: Bearer karma_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "externalUserId": "user_123",
    "email": "user@example.com"
  }'

{
  "data": {
    "id": "770e8400-e29b-41d4-a716-446655440000",
    "externalUserId": "user_123",
    "email": "user@example.com",
    "applicantId": "custom_kyc_business_customer_id_user_123",
    "bridgeCustomerId": null,
    "createdAt": "2025-10-31T12:00:00Z"
  }
}
Authentication: Business API Key
Create a new end-user record. This is the first step in the Custom KYC onboarding flow where you handle KYC verification using your own provider (e.g., Sumsub, Persona, Onfido) and submit the data to Bridge.

​
Custom KYC Flow

1

Create end-user record

Call this endpoint with externalUserId and email
2

Generate ToS link

Use POST /v0/end-users/:externalUserId/tos-link to generate Terms of Service acceptance link
3

User accepts ToS

Direct user to the ToS link. After acceptance, you receive signed_agreement_id
4

Collect KYC data

Use your own KYC verification provider to collect and verify user identity
5

Submit KYC data

Use POST /v0/end-users/:externalUserId/submit-kyc with the signed_agreement_id and KYC data
6

Poll for approval

Use GET /v0/end-users/:externalUserId/customer-status to check endorsement status
7

Create accounts

Once approved, create virtual accounts or external accounts for the user

​
Request Body

​
externalUserId
string
required
Your internal user ID that you use to identify this end-user in your system
​
email
string
required
User’s email address

​
Response

​
data
object
curl -X POST 'https://api.karmapay.xyz/v0/end-users' \
  -H 'Authorization: Bearer karma_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "externalUserId": "user_123",
    "email": "user@example.com"
  }'

{
  "data": {
    "id": "770e8400-e29b-41d4-a716-446655440000",
    "externalUserId": "user_123",
    "email": "user@example.com",
    "applicantId": "custom_kyc_business_customer_id_user_123",
    "bridgeCustomerId": null,
    "createdAt": "2025-10-31T12:00:00Z"
  }
}
After creating the end-user, generate a ToS link using POST /v0/end-users/:externalUserId/tos-link. Once the user accepts the ToS and you receive the signed_agreement_id, submit their KYC data using POST /v0/end-users/:externalUserId/submit-kyc.