Skip to main content
POST
https://api.karmapay.xyz/v0
/
v0
/
end-users
/
:externalUserId
/
submit-kyc
curl -X POST 'https://api.karmapay.xyz/v0/end-users/user_123/submit-kyc' \
  -H 'Authorization: Bearer karma_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "individual",
    "first_name": "John",
    "last_name": "Doe",
    "email": "[email protected]",
    "residential_address": {
      "street_line_1": "123 Main St",
      "city": "San Francisco",
      "subdivision": "CA",
      "postal_code": "94102",
      "country": "USA"
    },
    "birth_date": "1990-01-15",
    "signed_agreement_id": "agmt_xxx",
    "identifying_information": [
      {
        "type": "ssn",
        "issuing_country": "usa",
        "number": "123-45-6789"
      },
      {
        "type": "drivers_license",
        "issuing_country": "usa",
        "number": "D1234567",
        "image_front": "data:image/png;base64,...",
        "image_back": "data:image/png;base64,..."
      }
    ]
  }'

{
  "data": {
    "id": "770e8400-e29b-41d4-a716-446655440000",
    "externalUserId": "user_123",
    "email": "[email protected]",
    "applicantId": "custom_kyc_business_customer_id_user_123",
    "bridgeCustomerId": "cus_1234567890abcdef",
    "createdAt": "2025-10-31T12:00:00Z"
  }
}
Authentication: Business API Key
Submit KYC data collected from your own verification provider (e.g., Sumsub, Persona, Onfido) and create a Bridge customer. This is step 3 of the Custom KYC flow, after the user has accepted the Terms of Service.
Critical Requirements:
  • signed_agreement_id is REQUIRED (obtained from ToS link completion)
  • identifying_information MUST include at least ONE government ID document with images:
    • drivers_license (with image_front and image_back)
    • passport (with image_front and image_back)
    • national_id (with image_front and image_back)
  • SSN alone is NOT sufficient for government ID verification
  • For US addresses, use 2-letter state code for subdivision (e.g., “CA”, not “California”)
  • Images must be base64-encoded strings in format: data:image/png;base64,...

​
URL Parameters

​
externalUserId
string
required
Your internal user ID

​
Request Body

​
type
string
required
Customer type. Currently only "individual" is supported.
​
first_name
string
required
Customer’s first name
​
last_name
string
required
Customer’s last name
​
email
string
required
Customer’s email address
​
residential_address
object
required
Customer’s residential address
​
birth_date
string
required
Date of birth in format: YYYY-MM-DD (e.g., “1990-01-15”)
​
signed_agreement_id
string
required
The signed agreement ID received from the ToS link redirect. This is REQUIRED.
​
identifying_information
array
required
Array of identifying documents. MUST include at least ONE government ID with images (drivers_license, passport, or national_id).
​
phone
string
Customer’s phone number (optional)

​
Response

​
data
object
curl -X POST 'https://api.karmapay.xyz/v0/end-users/user_123/submit-kyc' \
  -H 'Authorization: Bearer karma_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "individual",
    "first_name": "John",
    "last_name": "Doe",
    "email": "[email protected]",
    "residential_address": {
      "street_line_1": "123 Main St",
      "city": "San Francisco",
      "subdivision": "CA",
      "postal_code": "94102",
      "country": "USA"
    },
    "birth_date": "1990-01-15",
    "signed_agreement_id": "agmt_xxx",
    "identifying_information": [
      {
        "type": "ssn",
        "issuing_country": "usa",
        "number": "123-45-6789"
      },
      {
        "type": "drivers_license",
        "issuing_country": "usa",
        "number": "D1234567",
        "image_front": "data:image/png;base64,...",
        "image_back": "data:image/png;base64,..."
      }
    ]
  }'

{
  "data": {
    "id": "770e8400-e29b-41d4-a716-446655440000",
    "externalUserId": "user_123",
    "email": "[email protected]",
    "applicantId": "custom_kyc_business_customer_id_user_123",
    "bridgeCustomerId": "cus_1234567890abcdef",
    "createdAt": "2025-10-31T12:00:00Z"
  }
}
Next Step: After successfully submitting KYC data, poll GET /v0/end-users/:externalUserId/customer-status every 5 seconds until baseEndorsementStatus is "approved". Once approved, the customer is ready to create virtual accounts or external accounts.