Skip to main content
POST
Sandbox only. This endpoint is available in sandbox only while we finish development. It is not available in production yet, and its request and response shapes may change before release.

Authorizations

x-api-key
string
header
required

Headers

x-idempotency-key
string<uuid>
required

Unique key (UUID) to ensure request idempotency on POST, PUT and PATCH requests.

A key is scoped to your client, the HTTP method and the path, and is remembered for 24 hours after a successful (below 400) response. Repeating the same request (same JSON body, whatever the key order or whitespace) with the same key within that window returns the original response with X-Idempotent-Replayed: true instead of executing the request again. Using the same key on the same endpoint with a different body returns 422 with problem type idempotency-key-reused; the request is not executed. Error responses (4xx and 5xx) are not remembered, so a request refused for a fixable reason can be corrected and retried under the same key. Request bodies that are not JSON (for example file uploads) are not compared.

Path Parameters

customer_id
string
required

KSUID is a 27-character globally unique ID that combines a timestamp with a random component. Used for all entity identifiers in the Dakota platform.

Required string length: 27
Pattern: ^[0-9A-Za-z]{27}$
Example:

"1NFHrqBHb3cTfLVkFSGmHZqdDPi"

Body

application/json

Cardholder details

Creates a cardholder for an INDIVIDUAL customer. Name is not supplied here -- it is taken from the individual on the customer's latest approved onboarding application. email follows the same on-file rule as CreateCardholderFromPersonRequest: required only when the person has none on file, and otherwise rejected if it disagrees with the one already there. phone is optional when a phone number is on file for the individual, and required (a 400 on phone) when none is.

phone
string

Optional when a phone number is on file for the individual: the one on file is used when this is omitted, and a phone sent here is used instead. Required when none is on file. The cardholder's own mobile number, E.164-formatted (a +1 number must be a North American number that can exist: 10 digits after the +1, with an area code and exchange that do not start with 0 or 1). It is used to verify the cardholder at online checkouts that ask for 3-D Secure, so do not send a shared or placeholder number.

Example:

"+15555550123"

email
string<email>

Required only when the individual has no email on file. Otherwise omit it; sending a different email than the one already on file is rejected.

Maximum string length: 254
Example:

"ada@example.com"

external_id
string | null

Optional client-supplied lookup key.

address
Address · object

Optional override for the cardholder's residential address. When omitted, the customer's stored address is used for the country check and for provisioning: the business's address for a business customer, and the individual's onboarding address for an individual customer. An address sent here must be one the card issuer accepts, or the request is refused with a 400 naming the field (errors[].code is cardholder_address_invalid) and nothing is created: every address needs street1 and city; a US address (country of US) also needs region, a two-letter US state or territory code such as CA, and postal_code, five digits or ZIP+4 such as 12345-1234; an address in the Cayman Islands (KY) or the British Virgin Islands (VG) needs a postal_code in that country's format (KY1-1234, VG1110).

Response

Cardholder created successfully

Response containing cardholder details.

id
string
required

KSUID is a 27-character globally unique ID that combines a timestamp with a random component. Used for all entity identifiers in the Dakota platform.

Required string length: 27
Pattern: ^[0-9A-Za-z]{27}$
Example:

"1NFHrqBHb3cTfLVkFSGmHZqdDPi"

customer_id
string
required

KSUID is a 27-character globally unique ID that combines a timestamp with a random component. Used for all entity identifiers in the Dakota platform.

Required string length: 27
Pattern: ^[0-9A-Za-z]{27}$
Example:

"1NFHrqBHb3cTfLVkFSGmHZqdDPi"

first_name
string
required
last_name
string
required
email
string
required
phone
string
required
status
enum<string>
required

Current status of the cardholder. Returns pending on create; on the clean path it flips to active within seconds via a cardholder.updated webhook.

An enrollment flagged during screening takes a longer route: pending → under_review (a reviewer holds it) → request_for_information (the reviewer needs something from you) → active or declined. You answer information requests through the API; there is never a cardholder-facing link. Every transition emits cardholder.updated, and opening a request also emits cardholder.information_requested.

suspended and closed are lifecycle rather than review states. closed is terminal and appears only in the cardholder.updated webhook emitted when a cardholder is deleted — deleted cardholders are not returned by the REST endpoints.

Available options:
pending,
under_review,
request_for_information,
active,
declined,
suspended,
closed
Example:

"pending"

created_at
integer
required

Unix timestamp (seconds) of creation.

updated_at
integer
required

Unix timestamp (seconds) of last update.

open_requirements
Cardholder Open Requirements · object

Summary of what a reviewer is currently waiting on for this cardholder. count is 0 and types is empty unless the cardholder is in request_for_information.

This is a summary only. Read the individual items, with their descriptions, from GET /cardholders/{cardholder_id}/application.

external_id
string | null