Skip to main content

​
Introduction

The Cards API reports physical and virtual card data to Lead for compliance oversight. Use it to notify Lead when cards are created with your issuer processor, retrieve card details, and manage each card through its full lifecycle — from activation and deactivation to closure. You’ll integrate with this API if you issue physical or virtual cards (for example, consumer, commercial, HSA, or FSA cards) to your customers. The Cards API sits downstream of the Entity and Accounts APIs in the compliance onboarding sequence:
1

Entity API

Create the entity record for your cardholder.
2

Applications API

Submit the underwriting outcome during the cardholder’s onboarding.
Only certain programs will have an underwriting process; programs without underwriting can skip this step.
3

Accounts API

Create the account the card will be linked to, and link the cardholder entity to it as an account_holder or authorized_user.
4

Cards API

Create the card, referencing the account_id and entity_id from the prior steps.
Accounts are created in active status. You can manage the account lifecycle through dedicated status-transition endpoints — activate, deactivate, and close.
A separate OpenAPI spec covers the full schema definition for request and response bodies. This page provides conceptual context for integrating with the API.

​
Authentication

Access is controlled via OAuth scopes:
  • card/read_write: Required for POST and PATCH requests and for all status-transition endpoints (/activate, /deactivate, /close). Grants both read and write access.
  • card/read: Sufficient for GET /v0/cards/{id}. Grants read-only access.
Use the least-privileged scope appropriate to the operation you’re performing. The Card object links to an account_id and an entity_id, which are sensitive tokens; the associated Entity objects (managed by the Entity API) hold the actual PII and are not exposed via the Cards API.
All endpoints are available in both Sandbox and Production. Versioning is handled via a prefix in the URI path (/v0/). This is the V0 API; we’ll add non-breaking changes to V0, and breaking changes will require a new version.

​
Endpoints

MethodPathPurpose
POST/v0/cardsCreate a new card.
GET/v0/cards/{id}Retrieve a specific card by ID.
PATCH/v0/cards/{id}Update a card’s card_product_name and/or metadata.
POST/v0/cards/{id}/activateActivate an inactive card.
POST/v0/cards/{id}/deactivateDeactivate an active card.
POST/v0/cards/{id}/closeClose a card.

​
Card Object

AttributeTypeDescription
idstringUnique identifier for the card. Prefixed with card_. Server-generated and read-only.
client_card_idstringClient-provided identifier for the card. Populated only for cards created via file upload; cards created through the API are identified solely by their server-generated ID.
entity_idstringUnique ID of the associated customer entity. Prefixed with entity_.
account_idstringUnique ID of the associated account. Prefixed with account_.
created_attimestampLead server-generated ISO 8601 timestamp when the card was created.
updated_attimestampLead server-generated ISO 8601 timestamp when the card was last updated.
statusstringCurrent status of the card. Possible values: active, inactive, closed. Set by the system.
status_reasonstringReason for the current card status. Set via the status-transition endpoints.
detailsobjectDetailed attributes of the card. See details object below.
metadatajsonArbitrary key-value pairs for storing additional information related to this object.

​
details (sub-object)

AttributeTypeDescription
card_product_namestringThe name of the card product in your system.
is_virtualbooleantrue if the card exists as a virtual card; false if a physical representation exists.
card_typestringThe type of card. Possible values: hsa, fsa, consumer, commercial.
expiry_datedateDate the card expires (YYYY-MM-DD). Always expressed as the last day of the month — e.g., if expiration is 01/29, the value is 2029-01-31.
replacement_forstringThe card_id of the card this card replaces. The referenced card must be in a closed status. Set on creation; immutable.
last_fourstringLast four digits of the card’s PAN. Must match ^[0-9]{4}$.
closed_attimestampISO 8601 timestamp when the card was closed. Empty unless the card is in a closed status; set by the system based on the most recent /close call. Server-managed and read-only.
Example Card Object 
{
  "id": "card_abc123def456ghi789",
  "client_card_id": "id_123def456ghi789",
  "created_at": "2025-10-20T14:25:00Z",
  "updated_at": "2025-10-25T14:30:00Z",
  "account_id": "account_9h8g7f6e5d4c3b2a",
  "entity_id": "entity_mno456pqr789",
  "status": "active",
  "status_reason": "",
  "details": {
    "card_product_name": "Corporate Plus Rewards",
    "is_virtual": true,
    "card_type": "commercial",
    "expiry_date": "2028-10-31",
    "replacement_for": "card_1234523",
    "last_four": "1234",
    "closed_at": ""
  },
  "metadata": {}
}

​
Key Concepts

Lifecycle and the Action-endpoint Status Model A card transitions through three states: active, inactive, and closed. When you create a card via POST /v0/cards, it starts directly in the active state. You make status changes exclusively through the dedicated action endpoints (/activate, /deactivate, /close) — you cannot set the status field via POST or PATCH. The Closed State is Terminal By default, closed is a terminal state. Support for moving a card from closed back to active or inactive is intended only to correct an accidental or erroneous closure. If a status was reported incorrectly, it can be corrected through the API. E.g., if a card was accidentally reported as closed, you can call the /activate endpoint to return it to an active status.  Entity and Account Prerequisites The entity and account a card references must exist before you create the card, and the entity must already be linked to the account as an account_holder or authorized_user. Capture the account_id and entity_id from the Accounts and Entity APIs and supply them on your card creation request. Replacement Cards When you issue a replacement, set details.replacement_for on the new card to the card_id of the closed card it replaces. This replaces the pattern used in the prior version of Lead’s product based on file uploads, where you were requested to include the “replacing” card’s ID when closing the “replaced” card. This is so that you don’t need to create the new card first just to obtain its ID and then patch the old card’s status.