API Reference

💳 Cards API: How to Use It

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.

OperationEndpointMethod
Find all cards/v3/cardsGET
Find cards by uuid/v3/cards/{uuid}GET
Create cards/v3/cards/bulk-createPOST
Single create card/v3/cardsPOST
Update cards threshold/v3/cards/{uuid}/thresholdPATCH
Lock/unlock cards/v3/cards/{uuid}/lockPATCH
Delete card/v3/cards/{uuid}DELETE
Delete cards/v3/cards/deletePOST

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

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

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.