> ## 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 Best Practices

> Guidance on OAuth scopes, idempotency keys, replacement cards, expiry date handling, and resource sequencing when integrating with the Lead Cards API.

### Use the Correct Authentication Scope

Choose the right OAuth scope before making any API call. `POST /v0/cards`, `PATCH /v0/cards/{id}`, and the action endpoints require `card/read_write`; `GET /v0/cards/{id}` accepts `card/read` or `card/read_write`. Use the least-privileged scope appropriate to the operation. If your integration only needs to retrieve cards, use `card/read` and avoid provisioning broader write access.

### Use Idempotency Keys on POST and PATCH

Always include a unique `Idempotency-Key` header on every `POST /v0/cards` request. Use a UUID (e.g., `550e8400-e29b-41d4-a716-446655440000`).

Key behaviors to be aware of:

* If a request fails with a 4xx error (except 409 Conflict), the idempotency key was not consumed. Generate a new key before retrying — the same key can only be reused for the exact same request body.
* If a request succeeds (200), reusing the same idempotency key returns the cached response without creating a duplicate card.
* Omitting the `Idempotency-Key` header results in a 400 operation\_not\_allowed error.

### Sequence Resource Creation Correctly

Because the API is synchronous and per-resource, you are responsible for sequencing. Create the Entity and the Account first, capture their IDs, and use them when creating the card. The card cannot be created until both the referenced entity and account exist, and the entity must already be linked to the account as an account holder or authorized user.

### Use replacement\_for for Replacement Cards

When issuing a replacement, set `details.replacement_for` to the `card_id` of the card being replaced on the new card's creation request. The old card must already be in a `closed` status. This pattern means you do not need to create the new card first just to obtain its ID and then patch the old card.

### Treat Expiry Dates as End-of-Month

Always set `expiry_date` to the last calendar day of the expiration month. This keeps reported expirations consistent with how card networks treat the expiry month.

### Use metadata for Your Own Context

The optional `metadata` object is the supported place to store your own key-value context on a card, and it is one of only two fields editable after creation. Avoid encoding such context into immutable fields.\\

### Correcting an Accidentally Closed Card

The action endpoints exist primarily to support normal lifecycle progression. If a card is closed in error, moving it back to `active` (via `/activate`) or `inactive` (via `/deactivate`) is intended only as an error-correction path — it may not be enabled for your program during beta. If you close a card in error, contact your Lead representative to confirm whether the reopen path is available.