Cardholder Creation

Goal: create a cardholder profile with KYC data so the user is eligible for card issuance.

Review the encrypted request rules in Overview before starting.

Workflow steps

Create a user
Register the user who will own the cardholder profile.
List card products
Select a card product and store its subprovider_code for the next step.
Create the cardholder
Submit KYC data with external_user_id and subprovider_code.

POST/api/v1/users/createCreate the user that owns the cardholder.
POST/api/v1/cards/productsList available card products and their subprovider_code.
POST/api/v1/cardholders/createCreate the cardholder with KYC data.

Field	Type	Required	Description
`cardholder_id`	string	Required	Cardholder identifier.
`project_id`	string	Optional	Project identifier.
`user_id`	string	Optional	Internal user identifier.
`subprovider_code`	string	Required	Subprovider code. Use this field
`subprovider_id`	string	Optional	Legacy subprovider ObjectId. Prefer subprovider_code.
`registration_status`	string	Required	Registration status. Enum: `pending`, `active`, `suspended`, `failed`
`kyc_status`	string	Required	KYC status. Enum: `not_started`, `pending`, `approved`, `rejected`, `expired`
`kyc_level`	string	Optional	KYC level if available (none, basic, advanced, full).
`registered_at`	string	Optional	UTC registration timestamp (ISO 8601).
`activated_at`	string	Optional	UTC activation timestamp (ISO 8601).
`created_at`	string	Optional	UTC creation timestamp (ISO 8601).
`updated_at`	string	Optional	UTC last-update timestamp (ISO 8601).

Field	Type	Required	Description
`first_name`	string	Required	Given name.
`last_name`	string	Required	Family name.
`birth_date`	string	Required	Date of birth (YYYY-MM-DD).
`email`	string	Required	Valid email address.
`phone_number_full`	string	Required	Full international phone number.
`country_iso`	string	Required	ISO 3166-1 alpha-2 country code.

These error slugs show up most often during cardholder onboarding.

Error Slug	Description
`invalid_request`	Request payload failed validation.
`external_user_id_exists`	User with this external_user_id already exists.
`external_user_id_required`	external_user_id is required.
`project_user_not_found`	User not found for the given identifier.
`invalid_subprovider_id`	subprovider_id or subprovider_code is invalid.
`subprovider_not_found`	Subprovider not found.
`subprovider_not_active`	Subprovider is not active.
`cardholder_already_exists`	Cardholder already exists for the user.
`kyc_data_required`	KYC data is missing.
`provider_error`	Provider-specific failure.

Field-level validation errors share a predictable naming pattern.

Field	Example Error Slugs
`first_name`	first_name_required, first_name_invalid_type, first_name_invalid_length
`last_name`	last_name_required, last_name_invalid_type, last_name_invalid_length
`birth_date`	birth_date_required, birth_date_invalid_format, birth_date_underage
`email`	email_required, email_invalid_format, email_invalid_length
`phone_number_full`	phone_number_full_required, phone_number_full_invalid_format
`country_iso`	country_iso_required, country_iso_invalid_length