> ## Documentation Index
> Fetch the complete documentation index at: https://developers.clara.team/llms.txt
> Use this file to discover all available pages before exploring further.

# Clara API

> REST API for programmatic access to corporate cards, transactions, users, invoices, and spend management across Mexico, Brazil, and Colombia.

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:

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

```bash theme={null}
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](/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.

```bash theme={null}
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:

```json theme={null}
{
  "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

<CardGroup cols={2}>
  <Card title="Card Management" icon="credit-card" href="/v3/cards">
    Issue physical and virtual cards, set spending limits, lock/unlock, and configure merchant and time restrictions.
  </Card>

  <Card title="Transactions" icon="receipt" href="/v3/transactions">
    List, filter, and export transactions with full merchant, user, label, and accounting data.
  </Card>

  <Card title="User Provisioning" icon="users" href="/v3/users">
    Create, update, and deactivate users. Manage roles, cost centers, and manager assignments.
  </Card>

  <Card title="Invoices & Fiscal Docs" icon="file-invoice" href="/v3/invoices">
    Retrieve CFDI fiscal invoices and extracted documents linked to transactions. Mexico only.
  </Card>

  <Card title="Reconciliation" icon="table" href="/v3/billing-statements">
    Access monthly billing statements with embedded transaction detail for automated reconciliation.
  </Card>

  <Card title="Reimbursements" icon="arrow-left-arrow-right" href="/v3/reimbursements">
    Query and manage employee reimbursement records by date, status, or requester.
  </Card>

  <Card title="Digital Account" icon="building-columns" href="/v3/digital-account">
    Retrieve PIX, TED, and bill payment transactions for Brazil digital accounts.
  </Card>

  <Card title="Virtual Cards (VCN)" icon="shield-check" href="/vcn/introduction">
    Generate and manage Virtual Card Numbers for controlled B2B purchasing with spending rules.
  </Card>

  <Card title="Clara MCP" icon="robot" href="/mcp/introduction">
    Connect Claude, ChatGPT, Gemini, or any MCP-compatible AI assistant directly to Clara data.
  </Card>
</CardGroup>

## 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](/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.