Clara API

Clara API gives you programmatic control over every aspect of corporate spend management — issue and manage cards, retrieve transactions, handle users, process invoices, and generate reconciliation reports. All through a consistent REST interface with JSON request and response bodies.

Base URLs

Each Clara market operates on its own base URL. Use the one that matches your company’s Clara account.

Market	Base URL
Mexico	`https://public-api.mx.clara.com`
Brazil	`https://public-api.br.clara.com`
Colombia	`https://public-api.co.clara.com`

API Versions

Version	Status	Recommendation
v3	Current	Use for all new integrations
v2	Stable	Supported, not deprecated
v1	Legacy	Avoid for new work

All three versions are documented in this reference. When an endpoint exists in multiple versions, prefer v3.

Authentication

Every request requires two layers of authentication:

Mutual TLS (mTLS) — a valid X.509 client certificate in every request
Bearer token — a JWT obtained from the Auth0 token endpoint

curl --request POST https://public-api.mx.clara.com/oauth/token \
  --header "Authorization: Basic base64(CLIENT_ID:CLIENT_SECRET)"

The response includes an access_token. Pass it as Authorization: Bearer <token> on all subsequent requests, alongside your client certificate. See Authentication for the full setup guide, including certificate provisioning and token refresh.

Quick Start

The following example retrieves your 10 most recent transactions. Replace <BASE_URL> with your market’s base URL and <TOKEN> with a valid Bearer token.

curl --request GET "<BASE_URL>/api/v3/transactions?page=0&size=10" \
  --header "Authorization: Bearer <TOKEN>" \
  --cert client.crt \
  --key client.key

A successful response returns a paginated list of TransactionResponseV3 objects:

{
  "content": [
    {
      "uuid": "e45a6048-5d6a-49be-97c6-3e1b62436152",
      "type": "PURCHASE",
      "transactionLabel": "Aeromexico",
      "status": "AUTHORIZED",
      "merchant": {
        "name": "Aeromexico",
        "mcc": "3006",
        "category": "TRAVEL",
        "categoryCode": 12
      },
      "card": {
        "uuid": "fa466ed3-ed2f-4850-9e6c-1faab27ed6ce",
        "maskedPan": "510979******3540"
      },
      "user": {
        "uuid": "c0fe4109-f528-4d0b-aec3-bd251650bfdc",
        "holderName": "Ana García"
      },
      "amountValue": {
        "currency": "MXN",
        "amount": 1250.00
      },
      "audit": {
        "accountingDate": "2026-05-21",
        "operationDate": "2026-05-21",
        "lastUpdateDate": "2026-05-23"
      }
    }
  ],
  "totalElements": 118,
  "totalPages": 12,
  "size": 10,
  "number": 0
}

What You Can Build

Card Management

Issue physical and virtual cards, set spending limits, lock/unlock, and configure merchant and time restrictions.

Transactions

List, filter, and export transactions with full merchant, user, label, and accounting data.

User Provisioning

Create, update, and deactivate users. Manage roles, cost centers, and manager assignments.

Invoices & Fiscal Docs

Retrieve CFDI fiscal invoices and extracted documents linked to transactions. Mexico only.

Reconciliation

Access monthly billing statements with embedded transaction detail for automated reconciliation.

Reimbursements

Query and manage employee reimbursement records by date, status, or requester.

Digital Account

Retrieve PIX, TED, and bill payment transactions for Brazil digital accounts.

Virtual Cards (VCN)

Generate and manage Virtual Card Numbers for controlled B2B purchasing with spending rules.

Clara MCP

Connect Claude, ChatGPT, Gemini, or any MCP-compatible AI assistant directly to Clara data.

Pagination

List endpoints return paginated responses using page (zero-indexed) and size query parameters.

GET /api/v3/transactions?page=0&size=50

Continue requesting until currentPage equals totalPages - 1, or until a page returns fewer items than size.

Errors

Clara API uses standard HTTP status codes.

Code	Meaning
`200`	Success
`400`	Bad request — invalid parameters or missing required fields
`401`	Unauthorized — missing or invalid Bearer token
`403`	Forbidden — valid token but insufficient permissions
`404`	Not found
`429`	Rate limit exceeded
`500`	Internal server error

Error responses include a JSON body with a message field describing the issue.

Rate Limits

Requests are rate-limited per client certificate. Write endpoints (POST, PATCH, DELETE) have lower limits than read endpoints (GET). If you receive a 429, back off and retry with exponential backoff. See Error Handling for a retry implementation example, or contact your Clara integration team for limit increases.

Sandbox

A sandbox environment is available for testing. Use the same base URL structure with the /api-test/ path prefix:

GET https://public-api.mx.clara.com/api-test/v3/transactions

Contact your Clara integration team for sandbox credentials.

Overview

Conventions

Guides

Resources

API Reference

MCP

VCN

Base URLs

API Versions

Authentication

Quick Start

What You Can Build

Card Management

Transactions

User Provisioning

Invoices & Fiscal Docs

Reconciliation

Reimbursements

Digital Account

Virtual Cards (VCN)

Clara MCP

Errors

Rate Limits

Sandbox

​Base URLs

​API Versions

​Authentication

​Quick Start

​What You Can Build

Card Management

Transactions

User Provisioning

Invoices & Fiscal Docs

Reconciliation

Reimbursements

Digital Account

Virtual Cards (VCN)

Clara MCP

​Pagination

​Errors

​Rate Limits

​Sandbox

Base URLs

API Versions

Authentication

Quick Start

What You Can Build

Pagination

Errors

Rate Limits

Sandbox