Here is a full guide to card creation, management, and lifecycle
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.