Skip to main content
POST
Create card

Authorizations

x-api-key
string
header
required

Enter your API key

Headers

Idempotency-Key
string

Optional but recommended. Without it, Direct does not deduplicate repeated card-creation requests. A unique value you choose for each intended card, for example new-card-{userId}-2026-09-23; save it and reuse it only for retries of that card. Sending the same key again with the same body and API version within 24 hours returns the original result instead of creating a second card; reusing it with a different body returns IDEMPOTENCY_KEY_REUSED. If the first request failed with a timeout or an unexpected error on our side, the card may exist, so the same key returns IDEMPOTENCY_KEY_OUTCOME_UNKNOWN instead of trying again. An empty card list does not prove that no card was created: a new card may not be listed straight away, and a request waiting for approval is not listed until it is approved. Use a new key to repeat the creation only once you have confirmed the first request created neither a card nor a pending approval: check pending approvals in the dashboard and list your cards again after a few minutes. Empty lists alone do not confirm it, and neither does the key expiring after 24 hours; contact support with the requestId if you still cannot tell. See Idempotency for retention and recovery. Errors that mean no card was created, such as CARD_CREATION_BUSY and CARD_CREATION_UNAVAILABLE, release the key, so you can retry with the same key.

Body

application/json
type
enum<string>
required

The kind of card to create. Only virtual cards can be created through the API.

Available options:
virtual
title
string
required

A nickname for the card, up to 255 characters, shown in the dashboard and returned by the API. Say who or what the card is for, for example Ada – Marketing tools.

Maximum string length: 255
Pattern: \S
cardholderId
string
required

The userId of the team member who will hold the card, from List team members. The team member must have inviteStatus approved, or the request fails with CARDHOLDER_NOT_FOUND.

category
string<uuid>
required

The ID of the card category, from List card categories, or the request fails with CARD_CATEGORY_NOT_FOUND. It labels what the card is for and doesn't limit where it can be used.

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
planType
enum<string>

How the card is funded: subscription (the default) draws on your shared credit within the card's limits, and topUp gives the card its own fixed budget, set in spendCap.

Available options:
subscription,
topUp
isRevolving
boolean

Whether the card draws from your business's shared revolving budget. Leave it out or set it to false for top-up cards.

expiresAt
string<date> | null

The date you want the card to expire (YYYY-MM-DD). Leave it out to use the standard expiry date.

Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$
spendCap
object

The fixed budget for a top-up card, for example 500.00 USD. It's required when planType is topUp, and the card declines card transactions once it's used up.

spendControl
object

Spending limits to put on the card: per card transaction, or per day, week, month, year or lifetime. Set only the ones you need. No limit can be more than a limit for a longer period: for example, daily can't be more than monthly, and transaction can't be more than any period limit.

restriction
object

The hours of the day when the card can be used, in UTC. Leave it out to allow use at any time.

message
string | null

An optional note saved with the card request, up to 255 characters, for example to explain the request to an approver.

Maximum string length: 255

Response

Card created. You usually get the full card back; if it's still being set up, you get { id, status: pending } instead, and can fetch the URL in the Location header until the card is ready.

id
string
required

The card's unique ID. Use it with Retrieve a card, Freeze card and the other card endpoints.

type
enum<string>
required

Whether this is a virtual or a physical card.

Available options:
virtual,
physical
status
enum<string>
required

Where the card is in its lifecycle: pending (a physical card not yet activated), active (ready to use), frozen (paused, can be unfrozen), inactive (not usable for another reason, such as a restricted or blocked card), expiring (a physical card within 90 days of its expiry date), expired or terminated (permanently closed).

Available options:
pending,
active,
frozen,
inactive,
expiring,
expired,
terminated
title
string | null
required

The card's nickname, set when the card was created or renamed with Edit card details.

last4
string | null
required

The last four digits of the card number. To see the full card details, use Reveal card details.

expiresAt
string<date> | null
required

The date the card expires (YYYY-MM-DD).

Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$
isRevolving
boolean
required

Whether the card draws from your business's shared revolving budget. It's always false for top-up cards.

planType
enum<string> | null
required

How the card is funded: subscription (draws on shared credit within its limits), topUp (has its own fixed budget in spendCap) or physical (a physical card plan).

Available options:
physical,
subscription,
topUp,
null
category
string | null
required

The display name of the card category chosen when the card was created, for example Travel. It describes what the card is for and is different from each card transaction's category. To create a card with this category, pass its id from List card categories.

cardholder
object
required

The team member the card belongs to.

spendCap
object | null
required

The fixed budget set aside for the card; for top-up cards, this is how much the card can spend in total. Change it with Update spend control. Null if the card has no fixed budget.

spentAmount
object
required

How much has been spent on the card since it was created. For top-up cards, compare it with spendCap to see how much budget is left.

spendControl
object
required

The card's spending limits, plus how much has been spent in each period so far.

restriction
object
required

Rules on when and in which transaction categories the card can be used. Change them with Update card usage restriction.

createdAt
string<date-time>
required

When the card was created, in UTC.

Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
updatedAt
string<date-time>
required

When the card's details, limits or status last changed, in UTC.

Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$