First Leeward

Cards

Create card

POSThttps://api.firstleeward.com/v0/cards

Creates a new virtual or physical card for a user. User must have approved application; account must be active. The phone number used for OTP verification is taken from the user record; the card is issued against the user's verified identity. On corporate employee projects there is no cardholder KYC, and the card is issued under the employee's company instead.

Authorizations

Authorizationstring · headerrequired

API key as Bearer token, e.g. Bearer YOUR_API_KEY

Headers

Leeward-Versionenum<string>required

API version (YYYY-MM-DD). Available option: 2026-09-18

Idempotency-Keystringrequired

Unique key for safely retrying this request. Up to 255 characters; we recommend a UUIDv4. The first request executes and its response is cached; subsequent requests with the same key replay the cached response (24h retention).

Body

application/json

userIdstring<uuid>required

ID of the user to create the card for

accountIdstring<uuid>required

ID of the account to link the card to

typestringrequired

Card type (VIRTUAL or PHYSICAL)

Available options:VIRTUALPHYSICAL
3dsChallengeMethodstringdefault: "SMS"

3DS challenge verification method. Defaults to SMS if not specified.

Available options:SMSWEBHOOK
cardDesignIdstring

Card design to use. Defaults to the project default design when not specified. Throws error when default is not configured and no value is passed here.

Response

200Card resource
idstring<uuid>required

Unique card identifier

accountIdstring<uuid>required

ID of the account the card belongs to

userIdstring<uuid>required

ID of the user the card belongs to

typestringrequired

Card type (VIRTUAL or PHYSICAL)

Available options:VIRTUALPHYSICAL
cardDesignIdstringrequired

Design the card was issued with. For a physical card this is the design on the card record, which can differ from the one produced: the plastic is made from the design chosen on the shipment, returned as cardDesignId per card on the shipment endpoints.

statusstringrequired

Current card status

Available options:ACTIVEFROZENBLOCKEDEXPIRED
blockReasonobject | nullrequired

Block reason details (only present when status is BLOCKED)

Show child attributes
typestringrequired

Machine-readable code for the block reason

Available options:CLIENT_REQUESTEDSUSPECTED_FRAUD_CVVSUSPECTED_FRAUD_EXPIRYSUSPECTED_FRAUD_PINFRAUD_ALERT_CONFIRMEDOTHER
messagestringrequired

Human-readable message for the block reason

blockLiftablebooleanrequired

Whether the current block can be lifted with the unblock endpoint. false for blocks that need First Leeward support, and for a card that holds no block.

frozenbooleanrequired

Whether the card is frozen. A block hides a freeze from status, so a card that is BLOCKED with frozen: true returns to FROZEN once the block lifts.

cardholderNamestringrequired

Cardholder name displayed on card

last4stringrequired

Last 4 digits of the card number. Use reveal endpoint for full details.

3dsChallengeMethodstringrequired

3DS challenge verification method

Available options:SMSWEBHOOK
physicalCardStatusstring | nullrequired

Physical lifecycle of the card (production + shipping + activation rollup). Defaults to NOT_ORDERED for newly created physical cards. null for virtual cards, which have no physical lifecycle.

Available options:NOT_ORDEREDREQUESTEDIN_PRODUCTIONPRODUCTION_COMPLETEDIN_TRANSITOUT_FOR_DELIVERYDELIVEREDACTIVATEDCANCELEDDELIVERY_FAILEDEXCEPTION
createdAtstringrequired

ISO 8601 timestamp of creation

updatedAtstringrequired

ISO 8601 timestamp of last update

400Response for status 400
Option 1 · UserApplicationNotApprovedError
errorobjectrequired
Show child attributes
codestringrequired
messagestringrequired
detailobject | nullrequired
Option 2 · CardholderCountryNotSupportedError
errorobjectrequired
Show child attributes
codestringrequired
messagestringrequired
detailobject | nullrequired
Option 3 · CardCompanyNotFoundError
errorobjectrequired
Show child attributes
codestringrequired
messagestringrequired
detailobject | nullrequired
Option 4 · CardCompanyNotActiveError
errorobjectrequired
Show child attributes
codestringrequired
messagestringrequired
detailobject | nullrequired
Option 5 · CardAccountNotFoundError
errorobjectrequired
Show child attributes
codestringrequired
messagestringrequired
detailobject | nullrequired
Option 6 · AccountOwnerMismatchError
errorobjectrequired
Show child attributes
codestringrequired
messagestringrequired
detailobject | nullrequired
Option 7 · AccountNotActiveError
errorobjectrequired
Show child attributes
codestringrequired
messagestringrequired
detailobject | nullrequired
Option 8 · AccountNotEligibleError
errorobjectrequired
Show child attributes
codestringrequired
messagestringrequired
detailobject | nullrequired
Option 9 · CardDesignNotActiveError
errorobjectrequired
Show child attributes
codestringrequired
messagestringrequired
detailobject | nullrequired
Option 10 · DefaultCardDesignNotConfiguredError
errorobjectrequired
Show child attributes
codestringrequired
messagestringrequired
detailobject | nullrequired
Option 11 · CardCompanyNotReadyForIssuanceError
errorobjectrequired
Show child attributes
codestringrequired
messagestringrequired
detailobject | nullrequired
Option 12 · CardEmailDomainNotValidatedError
errorobjectrequired
Show child attributes
codestringrequired
messagestringrequired
detailobject | nullrequired
404Response for status 404
Option 1 · CardUserNotFoundError
errorobjectrequired
Show child attributes
codestringrequired
messagestringrequired
detailobject | nullrequired
Option 2 · CardDesignNotFoundError
errorobjectrequired
Show child attributes
codestringrequired
messagestringrequired
detailobject | nullrequired
409Response for status 409
Option 1 · CardQuotaExceededError
errorobjectrequired
Show child attributes
codestringrequired
messagestringrequired
detailobject | nullrequired
Option 2 · AuthorizationEndpointRequiredError
errorobjectrequired
Show child attributes
codestringrequired
messagestringrequired
detailobject | nullrequired
503Service is temporarily unavailable. Please retry.
errorobjectrequired
Show child attributes
codestringrequired
messagestringrequired
detailobject | nullrequired