Sign in

v1

latestOpenAPI 3.0.22026-07-26123510445.2 KB
Cardholders

Retrieve Cardholder

Retrieves an issuing cardholder object.

get/v1/issuing/cardholders/{id}

Path parameters

idstring uuid required
Example:b3d9d2d5-4c12-4946-a09d-953e82sed2b0

Universally unique identifier (UUID v4) of a resource.

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.

Response

OK - Successfully retrieved a cardholder.

cardholder_idstring uuid

The cardholder's unique identifier.

emailstring

The cardholder's email address.

number_of_cardsinteger

The total number of cards associated with the cardholder, including all statuses.

first_namestring

The first name of this cardholder. Required before activating Cards. This field cannot contain any numbers, special characters (except periods, commas, hyphens, spaces and apostrophes) or non-latin letters.

last_namestring

The last name of this cardholder. Required before activating Cards. This field cannot contain any numbers, special characters (except periods, commas, hyphens, spaces and apostrophes) or non-latin letters.

create_timestring

Time at which the object was created.

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

The cardholder's status.

date_of_birthstring

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

country_codestring

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

phone_numberstring

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.

review_status'SUCCESS' | 'FAILED' | 'PENDING'

The review status of the cardholder.

idv_status'PENDING' | 'PASSED' | 'FAILED'

IDV verification status. Returned when applicable.

  • PENDING - IDV pending.
  • PASSED - IDV passed.
  • FAILED - IDV failed.
idv_verification_urlstring

IDV verification URL. Returned when applicable.

idv_url_expires_atstring

IDV verification URL expiration time in RFC 3339 format.

Example response

{
  "cardholder_id": "7c4ff2cd-1bf6-4aaa-bf16-266771425011",
  "email": "demo@example.com",
  "number_of_cards": 1,
  "first_name": "Emily",
  "last_name": "Toy",
  "create_time": "2024-05-09 15:52:23",
  "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"
  },
  "review_status": "SUCCESS",
  "idv_verification_url": "https://idv.sumsub.com/verify/abc123",
  "idv_url_expires_at": "2026-04-10T10:00:00+08:00"
}