Cardholder
A cardholder represents the person who will use a card. You must create a cardholder before issuing any card to them. Once a card is linked to a cardholder, the association cannot be changed.
Create Cardholder
This API allows you to create a new cardholder profile in the system.
{{baseUrl}}/hashdt/issuing/api/v1/card/cardholder
Description
Cardholders are authorized representatives of your business and are associated with a named individual who represents your business. A cardholder can be associated with a card.
Creating a cardholder requires passing a name screening process, which involves submitting basic information about the cardholder.
Cardholders residing in restricted countries cannot be issued cards, and some nationalities require proof of address (POA). See Cardholder Region Restrictions before submitting.
Note: The sample request below includes both required and optional fields. Adjust the payload to match your use case, for example:
back_fileis required only whenidentity.typeisID_CARD.proof_of_address,proof_of_address_issue_date, andproof_of_address_issuing_countryare required only when POA applies to the cardholder's nationality.kyc_verificationis required only if you use your own KYC provider.country_codeandaddress.line2are optional.
📩 Request Headers
x-api-key string required
x-product-id string required
x-request-id string required
x-user-id string required
agent-code string required
subagent-code string required
Content-Type string required
application/jsonAuthorization string required
📦 Request Body
email string required
gender string required
MALE or FEMALE.nationality string required
mobile_number string required
country_code string
individual object required
date_of_birth string required
YYYY-MM-DD). Cardholders must be at least 18 and under 80 years old.name object required
first_name string required
last_name string required
address object required
city string required
country string required
line1 string required
line2 string
state string required
postcode string required
identity object required
type string required
ID_CARD or PASSPORT.number string required
front_file string required
back_file string conditional
type is ID_CARD. Maximum file size: 2 MB (2,097,152 bytes) after Base64 decoding.proof_of_address string conditional
PDF, PNG, JPG, and JPEG, up to 10 MB (10,485,760 bytes) after decoding.proof_of_address_issue_date string conditional
YYYY-MM-DD. Required when POA is applicable.proof_of_address_issuing_country string conditional
kyc_verification object conditional
Note:
- Required only if the client uses its own KYC provider for verification.
- Not required if the platform's default KYC provider is used.
- The user's KYC verification must be completed before submitting these details.
method string required
KYC verification method. Accepted value: THIRD_PARTY.
THIRD_PARTY- Cardholder has completed verification via a third-party provider and submits proof.
kyc_proof object required
provider string required
SUMSUB, MYINFO, JUMIO, DIDIT, SHUFTI, REGTANK.reference_id string required
type string required
INDIVIDUALcreated_by string required
- 🧩 Examples
Request Example
- cURL
- Python
- Java
- NodeJs
curl --location --request POST \
--url '{{baseUrl}}/hashdt/issuing/api/v1/card/cardholder' \
--header 'x-api-key: {{Shared X-API key}}' \
--header 'x-product-id: {{Shared ProductID}}' \
--header 'x-request-id: {{IdempotencyKey}}' \
--header 'x-user-id: {{UserID}}' \
--header 'agent-code: {{Shared Agent Code}}' \
--header 'subagent-code: {{Shared Sub-Agent Code}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{AccessToken}}'
--data-raw '{
"email": "demo@yopmail.com",
"gender": "MALE",
"nationality": "SG",
"mobile_number": "92271434",
"country_code": "SG",
"individual": {
"date_of_birth": "1990-01-01",
"name": {
"first_name": "John",
"last_name": "Doe"
},
"address": {
"city": "Singapore",
"country": "SG",
"line1": "123 Bukit Timah Road",
"state": "Singapore",
"postcode": "229837"
}
},
"identity": {
"type": "PASSPORT",
"number": "E12345678",
"front_file": "base64-encode-string",
"back_file": "base64-encode-string",
"proof_of_address": "base64-encode-string",
"proof_of_address_issue_date": "2026-10-15",
"proof_of_address_issuing_country": "SG"
},
"kyc_verification": {
"method": "THIRD_PARTY",
"kyc_proof": {
"provider": "SUMSUB",
"reference_id": "SUMSUB-123456"
}
},
"type": "INDIVIDUAL",
"created_by": "Test User"
}'
import requests
import json
url = "{{baseUrl}}/hashdt/issuing/api/v1/card/cardholder"
payload = json.dumps({
"email": "demo@yopmail.com",
"gender": "MALE",
"nationality": "SG",
"mobile_number": "92271434",
"country_code": "SG",
"individual": {
"date_of_birth": "1990-01-01",
"name": {
"first_name": "John",
"last_name": "Doe"
},
"address": {
"city": "Singapore",
"country": "SG",
"line1": "123 Bukit Timah Road",
"state": "Singapore",
"postcode": "229837"
}
},
"identity": {
"type": "PASSPORT",
"number": "E12345678",
"front_file": "base64-encode-string",
"back_file": "base64-encode-string",
"proof_of_address": "base64-encode-string",
"proof_of_address_issue_date": "2026-10-15",
"proof_of_address_issuing_country": "SG"
},
"kyc_verification": {
"method": "THIRD_PARTY",
"kyc_proof": {
"provider": "SUMSUB",
"reference_id": "SUMSUB-123456"
}
},
"type": "INDIVIDUAL",
"created_by": "Test User"
})
headers = {
'x-api-key': '{{Shared X-API key}}',
'x-product-id': '{{Shared ProductID}}',
'x-request-id': '{{IdempotencyKey}}',
'x-user-id': '{{UserID}}',
'agent-code': '{{Shared Agent Code}}',
'subagent-code': '{{Shared Sub-Agent Code}}',
'Content-Type': 'application/json',
'Authorization': 'Bearer {{AccessToken}}'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\r\n \"email\": \"demo@yopmail.com\",\r\n \"gender\": \"MALE\",\r\n \"nationality\": \"SG\",\r\n \"mobile_number\": \"92271434\",\r\n \"country_code\": \"SG\",\r\n \"individual\": {\r\n \"date_of_birth\": \"1990-01-01\",\r\n \"name\": {\r\n \"first_name\": \"John\",\r\n \"last_name\": \"Doe\"\r\n },\r\n \"address\": {\r\n \"city\": \"Singapore\",\r\n \"country\": \"SG\",\r\n \"line1\": \"123 Bukit Timah Road\",\r\n \"state\": \"Singapore\",\r\n \"postcode\": \"229837\"\r\n }\r\n },\r\n \"identity\": {\r\n \"type\": \"PASSPORT\",\r\n \"number\": \"E12345678\",\r\n \"front_file\": \"base64-encode-string\",\r\n \"back_file\": \"base64-encode-string\",\r\n \"proof_of_address\": \"base64-encode-string\",\r\n \"proof_of_address_issue_date\": \"2026-10-15\",\r\n \"proof_of_address_issuing_country\": \"SG\"\r\n },\r\n \"kyc_verification\": {\r\n \"method\": \"THIRD_PARTY\",\r\n \"kyc_proof\": {\r\n \"provider\": \"SUMSUB\",\r\n \"reference_id\": \"SUMSUB-123456\"\r\n }\r\n },\r\n \"type\": \"INDIVIDUAL\",\r\n \"created_by\": \"Test User\"\r\n}");
Request request = new Request.Builder()
.url("{{baseUrl}}/hashdt/issuing/api/v1/card/cardholder")
.method("POST", body)
.addHeader("x-api-key", "{{Shared X-API key}}")
.addHeader("x-product-id", "{{Shared ProductID}}")
.addHeader("x-request-id", "{{IdempotencyKey}}")
.addHeader("x-user-id", "{{UserID}}")
.addHeader("agent-code", "{{Shared Agent Code}}")
.addHeader("subagent-code", "{{Shared Sub-Agent Code}}")
.addHeader("Content-Type", "application/json")
.addHeader("Authorization", "Bearer {{AccessToken}}")
.build();
Response response = client.newCall(request).execute();
const axios = require('axios');
let data = JSON.stringify({
"email": "demo@yopmail.com",
"gender": "MALE",
"nationality": "SG",
"mobile_number": "92271434",
"country_code": "SG",
"individual": {
"date_of_birth": "1990-01-01",
"name": {
"first_name": "John",
"last_name": "Doe"
},
"address": {
"city": "Singapore",
"country": "SG",
"line1": "123 Bukit Timah Road",
"state": "Singapore",
"postcode": "229837"
}
},
"identity": {
"type": "PASSPORT",
"number": "E12345678",
"front_file": "base64-encode-string",
"back_file": "base64-encode-string",
"proof_of_address": "base64-encode-string",
"proof_of_address_issue_date": "2026-10-15",
"proof_of_address_issuing_country": "SG"
},
"kyc_verification": {
"method": "THIRD_PARTY",
"kyc_proof": {
"provider": "SUMSUB",
"reference_id": "SUMSUB-123456"
}
},
"type": "INDIVIDUAL",
"created_by": "Test User"
});
let config = {
method: 'post',
maxBodyLength: Infinity,
url: '{{baseUrl}}/hashdt/issuing/api/v1/card/cardholder',
headers: {
'x-api-key': '{{Shared X-API key}}',
'x-product-id': '{{Shared ProductID}}',
'x-request-id': '{{IdempotencyKey}}',
'x-user-id': '{{UserID}}',
'agent-code': '{{Shared Agent Code}}',
'subagent-code': '{{Shared Sub-Agent Code}}',
'Content-Type': 'application/json',
'Authorization': 'Bearer {{AccessToken}}'
},
data : data
};
axios.request(config)
.then((response) => {
console.log(JSON.stringify(response.data));
})
.catch((error) => {
console.log(error);
});
Response Example
- 201
- 400
{
"status": "success",
"message": "Cardholder created successfully.",
"code": 201,
"data": [
{
"id": "cardholder-id"
}
]
}
{
"code": 400,
"status": "error",
"message": "Error Message"
}
Get All Cardholders
{{baseUrl}}/hashdt/issuing/api/v1/card/cardholder
Description
This API returns a list of all cardholders, allowing you to view and manage cardholder details easily.
📩 Request Headers
x-api-key string required
x-product-id string required
x-request-id string required
x-user-id string required
agent-code string required
subagent-code string required
Content-Type string required
application/jsonAuthorization string required
🔍 Query Parameters
page_num integer
page_size integer
- 🧩 Examples
Request Example
- cURL
- Python
- Java
- NodeJs
curl --location --request GET \
--url '{{baseUrl}}/hashdt/issuing/api/v1/card/cardholder' \
--header 'x-api-key: {{Shared X-API key}}' \
--header 'x-product-id: {{Shared ProductID}}' \
--header 'x-request-id: {{IdempotencyKey}}' \
--header 'x-user-id: {{UserID}}' \
--header 'agent-code: {{Shared Agent Code}}' \
--header 'subagent-code: {{Shared Sub-Agent Code}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{AccessToken}}'
import requests
import json
url = "{{baseUrl}}/hashdt/issuing/api/v1/card/cardholder"
payload = {}
headers = {
'x-api-key': '{{Shared X-API key}}',
'x-product-id': '{{Shared ProductID}}',
'x-request-id': '{{IdempotencyKey}}',
'x-user-id': '{{UserID}}',
'agent-code': '{{Shared Agent Code}}',
'subagent-code': '{{Shared Sub-Agent Code}}',
'Content-Type': 'application/json',
'Authorization': 'Bearer {{AccessToken}}'
}
response = requests.request("GET", url, headers=headers, data=payload)
print(response.json())
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "");
Request request = new Request.Builder()
.url("{{baseUrl}}/hashdt/issuing/api/v1/card/cardholder")
.method("GET", body)
.addHeader("x-api-key", "{{Shared X-API key}}")
.addHeader("x-product-id", "{{Shared ProductID}}")
.addHeader("x-request-id", "{{IdempotencyKey}}")
.addHeader("x-user-id", "{{UserID}}")
.addHeader("agent-code", "{{Shared Agent Code}}")
.addHeader("subagent-code", "{{Shared Sub-Agent Code}}")
.addHeader("Content-Type", "application/json")
.addHeader("Authorization", "Bearer {{AccessToken}}")
.build();
Response response = client.newCall(request).execute();
const axios = require('axios');
let config = {
method: 'get',
maxBodyLength: Infinity,
url: '{{baseUrl}}/hashdt/issuing/api/v1/card/cardholder',
headers: {
'x-api-key': '{{Shared X-API key}}',
'x-product-id': '{{Shared ProductID}}',
'x-request-id': '{{IdempotencyKey}}',
'x-user-id': '{{UserID}}',
'agent-code': '{{Shared Agent Code}}',
'subagent-code': '{{Shared Sub-Agent Code}}',
'Content-Type': 'application/json',
'Authorization': 'Bearer {{AccessToken}}'
}
};
axios.request(config)
.then((response) => {
console.log(JSON.stringify(response.data));
})
.catch((error) => {
console.log(error);
});
Response Example
- 200
- 400
{
"status": "success",
"message": "Cardholder fetched successfully",
"code": 200,
"totalcount": 2,
"data": [
{
"id": "cardholder-id",
"email": "demo@yopmail.com",
"country_code": "SG",
"mobile_number": "92271434",
"kyc_status": null,
"status": "SUCCESS",
"type": "INDIVIDUAL",
"postal_address": {
"line1": "123 5th Avenue",
"line2": null,
"city": "New York",
"state": "NY",
"country": "SG",
"postcode": "10001"
},
"individual": {
"address": {
"line1": "123 5th Avenue",
"line2": null,
"city": "New York",
"state": "NY",
"country": "SG",
"postcode": "10001"
},
"date_of_birth": "1990-01-01",
"employers": null,
"name": {
"title": null,
"first_name": "John",
"middle_name": null,
"last_name": "Doe",
"name_on_card": null
}
},
"created_at": "2026-08-11 14:50:41",
"review_status": "SUCCESS"
},
{
"id": "cardholder-id",
"email": "sandeep.test@yopmail.com",
"country_code": "SG",
"mobile_number": "92271430",
"kyc_status": null,
"status": "SUCCESS",
"type": "INDIVIDUAL",
"postal_address": {
"line1": "5678 Oak Avenue",
"line2": null,
"city": "Los Angeles",
"state": "CA",
"country": "US",
"postcode": "94932"
},
"individual": {
"address": {
"line1": "5678 Oak Avenue",
"line2": null,
"city": "Los Angeles",
"state": "CA",
"country": "US",
"postcode": "94932"
},
"date_of_birth": "1998-08-11",
"employers": null,
"name": {
"title": null,
"first_name": "Sandeep",
"middle_name": null,
"last_name": "Sharma",
"name_on_card": null
}
},
"created_at": "2026-08-10 16:48:22",
"review_status": "SUCCESS"
}
]
}
{
"code": 400,
"status": "error",
"message": "Error Message",
}
Get Cardholder Details
This API is used to retrieve the cardholder details.
{{baseUrl}}/hashdt/issuing/api/v1/card/cardholder
Description
This API is used to retrieve the details of a specific cardholder. You must provide the Cardholder ID or email ID as a query parameter to identify the cardholder.
📩 Request Headers
x-api-key string required
x-product-id string required
x-request-id string required
x-user-id string required
agent-code string required
subagent-code string required
Content-Type string required
application/jsonAuthorization string required
🔍 Query Parameters
id string
email string
- 🧩 Examples
Request Example
- cURL
- Python
- Java
- NodeJs
curl --location --request GET \
--url '{{baseUrl}}/hashdt/issuing/api/v1/card/cardholder?id={{CardholderID}}' \
--header 'x-api-key: {{Shared X-API key}}' \
--header 'x-product-id: {{Shared ProductID}}' \
--header 'x-request-id: {{IdempotencyKey}}' \
--header 'x-user-id: {{UserID}}' \
--header 'agent-code: {{Shared Agent Code}}' \
--header 'subagent-code: {{Shared Sub-Agent Code}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{AccessToken}}'
import requests
import json
url = "{{baseUrl}}/hashdt/issuing/api/v1/card/cardholder?id={{CardholderID}}"
payload = {}
headers = {
'x-api-key': '{{Shared X-API key}}',
'x-product-id': '{{Shared ProductID}}',
'x-request-id': '{{IdempotencyKey}}',
'x-user-id': '{{UserID}}',
'agent-code': '{{Shared Agent Code}}',
'subagent-code': '{{Shared Sub-Agent Code}}',
'Content-Type': 'application/json',
'Authorization': 'Bearer {{AccessToken}}'
}
response = requests.request("GET", url, headers=headers, data=payload)
print(response.text)
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "");
Request request = new Request.Builder()
.url("{{baseUrl}}/hashdt/issuing/api/v1/card/cardholder?id={{CardholderID}}")
.method("GET", body)
.addHeader("x-api-key", "{{Shared X-API key}}")
.addHeader("x-product-id", "{{Shared ProductID}}")
.addHeader("x-request-id", "{{IdempotencyKey}}")
.addHeader("x-user-id", "{{UserID}}")
.addHeader("agent-code", "{{Shared Agent Code}}")
.addHeader("subagent-code", "{{Shared Sub-Agent Code}}")
.addHeader("Content-Type", "application/json")
.addHeader("Authorization", "Bearer {{AccessToken}}")
.build();
Response response = client.newCall(request).execute();
const axios = require('axios');
let config = {
method: 'get',
maxBodyLength: Infinity,
url: '{{baseUrl}}/hashdt/issuing/api/v1/card/cardholder?id={{CardholderID}}',
headers: {
'x-api-key': '{{Shared X-API key}}',
'x-product-id': '{{Shared ProductID}}',
'x-request-id': '{{IdempotencyKey}}',
'x-user-id': '{{UserID}}',
'agent-code': '{{Shared Agent Code}}',
'subagent-code': '{{Shared Sub-Agent Code}}',
'Content-Type': 'application/json',
'Authorization': 'Bearer {{AccessToken}}'
}
};
axios.request(config)
.then((response) => {
console.log(JSON.stringify(response.data));
})
.catch((error) => {
console.log(error);
});
Response Example
- 200
- 400
{
"status": "success",
"message": "Cardholder fetched successfully",
"code": 200,
"data": [
{
"id": "cardholder-id",
"email": "demo@yopmail.com",
"country_code": "SG",
"mobile_number": "92271434",
"kyc_status": null,
"status": "SUCCESS",
"type": "INDIVIDUAL",
"postal_address": {
"line1": "123 5th Avenue",
"line2": null,
"city": "New York",
"state": "NY",
"country": "SG",
"postcode": "10001"
},
"individual": {
"address": {
"line1": "123 5th Avenue",
"line2": null,
"city": "New York",
"state": "NY",
"country": "SG",
"postcode": "10001"
},
"date_of_birth": "1990-01-01",
"employers": null,
"name": {
"title": null,
"first_name": "John",
"middle_name": null,
"last_name": "Doe",
"name_on_card": null
}
},
"created_at": "2026-08-11 14:48:02",
"review_status": "SUCCESS"
}
]
}
{
"code": 400,
"status": "error",
"message": "Error Message"
}
Update Cardholder
This API allows you to update a cardholder profile in the system.
{{baseUrl}}/hashdt/issuing/api/v1/card/cardholder
Description
This endpoint updates cardholder information, including physical address, postal address, and contact details. All fields are optional, and only the fields provided will be updated. For composite objects, such as name, all child fields must be provided and valid when the object is included.
💡 mobile_number and country_code must be provided together. Updating either field individually is not supported.
📩 Request Headers
x-api-key string required
x-product-id string required
x-request-id string required
x-user-id string required
Content-Type string required
application/jsonAuthorization string required
📦 Request Body
mobile_number string
country_code string
individual object
address object required
city string required
country string required
line1 string required
line2 string
state string required
postcode string required
updated_by string required
🔍 Query Parameters
id string required
- 🧩 Examples
Request Example
- cURL
- Python
- Java
- NodeJs
curl --location --request PATCH \
--url '{{baseUrl}}/hashdt/issuing/api/v1/card/cardholder?id={{CardholderID}}' \
--header 'x-api-key: {{Shared X-API key}}' \
--header 'x-product-id: {{Shared ProductID}}' \
--header 'x-request-id: {{IdempotencyKey}}' \
--header 'x-user-id: {{UserID}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{AccessToken}}'
--data '{
"individual": {
"address": {
"city": "Austin",
"country": "US",
"line1": "1234 Elm Street",
"state": "TX",
"postcode": "94932"
}
},
"updated_by": "user"
}'
import requests
import json
url = "{{baseUrl}}/hashdt/issuing/api/v1/card/cardholder?id={{CardholderID}}"
payload = json.dumps({
"individual": {
"address": {
"city": "Austin",
"country": "US",
"line1": "1234 Elm Street",
"state": "TX",
"postcode": "94932"
}
},
"updated_by": "user"
})
headers = {
'x-api-key': '{{Shared X-API key}}',
'x-product-id': '{{Shared ProductID}}',
'x-request-id': '{{IdempotencyKey}}',
'x-user-id': '{{UserID}}',
'Content-Type': 'application/json',
'Authorization': 'Bearer {{AccessToken}}'
}
response = requests.request("PATCH", url, headers=headers, data=payload)
print(response.text)
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\r\n \"individual\": {\r\n \"address\": {\r\n \"city\": \"Austin\",\r\n \"country\": \"US\",\r\n \"line1\": \"1234 Elm Street\",\r\n \"state\": \"TX\",\r\n \"postcode\": \"94932\"\r\n }\r\n }, \r\n \"updated_by\": \"user\"\r\n }");
Request request = new Request.Builder()
.url("{{baseUrl}}/hashdt/issuing/api/v1/card/cardholder?id={{CardholderID}}")
.method("PATCH", body)
.addHeader("x-api-key", "{{Shared X-API key}}")
.addHeader("x-product-id", "{{Shared ProductID}}")
.addHeader("x-request-id", "{{IdempotencyKey}}")
.addHeader("x-user-id", "{{UserID}}")
.addHeader("Content-Type", "application/json")
.addHeader("Authorization", "Bearer {{AccessToken}}")
.build();
Response response = client.newCall(request).execute();
const axios = require('axios');
let data = JSON.stringify({
"individual": {
"address": {
"city": "Austin",
"country": "US",
"line1": "1234 Elm Street",
"state": "TX",
"postcode": "94932"
}
},
"updated_by": "user"
});
let config = {
method: 'patch',
maxBodyLength: Infinity,
url: '{{baseUrl}}/hashdt/issuing/api/v1/card/cardholder?id={{CardholderID}}',
headers: {
'x-api-key': '{{Shared X-API key}}',
'x-product-id': '{{Shared ProductID}}',
'x-request-id': '{{IdempotencyKey}}',
'x-user-id': '{{UserID}}',
'Content-Type': 'application/json',
'Authorization': 'Bearer {{AccessToken}}'
},
data : data
};
axios.request(config)
.then((response) => {
console.log(JSON.stringify(response.data));
})
.catch((error) => {
console.log(error);
});
Response Example
- 200
- 400
{
"status": "success",
"message": "Cardholder updated successfully.",
"code": 200
}
{
"code": 400,
"status": "error",
"message": "Error Message"
}