Query a Cardholder

Retrieve a cardholder's details by ID, including their current review status. Deleted cardholders are removed permanently, so querying one returns CARDHOLDER_NOT_EXIST.
Request Parameters
idstring
required
Unique cardholder identifier returned by Create a Cardholder. Max 64 characters.
Response Parameters
resultResult
See Result.
idstring
Unique cardholder identifier. Max 64 characters.
typestring
Cardholder type.

Valid Values:

EMPLOYEE — An employee of your business.
SHAREHOLDER — A shareholder or beneficial owner of your business.
statusstring
Current cardholder status. Poll this field after creation to learn the KYC outcome.

Valid Values:

PENDING — Under review, awaiting KYC verification.
ACTIVE — Review passed; cards can be issued to this cardholder.
FAILED — Review failed or the cardholder was rejected.
personInfoPersonInfo
Personal details of the cardholder.
Show child parametersShow child parameters
nationalitystring
Cardholder's nationality, as a three-letter ISO 3166-1 alpha-3 country code.
createdAtdatetime
Timestamp when the cardholder was created. ISO 8601 extended format.
Error Codes
resultCoderesultStatusresultMessageTroubleshooting
SUCCESSSSuccess.Query succeeded.
PARAM_ILLEGALFIllegal parameters exist.Verify that `id` is present and correctly formatted.
CARDHOLDER_NOT_EXISTFThe cardholder does not exist.The ID is wrong or the cardholder has been deleted. Confirm the ID with List Cardholders.
AUTHORIZATION_NOT_EXISTFThe authorization relationship does not exist.Verify the `account-id` / `access-token` authorization before retrying.
USER_NOT_EXISTFThe user does not exist.Retry with correct user information.
Definition
POST /api/open/v1/issuing/cardholders/query
Request
{
"id": "ch_abc123xyz"
}
Response
{
"result": {
  "resultCode": "SUCCESS",
  "resultMessage": "success",
  "resultStatus": "S"
},
"id": "ch_abc123xyz",
"type": "EMPLOYEE",
"status": "ACTIVE",
"personInfo": {
  "userName": {
    "firstName": "San",
    "lastName": "Zhang",
    "fullName": "San Zhang"
  },
  "dateOfBirth": "1990-06-15"
},
"nationality": "CHN",
"createdAt": "2024-01-15T08:00:00Z"
}