Cards API Overview - Lead

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:

Entity API

Create the entity record for your cardholder.

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.

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.

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

Method	Path	Purpose
`POST`	`/v0/cards`	Create 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}/activate`	Activate an `inactive` card.
`POST`	`/v0/cards/{id}/deactivate`	Deactivate an `active` card.
`POST`	`/v0/cards/{id}/close`	Close a card.

Card Object

Attribute	Type	Description
`id`	string	Unique identifier for the card. Prefixed with `card_`. Server-generated and read-only.
`client_card_id`	string	Client-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_id`	string	Unique ID of the associated customer entity. Prefixed with `entity_`.
`account_id`	string	Unique ID of the associated account. Prefixed with `account_`.
`created_at`	timestamp	Lead server-generated ISO 8601 timestamp when the card was created.
`updated_at`	timestamp	Lead server-generated ISO 8601 timestamp when the card was last updated.
`status`	string	Current status of the card. Possible values: `active`, `inactive`, `closed`. Set by the system.
`status_reason`	string	Reason for the current card status. Set via the status-transition endpoints.
`details`	object	Detailed attributes of the card. See `details` object below.
`metadata`	json	Arbitrary key-value pairs for storing additional information related to this object.

`details` (sub-object)

Attribute	Type	Description
`card_product_name`	string	The name of the card product in your system.
`is_virtual`	boolean	`true` if the card exists as a virtual card; `false` if a physical representation exists.
`card_type`	string	The type of card. Possible values: `hsa`, `fsa`, `consumer`, `commercial`.
`expiry_date`	date	Date 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_for`	string	The `card_id` of the card this card replaces. The referenced card must be in a `closed` status. Set on creation; immutable.
`last_four`	string	Last four digits of the card’s PAN. Must match `^[0-9]{4}$`.
`closed_at`	timestamp	ISO 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.

​Introduction

​Authentication

​Endpoints

​Card Object

​details (sub-object)

​Key Concepts

Introduction

Authentication

Endpoints

Card Object

`details` (sub-object)

Key Concepts