Cardholders

Cards is available in sandbox only while we finish development. Dakota enables Cards per account. The Cards endpoints are in the API reference, marked Sandbox only. Endpoints, fields, and flows can still change before release.

A cardholder is the person a card is issued to. Every card belongs to one, and a cardholder must be active before you can issue them a card. One customer can have many cardholders, each with their own cards and limits. The customer’s Cards capability must be available first. Until then, creation returns 403 cards-tos-not-accepted. See Activating customers.

Create a cardholder

POST /customers/{customer_id}/cardholders takes one of three request shapes. The shape you send depends on the customer type, and on whether the person is already on the customer’s onboarding application.

Customer	Request	Name and email come from
Business, from a person already on the application	`person_id`, `phone`. Add `email` only if the person has none on file.	The person
Business, someone new	`first_name`, `last_name`, `email`, `phone`	The request
Individual	`phone`. Add `email` only if the customer has none on file.	The customer’s onboarding

phone is in E.164 format. external_id is optional on every shape: it is your own lookup key. Send the cardholder’s own mobile number and email address. The phone number is how the cardholder is verified at online checkouts that ask for 3-D Secure, so a shared or placeholder number makes those purchases fail. Adding the card to Apple Pay or Google Pay can also send a code to the phone or the email.

From a person already on the application

For a business customer, reuse the people Dakota already verified during onboarding instead of collecting their details again:

GET /customers/{customer_id}/persons

200 OK
{
  "data": [
    {
      "id": "2WGC9dLw1R5M9fHaZr7K4Ya8nPq",
      "first_name": "Ada",
      "last_name": "Lovelace",
      "roles": ["control_person"],
      "cardholder_id": null,
      "missing_for_cards": ["phone"]
    }
  ]
}

cardholder_id is set when the person already has a cardholder. A declined cardholder still counts. Delete it before you enroll the person again.
missing_for_cards lists what to collect before you create the cardholder. It always includes phone, and includes email when none is on file.

POST /customers/{customer_id}/cardholders
X-Idempotency-Key: 5b1e0c7a-2d4f-4a8e-9c3b-7f6e5d4c3b2a

{
  "person_id": "2WGC9dLw1R5M9fHaZr7K4Ya8nPq",
  "phone": "+14155550123",
  "external_id": "employee-4471"
}

The response is the cardholder, with status: "pending".

When creation is refused

Response	Cause	What to do
`409 cardholder-person-exists`	The email you sent belongs to a person already on the application.	Retry with the `person_id` the error names.
`409 cardholder-already-exists`	The person already has a cardholder, or the email is in use by one. An individual customer can have only one cardholder.	Use the cardholder the error names.
`409 cardholder-person-unavailable`	Dakota has no usable record for this person yet.	Contact Dakota.
`403 cardholder-base-not-enabled`	Your account is not activated for this customer type.	Contact Dakota.

Two people cannot share one email address.

Lifecycle

Wait for cardholder.updated with status: "active" before you issue a card. Most cardholders become active within seconds.

Status	Meaning
`pending`	Screening is running.
`under_review`	A reviewer is looking at the cardholder. Nothing is needed from you yet.
`request_for_information`	A reviewer needs something from you. See below.
`active`	Cards can be issued.
`suspended`	All of the cardholder’s cards are frozen, and none can be unfrozen until the suspension ends. Only Dakota can lift it.
`declined`	Final. The cardholder was not approved.
`closed`	Final. The cardholder was deleted.

Review requests are not live yet. When a reviewer needs something, GET /cardholders/{cardholder_id}/application will list it, and you will answer with POST /cardholders/{cardholder_id}/application/information. The request goes to you, never to the cardholder. Until the review pipeline is on, the list is always empty and a submission returns 501.

Update a cardholder

PATCH /cardholders/{cardholder_id} changes first_name, last_name, email, or phone. Fields you leave out are unchanged.

Delete a cardholder

Close each of the cardholder’s cards. Dakota refuses the delete while any of their cards is not closed, including frozen ones.
DELETE /cardholders/{cardholder_id}.

The delete is a soft delete. A final cardholder.updated reports status: "closed", and the cardholder is no longer returned by the API. Purchases already made on their cards still clear or reverse, and their card_transaction events keep arriving. You can enroll the same person again afterwards.

Find a cardholder

GET /customers/{customer_id}/cardholders accepts an external_id filter. The match is exact and case-sensitive, and it can return more than one cardholder, because external_id is not unique.

Playground

Documentation

Import Share Tokens

Agentic Payments

Cards

Authentication

Developer Tools

Create a cardholder

From a person already on the application

When creation is refused

Lifecycle

Update a cardholder

Delete a cardholder

Find a cardholder

​Create a cardholder

​From a person already on the application

​When creation is refused

​Lifecycle

​Update a cardholder

​Delete a cardholder

​Find a cardholder

Create a cardholder

From a person already on the application

When creation is refused

Lifecycle

Update a cardholder

Delete a cardholder

Find a cardholder