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_id for the next step.
Create the cardholder
Submit KYC data plus either external_user_id or project_user_id.

Field	Type	Required	Description
`cardholder_id`	string	Required	Cardholder identifier.
`external_user_id`	string	Optional	Your external user identifier.
`project_user_id`	string	Optional	Internal project user ID.
`subprovider_id`	string	Required	Subprovider identifier.
`registration_status`	string	Required	Registration status. Enum: `pending`, `active`, `suspended`, `failed`
`kyc_status`	string	Required	KYC status. Enum: `not_started`, `pending`, `approved`, `rejected`, `expired`

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.
`project_user_id_or_external_user_id_required`	Either external_user_id or project_user_id is required.
`invalid_project_user_id`	project_user_id is invalid.
`project_user_not_found`	User not found for the given identifier.
`invalid_subprovider_id`	subprovider_id 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