💳 Cards API: How to Use It

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	`/v3/cards`	GET
Find cards by uuid	`/v3/cards/{uuid}`	GET
Create cards	`/v3/cards/bulk-create`	POST
Single create card	`/v3/cards`	POST
Update cards threshold	`/v3/cards/{uuid}/threshold`	PATCH
Lock/unlock cards	`/v3/cards/{uuid}/lock`	PATCH
Delete card	`/v3/cards/{uuid}`	DELETE
Delete cards	`/v3/cards/delete`	POST

1️⃣ Find All Cards

List all cards in your account.

🔗 Endpoint

GET /v3/cards

📤 cURL Request

curl -X GET
"https://public-api.mx.clara.com/api/v3/transactions/47f8ed9e-4d7b-450b-ad6a-f1d83e3ce4e1/documents" \ 
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"

📥 Sample JSON Response

[
  {
    "uuid": "5d1e2f83-1c90-4c34-9400-bfef9ac85c6e",
    "lastFour": "3421",
    "type": "virtual",
    "status": "active",
    "name": "Marketing Card",
    "holderUuid": "f3a9cb88-894b-4420-aed3-6178cd41721d"
  }
]

📋 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 /v3/cards/{uuid}

📤 cURL Request

curl -X GET \
"https://public-api.mx.clara.com/api/v3/cards/5d1e2f83-1c90-4c34-9400-bfef9ac85c6e" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"

📥 Sample JSON Response

{
  "uuid": "5d1e2f83-1c90-4c34-9400-bfef9ac85c6e",
  "lastFour": "3421",
  "type": "virtual",
  "status": "active",
  "name": "Marketing Card",
  "issuedAt": "2024-04-01T12:00:00Z"
}

3️⃣ Create Cards (Bulk)

Create multiple cards asynchronously.

🔗 Endpoint

POST /v3/cards/bulk-create

📤 cURL Request

curl -X POST \
"https://public-api.mx.clara.com/api/v3/cards/bulk-create" \
-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 /v3/cards

📤 cURL Request

curl -X POST \
"https://public-api.mx.clara.com/api/v3/cards" \
-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 /v3/cards/{uuid}/threshold

📤 cURL Request

curl -X PATCH \
"https://public-api.mx.clara.com/api/v3/cards/abc-123/threshold" \
-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 /v3/cards/{uuid}/lock

📤 cURL Request

curl -X PATCH \
"https://public-api.mx.clara.com/api/v3/cards/abc-123/lock" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"lock": true}'

7️⃣ Delete a Card

Cancel (soft-delete) a single card.

🔗 Endpoint

DELETE /v3/cards/{uuid}

📤 cURL Request

curl -X DELETE \
"https://public-api.mx.clara.com/api/v3/cards/abc-123" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"

8️⃣ Delete Multiple Cards

Cancel multiple cards in one request.

🔗 Endpoint

POST /v3/cards/delete

📤 cURL Request

curl -X POST \
"https://public-api.mx.clara.com/api/v3/cards/delete" \
-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.