> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lead.bank/llms.txt
> Use this file to discover all available pages before exploring further.
# Cards API Overview
> Report physical and virtual card issuance to Lead with the Cards API, including creation, retrieval, activation, deactivation, and closure of cards.
## 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](https://docs.lead.bank/api-integrations/entity/overview) and [Accounts](https://docs.lead.bank/api-integrations/accounts/overview) APIs in the compliance onboarding sequence:
Create the entity record for your cardholder.
Submit the underwriting outcome during the cardholder’s onboarding.
Only certain programs will have an underwriting process; programs without underwriting can skip this step.
Create the account the card will be linked to, and link the cardholder entity to it as an `account_holder` or `authorized_user`.
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**
```json theme={null}
{
"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.