First Leeward

Cards

List cards

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

Retrieves a paginated list of cards. Use cursor-based pagination. Filter by accountId to get cards for a specific account. Pass includeTotalCount=true to also get the number of cards matching the filters.

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

Query Parameters

limitintegerdefault: 20

Maximum number of items to return (1-100, default: 20)

cursorstring

Opaque cursor for pagination. Pass nextCursor from previous response to get next page.

idstring<uuid>

Filter cards by exact ID match

statusstring[]

Filter cards by status (comma-separated)

Available options:ACTIVEFROZENBLOCKEDEXPIRED
typestring[]

Filter cards by type (comma-separated)

Available options:VIRTUALPHYSICAL
physicalCardStatusstring[]

Filter cards by physical card lifecycle status (comma-separated). Only meaningful for PHYSICAL cards.

Available options:NOT_ORDEREDREQUESTEDIN_PRODUCTIONPRODUCTION_COMPLETEDIN_TRANSITOUT_FOR_DELIVERYDELIVEREDACTIVATEDCANCELEDDELIVERY_FAILEDEXCEPTION
accountIdstring<uuid>[]

Filter cards by account ID(s) (comma-separated)

userIdstring<uuid>[]

Filter cards by user ID(s) (comma-separated)

includeTotalCountstring

When true, the response includes totalCount, the number of items matching the filters across all pages. Counting adds work to the request, so pass it only on the first page and only when you need it.

Response

200Response for status 200
itemsobject[]required
Show child attributes
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

nextCursorstring | nullrequired

Cursor for next page, or null if no more items

totalCountinteger

Number of items matching the filters across all pages, ignoring cursor and limit. Present only when includeTotalCount=true.