> ## Documentation Index
> Fetch the complete documentation index at: https://developers.clara.team/llms.txt
> Use this file to discover all available pages before exploring further.

# Cards API

> Create, update, activate, lock, and delete virtual and physical cards.

Clara's Cards API lets you manage **physical and virtual cards** for your users and teams. You can create cards, retrieve details, update names, change statuses, and more — all programmatically.

| Operation                          | Endpoint                              | Method |
| ---------------------------------- | ------------------------------------- | ------ |
| Find all cards                     | `/api/v3/cards`                       | GET    |
| Find card by UUID                  | `/api/v3/cards/{uuid}`                | GET    |
| Find all card requests by batch ID | `/api/v3/cards/requests/batches/{id}` | GET    |
| Find all card requests by ID       | `/api/v3/cards/requests/{id}`         | GET    |
| Find all card requests             | `/api/v3/cards/requests`              | GET    |
| Create cards                       | `/api/v3/cards/bulk-create`           | POST   |
| Single create card                 | `/api/v3/cards`                       | POST   |
| Update single card threshold       | `/api/v3/cards/{uuid}/threshold`      | PATCH  |
| Update multiple cards threshold    | `/api/v3/cards/threshold`             | PATCH  |
| Lock/unlock a single card          | `/api/v3/cards/{uuid}/lock`           | PATCH  |
| Lock/unlock multiple cards         | `/api/v3/cards/lock`                  | PATCH  |
| Delete card                        | `/api/v3/cards/{uuid}`                | DELETE |
| Delete cards                       | `/api/v3/cards/delete`                | POST   |

<br />

## 1⃣ Find All Cards

List **all cards** in your account.

### Endpoint

`GET /api/v3/cards`

### cURL Request

```curl cURL theme={null}
curl -X GET "https://public-api.mx.clara.com/api/v3/cards/" \
--cert /path/to/client-cert.pem \
--key /path/to/client-key.pem \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

### Sample JSON Response

```json JSON theme={null}
{
  "content": [
    {
      "uuid": "dd9bf99c-648b-419d-8316-32201ef91289",
      "claraStatus": "ACTIVE",
      "status": "ACTIVE",
      "lockCode": "UNLOCKED",
      "alias": "Marketing Card",
      "threshold": 1000.0,
      "periodicity": "MONTHLY",
      "maskedPan": "510979******9579",
      "type": "MASTER_VIRTUAL",
      "user": {
        "uuid": "c3fb1f07-5e7f-47b8-9819-0b09151b8099",
        "fullName": "Ana García",
        "username": "ana.garcia@company.com"
      }
    }
  ],
  "totalElements": 379,
  "totalPages": 190,
  "size": 2,
  "number": 0
}
```

### Query Parameters

| **Parameter** | **Type**  | **Description**                                                               | **Valid Values / Notes**                                        |
| ------------- | --------- | ----------------------------------------------------------------------------- | --------------------------------------------------------------- |
| `page`        | `integer` | Zero-based index of the page to retrieve. Used for pagination.                | `0..N`                                                          |
| `size`        | `integer` | Number of records to retrieve per page.                                       | Max allowed may depend on backend constraints                   |
| `userUuid`    | `string`  | Filter cards that belong to a specific user by UUID.                          | Cannot be used in combination with `userErpId`                  |
| `username`    | `string`  | Filter cards by the associated user's username (email/handle).                | Must be exact match                                             |
| `status`      | `string`  | Filter by card status.                                                        | e.g., `ACTIVE`, `BLOCKED`, `CANCELLED`, `EXPIRED`, etc.         |
| `periodicity` | `string`  | Filter cards by their spending limit periodicity.                             | `DAILY`, `WEEKLY`, `MONTHLY`                                    |
| `type`        | `string`  | Filter by the card’s product and format type.                                 | See full list below                                             |
| `userErpId`   | `string`  | ERP-specific user identifier. Applies only if `userUuid` is **not** provided. | Used for integrations with ERP systems like SAP, NetSuite, etc. |

✅ Valid Values for type

| **Value**            | **Description**                               |
| -------------------- | --------------------------------------------- |
| `MASTER_WORLD_ELITE` | Mastercard-branded premium "World Elite" card |
| `MASTER_CORPORATE`   | Mastercard corporate-level card               |
| `MASTER_VIRTUAL`     | Virtual Mastercard                            |
| `VISA_PHYSICAL`      | Physical Visa card                            |
| `VISA_VIRTUAL`       | Virtual Visa card                             |

⚠️ This field represents a combination of network + format + product line (not just "VIRTUAL" / "PHYSICAL" like in the POST endpoint).

## 2⃣ Find Card by UUID

Fetch a **single card** by its UUID.

### Endpoint

`GET /api/v3/cards/{uuid}`

### cURL Request

```curl cURL theme={null}
curl -X GET "https://public-api.mx.clara.com/api/v3/cards/5d1e2f83-1c90-4c34-9400-bfef9ac85c6e" \
--cert /path/to/client-cert.pem \
--key /path/to/client-key.pem \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

### Sample JSON Response

```json JSON theme={null}
{
  "uuid": "dd9bf99c-648b-419d-8316-32201ef91289",
  "claraStatus": "ACTIVE",
  "status": "ACTIVE",
  "lockCode": "UNLOCKED",
  "alias": "Marketing Card",
  "threshold": 1000.0,
  "periodicity": "MONTHLY",
  "maskedPan": "510979******9579",
  "type": "MASTER_VIRTUAL",
  "cvv": "705",
  "expiryDate": "12/30",
  "numberOnCard": "5109790205009579",
  "user": {
    "uuid": "c3fb1f07-5e7f-47b8-9819-0b09151b8099",
    "fullName": "Ana García",
    "username": "ana.garcia@company.com"
  }
}
```

<br />

## 3⃣ Create Cards (Bulk)

Create multiple cards asynchronously.

### Endpoint

`POST /api/v3/cards/bulk-create`

### cURL Request

```curl cURL theme={null}
curl -X POST "https://public-api.mx.clara.com/api/v3/cards/bulk-create" \
--cert /path/to/client-cert.pem \
--key /path/to/client-key.pem \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "cardsRequests": [
    {
      "type": "virtual",
      "alias": "Ops Team",
      "userUUID": "user-uuid-1",
      "threshold": 500,
      "periodicityType": "DAILY"
    }
  ]
}'
```

🕑 Cards are created async—monitor via webhook or poll /v3/cards.

<br />

## 4⃣ Create Single Card

Create one card directly.

### Endpoint

`POST /api/v3/cards`

### cURL Request

```curl cURL theme={null}
curl -X POST "https://public-api.mx.clara.com/api/v3/cards" \
--cert /path/to/client-cert.pem \
--key /path/to/client-key.pem \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "type": "physical",
  "alias": "Team Card",
  "userUUID": "user-uuid-2",
  "threshold": 1000,
  "periodicityType": "MONTHLY"
}'
```

### Request Body Fields

| **Field**      | **Type** | **Required** | **Description**                                 | **Valid Values / Notes**                                     |
| -------------- | -------- | ------------ | ----------------------------------------------- | ------------------------------------------------------------ |
| `type`         | `string` | ✅ Yes        | Defines whether the card is virtual or physical | `VIRTUAL`, `PHYSICAL`                                        |
| `alias`        | `string` | ✅ Yes        | Alias or nickname to identify the card          | Free-text                                                    |
| `userUuid`     | `uuid`   | ✅ Yes        | UUID of the cardholder                          | Must belong to a valid user in your organization             |
| `threshold`    | `number` | ❌ No         | Spending limit assigned to the card             | Must respect credit policies and cannot exceed company limit |
| `businessType` | `string` | ❌ No         | Defines the business product tier of the card   | `BUSINESS`, `WORLD_ELITE`                                    |
| `periodicity`  | `string` | ❌ No         | Frequency at which the threshold resets         | `DAILY`, `WEEKLY`, `MONTHLY`                                 |

## 5⃣ Update Card Threshold

Adjust the spending limit for a card.

### Endpoint

`PATCH /api/v3/cards/{uuid}/threshold`

### cURL Request

```curl cURL theme={null}
curl -X PATCH "https://public-api.mx.clara.com/api/v3/cards/abc-123/threshold" \
--cert /path/to/client-cert.pem \
--key /path/to/client-key.pem \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"threshold": 800}'
```

<br />

## 6⃣ Toggle Card Lock

Lock or unlock a card.

### Endpoint

`PATCH /api/v3/cards/{uuid}/lock`

### cURL Request

```curl cURL theme={null}
curl -X PATCH "https://public-api.mx.clara.com/api/v3/cards/abc-123/lock" \
--cert /path/to/client-cert.pem \
--key /path/to/client-key.pem \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"locked": true, "lockCode": 16}'
```

### Request Body

| Field      | Type    | Required | Description                          |
| ---------- | ------- | -------- | ------------------------------------ |
| `locked`   | boolean | ✅        | `true` to lock, `false` to unlock    |
| `lockCode` | integer | ✅        | Must be `16` for API-initiated locks |

### Response (202 Accepted — async)

```json theme={null}
{
  "batchId": "836ce8d6-e767-4a3f-827c-14919413638c",
  "id": "8034e101-adc9-4a65-8cfc-ddd98c4377e0",
  "uuid": "dd9bf99c-648b-419d-8316-32201ef91289",
  "status": "UPDATED"
}
```

### lockCode values

The `lockCode` field identifies who is initiating the lock. Use `16` for API-initiated locks.

| `lockCode` | Initiated by      | Description                                                                      |
| ---------- | ----------------- | -------------------------------------------------------------------------------- |
| `16`       | API / integration | Standard user-initiated lock. Use this for programmatic lock/unlock via the API. |

Locks can also be applied by manager hierarchy (Master Lock) or by Clara's internal team (Clara Blocked). These originate from different sources and cannot be set via the API — they are reflected in the `lockCode` field when you read the card back with `GET /api/v3/cards/{uuid}`.

<br />

## 7⃣ Delete a Card

Cancel (soft-delete) a single card.

### Endpoint

`DELETE /api/v3/cards/{uuid}`

### cURL Request

```curl cURL theme={null}
curl -X DELETE "https://public-api.mx.clara.com/api/v3/cards/abc-123" \
--cert /path/to/client-cert.pem \
--key /path/to/client-key.pem \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

<br />

## 8⃣ Delete Multiple Cards

Cancel multiple cards in one request.

### Endpoint

`POST /api/v3/cards/delete`

### cURL Request

```curl cURL theme={null}
curl -X POST "https://public-api.mx.clara.com/api/v3/cards/delete" \
--cert /path/to/client-cert.pem \
--key /path/to/client-key.pem \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "uuids": ["abc-123", "def-456"]
}'
```

<br />

⚠️ **Important Notes:**

* Threshold changes and locks are allowed only on active cards.
* Locking a card prevents usage; unlocking restores access.
* Deleted cards cannot be recovered.
* Ensure your threshold doesn’t exceed your company’s credit limit.

💡 **Tip:** Use locking to disable lost/stolen cards and delete to permanently remove unused ones.

***

## Endpoint Reference

### `GET /api/v3/cards`

List all cards (v3)

**Parameters:**

| Parameter     | In    | Type          | Required | Description                                          |
| ------------- | ----- | ------------- | -------- | ---------------------------------------------------- |
| `userUuid`    | query | string (uuid) |          | Filter by user UUID                                  |
| `username`    | query | string        |          | Filter by username                                   |
| `status`      | query | string        |          | Filter by card status                                |
| `periodicity` | query | string        |          | Filter by periodicity                                |
| `type`        | query | string        |          | Filter by card type                                  |
| `userErpId`   | query | string        |          | Filter by user ERP ID (only if userUuid not present) |
| `claraStatus` | query | string        |          | \[DEPRECATED] Use 'status' instead                   |

**Response Schema (`CardPageV3`):**

| Field           | Type            | Example |
| --------------- | --------------- | ------- |
| `content`       | array of CardV3 |         |
| `totalElements` | integer         |         |
| `totalPages`    | integer         |         |
| `size`          | integer         |         |
| `number`        | integer         |         |

### `POST /api/v3/cards`

Create card (v3)

**Request Body (`CreateCardRequestV3`):**

| Field          | Type             | Example                                |
| -------------- | ---------------- | -------------------------------------- |
| `type`         | string (enum)    | `VIRTUAL`/`PHYSICAL`                   |
| `alias`        | string           | `Card Name`                            |
| `userUuid`     | string (uuid)    | `a0c82a20-ac09-4cfd-b429-d0623585911e` |
| `threshold`    | number (decimal) | `1000`                                 |
| `businessType` | string (enum)    | `BUSINESS`/`WORLD_ELITE`               |
| `periodicity`  | string (enum)    | `MONTHLY`/`DAILY`                      |

### `GET /api/v3/cards/{uuid}`

Get card by UUID (v3)

**Parameters:**

| Parameter | In   | Type          | Required | Description |
| --------- | ---- | ------------- | -------- | ----------- |
| `uuid`    | path | string (uuid) | ✅        |             |

**Response Schema (`CardV3`):**

| Field          | Type             | Example                                                    |
| -------------- | ---------------- | ---------------------------------------------------------- |
| `uuid`         | string (uuid)    | `a0c82a20-ac09-4cfd-b429-d0623585911e`                     |
| `claraStatus`  | string           | `ACTIVE`                                                   |
| `status`       | string           | `ACTIVE`, `LOCKED`, `MASTER_LOCKED`, `CANCELLED`           |
| `lockCode`     | string           | `UNLOCKED`, `TEMPORAL_LOCKED`                              |
| `alias`        | string           | `Card Name`                                                |
| `threshold`    | number (decimal) | `1000`                                                     |
| `periodicity`  | string           | `MONTHLY`, `DAILY`                                         |
| `maskedPan`    | string           | `514509******5946`                                         |
| `type`         | string           | `MASTER_VIRTUAL`, `MASTER_CORPORATE`, `MASTER_WORLD_ELITE` |
| `user`         | object           | `{uuid, fullName, username, links}`                        |
| `cvv`          | string           | `705` — only present on `GET /{uuid}`                      |
| `expiryDate`   | string           | `12/30` — only present on `GET /{uuid}`                    |
| `numberOnCard` | string           | `5109790205009579` — only present on `GET /{uuid}`         |
| `links`        | array of Link    |                                                            |

### `DELETE /api/v3/cards/{uuid}`

Delete card (v3)

**Parameters:**

| Parameter | In   | Type          | Required | Description |
| --------- | ---- | ------------- | -------- | ----------- |
| `uuid`    | path | string (uuid) | ✅        |             |

### `PATCH /api/v3/cards/{uuid}/lock`

Toggle card lock (v3)

**Parameters:**

| Parameter | In   | Type          | Required | Description |
| --------- | ---- | ------------- | -------- | ----------- |
| `uuid`    | path | string (uuid) | ✅        |             |

**Request Body (`ToggleCardLockRequest`):**

| Field      | Type    | Required | Example                           |
| ---------- | ------- | -------- | --------------------------------- |
| `locked`   | boolean | ✅        | `true` to lock, `false` to unlock |
| `lockCode` | integer | ✅        | `16`                              |

**Response (`202 Accepted`):** `{batchId, id, uuid, status: "UPDATED"}`

### `PATCH /api/v3/cards/{uuid}/threshold`

Update card threshold (v3)

**Parameters:**

| Parameter | In   | Type          | Required | Description |
| --------- | ---- | ------------- | -------- | ----------- |
| `uuid`    | path | string (uuid) | ✅        |             |

**Request Body (`UpdateCardThresholdRequest`):**

| Field       | Type             | Example |
| ----------- | ---------------- | ------- |
| `threshold` | number (decimal) | `5000`  |

### `POST /api/v3/cards/bulk-create`

Bulk create cards (v3)

**Request Body (`BulkCreateCardRequest`):**

| Field   | Type                         | Example |
| ------- | ---------------------------- | ------- |
| `cards` | array of CreateCardRequestV3 |         |

### `POST /api/v3/cards/delete`

Bulk delete cards (v3)

**Request Body (`BulkDeleteCardsRequest`):**

| Field   | Type            | Example |
| ------- | --------------- | ------- |
| `uuids` | array of string |         |

### `PATCH /api/v3/cards/lock`

Bulk toggle card lock (v3). Returns `202 Accepted` — async, result delivered via webhook.

**Request Body:**

| Field               | Type  | Required | Description                                        |
| ------------------- | ----- | -------- | -------------------------------------------------- |
| `cardsLockRequests` | array | ✅        | Each item: `{uuid, locked: boolean, lockCode: 16}` |

**Example:**

```json theme={null}
{
  "cardsLockRequests": [
    { "uuid": "dd9bf99c-648b-419d-8316-32201ef91289", "locked": true, "lockCode": 16 }
  ]
}
```

**Response (`202`):**

```json theme={null}
{
  "id": "9e9fe2c0-a194-4b81-9025-df45753b0f79",
  "message": "Your request has been received but still in progress, you will get the response via webhook",
  "cardsLockResponses": [
    { "batchId": "9e9fe2c0-...", "id": "0dae8e5c-...", "uuid": "dd9bf99c-...", "status": "SENT" }
  ]
}
```

### `PATCH /api/v3/cards/threshold`

Bulk update card thresholds (v3). Returns `202 Accepted` — async, result delivered via webhook.

**Request Body:**

| Field                          | Type  | Required | Description                            |
| ------------------------------ | ----- | -------- | -------------------------------------- |
| `updateCardsThresholdRequests` | array | ✅        | Each item: `{uuid, threshold: number}` |

**Example:**

```json theme={null}
{
  "updateCardsThresholdRequests": [
    { "uuid": "dd9bf99c-648b-419d-8316-32201ef91289", "threshold": 1500.00 }
  ]
}
```

**Response (`202`):**

```json theme={null}
{
  "id": "85e01930-3d69-4aed-85b6-0080d6792c44",
  "message": "Your request has been received but still in progress, you will get the response via webhook",
  "updateCardsThresholdResponses": [
    { "batchId": "85e01930-...", "id": "88d35238-...", "uuid": "dd9bf99c-...", "status": "SENT" }
  ]
}
```