Sign in

v1

latestOpenAPI 3.0.22026-07-26123510445.2 KB
Cardholders

Create Cardholder

Creates a new issuing cardholder object that can be issued cards.

post/v1/issuing/cardholders

Headers

x-on-behalf-ofstring

Specifies the sub-account on whose behalf the request is made. This should be set to the account_id, which can be retrieved via the List Connected Accounts API. If omitted or empty, the request is executed using the master account. More information at Connected Accounts.

x-idempotency-keystring uuid

A unique identifier (UUID) used to maintain operation idempotency, ensuring that repeated executions of the same operation do not result in unintended effects or duplication. It helps preserve data consistency in the face of network errors, retries, or failures.

Request body

emailstring required

The cardholder's email address.

first_namestring required

The first name of the cardholder. Must be between 1 and 40 characters, containing only alphabetic characters and spaces. Spaces are not allowed at the beginning or end of the name.

last_namestring required

The last name of the cardholder. Must be between 1 and 40 characters, containing only alphabetic characters and spaces. Spaces are not allowed at the beginning or end of the name.

date_of_birthstring

The cardholder's birth date with yyyy-mm-dd format.

country_codestring required

Two-letter country code ISO 3166-1 alpha-2.

phone_numberstring required

The cardholder's phone number.

See Phone number validation rules for length validation details.

gender'MALE' | 'FEMALE'

The cardholder's gender.

  • MALE - Male.
  • FEMALE - Female.
nationalitystring

The cardholder's nationality in ISO 3166-1 alpha-2 format. Required for STANDARD and ENHANCED KYC levels.

document_type'pdf' | 'png' | 'jpg' | 'jpeg'

The type of the identification document.

documentstring

Base64 encoded identification document string, 2MB limitation.

Example request

{
  "email": "demo@example.com",
  "first_name": "Emily",
  "last_name": "Toy",
  "date_of_birth": "1990-01-01",
  "country_code": "SG",
  "phone_number": "86683306",
  "gender": "MALE",
  "nationality": "SG",
  "residential_address": {
    "country": "SG",
    "state": "Singapore",
    "city": "Singapore",
    "district": "Buona Vista",
    "line1": "9 N Buona Vista Dr",
    "line2": "THE METROPOLIS",
    "line_en": "9 N Buona Vista Dr, THE METROPOLIS",
    "postal_code": "138666"
  },
  "identity": {
    "type": "PASSPORT",
    "number": "E12345678"
  },
  "kyc_verification": {
    "method": "THIRD_PARTY",
    "kyc_proof": {
      "provider": "SUMSUB",
      "reference_id": "sumsub_ref_1234567890",
      "documents": [
        {
          "file_id": "b3d9d2d5-4c12-4946-a09d-953e82sed2b0",
          "report_type": "IDV"
        }
      ]
    }
  },
  "document_type": "pdf"
}

Response

Cardholder creation successfully.

cardholder_idstring uuid required

The cardholder's unique identifier.

cardholder_status'FAILED' | 'PENDING' | 'SUCCESS' | 'INCOMPLETE' required

The cardholder's status.

idv_verification_urlstring

IDV verification URL. Returned when kyc_verification.method is SUMSUB_REDIRECT.

idv_url_expires_atstring

IDV verification URL expiration time in RFC 3339 format. Returned when kyc_verification.method is SUMSUB_REDIRECT.

Example response

{
  "cardholder_id": "7c4ff2cd-1bf6-4aaa-bf16-266771425011",
  "idv_verification_url": "https://idv.sumsub.com/verify/abc123",
  "idv_url_expires_at": "2026-04-10T10:00:00+08:00"
}