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 when only the terms are outstanding, 403 cards-capability-enabling while Dakota finishes the setup for a customer who has done their part, and 403 cards-capability-unavailable otherwise. 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.
phone is in E.164 format. A phone you send is used instead of the one on file. The one on file does not change. external_id is optional on every shape: it is your own lookup key. address, the cardholder’s residential address, is also optional; when you leave it out, the customer’s address is used. If you send it, address.country is required and must be a two-letter ISO 3166-1 code, such as US or GB.
These return 400 validation-error, naming the field:
- No
phone, and none on file. - A
phonethat is not valid E.164, or a+1number that cannot exist. Itserrors[].codeiscardholder_phone_invalid. The same refusal says to sendphonewhen the number on file is the one that cannot be used. - An
emailthat differs from the one on file, or noemailwhen none is on file.
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:cardholder_idis set when the person already has a cardholder. A declined cardholder still counts. Delete it before you enroll the person again.phone_numberis the person’s phone on file, when there is one.missing_for_cardslists what to collect before you create the cardholder:phonewhen no usable phone is on file, andemailwhen none is on file. An empty list meansperson_idis enough.
status: "pending".
When creation is refused
Two people cannot share one email address.
Lifecycle
Wait forcardholder.updated with status: "active" before you issue a card. Most cardholders become active within seconds.
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. Only email and phone are passed on to the card processor; a name change updates Dakota’s record only. A phone or email the card processor cannot accept returns 400.
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. That refusal currently arrives as a
502whosedetailsays how many cards are still open, so check that every card is closed before you delete. DELETE /cardholders/{cardholder_id}.
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.
