Cards API - Clara API

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

1⃣ Find All Cards

List all cards in your account.

Endpoint

GET /api/v3/cards

cURL Request

cURL

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

{
  "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 -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

{
  "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"
  }
}

3⃣ Create Cards (Bulk)

Create multiple cards asynchronously.

Endpoint

POST /api/v3/cards/bulk-create

cURL Request

cURL

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.

4⃣ Create Single Card

Create one card directly.

Endpoint

POST /api/v3/cards

cURL Request

cURL

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 -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}'

6⃣ Toggle Card Lock

Lock or unlock a card.

Endpoint

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

cURL Request

cURL

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)

{
  "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}.

7⃣ Delete a Card

Cancel (soft-delete) a single card.

Endpoint

DELETE /api/v3/cards/{uuid}

cURL Request

cURL

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"

8⃣ Delete Multiple Cards

Cancel multiple cards in one request.

Endpoint

POST /api/v3/cards/delete

cURL Request

cURL

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"]
}'

⚠️ 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	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:

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

Response (202):

{
  "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:

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

Response (202):

{
  "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" }
  ]
}

​1⃣ Find All Cards

​Endpoint

​cURL Request

​Sample JSON Response

​Query Parameters

​2⃣ Find Card by UUID

​Endpoint

​cURL Request

​Sample JSON Response

​3⃣ Create Cards (Bulk)

​Endpoint

​cURL Request

​4⃣ Create Single Card

​Endpoint

​cURL Request

​Request Body Fields

​5⃣ Update Card Threshold

​Endpoint

​cURL Request

​6⃣ Toggle Card Lock

​Endpoint

​cURL Request

​Request Body

​Response (202 Accepted — async)

​lockCode values

​7⃣ Delete a Card

​Endpoint

​cURL Request

​8⃣ Delete Multiple Cards

​Endpoint

​cURL Request

​Endpoint Reference

​GET /api/v3/cards

​POST /api/v3/cards

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

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

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

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

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

​POST /api/v3/cards/delete

​PATCH /api/v3/cards/lock

​PATCH /api/v3/cards/threshold

1⃣ Find All Cards

Endpoint

cURL Request

Sample JSON Response

Query Parameters

2⃣ Find Card by UUID

Endpoint

cURL Request

Sample JSON Response

3⃣ Create Cards (Bulk)

Endpoint

cURL Request

4⃣ Create Single Card

Endpoint

cURL Request

Request Body Fields

5⃣ Update Card Threshold

Endpoint

cURL Request

6⃣ Toggle Card Lock

Endpoint

cURL Request

Request Body

Response (202 Accepted — async)

lockCode values

7⃣ Delete a Card

Endpoint

cURL Request

8⃣ Delete Multiple Cards

Endpoint

cURL Request

Endpoint Reference

`GET /api/v3/cards`

`POST /api/v3/cards`

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

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

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

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

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

`POST /api/v3/cards/delete`

`PATCH /api/v3/cards/lock`

`PATCH /api/v3/cards/threshold`