# Attachments
Source: https://developers.clara.team/api-reference/attachments
Retrieve transaction attachments (receipts, supporting documents) and download links.
This service is not yet available in v3. Available in **v2** only.
## What is the Attachments API?
The **Attachments API v2** allows you to retrieve files that have been uploaded and associated with Clara entities, such as transactions, invoices, or reimbursement requests.
Attachments may include receipts, invoices, approval files, or any supporting documentation. With this API, you can:
* List all uploaded files
* Retrieve metadata for a specific attachment
* Download the attachment as a base64-encoded file
## Available Endpoints
| Operation | Endpoint | Method |
| ------------------------------- | ------------------------------- | ------ |
| Get a list of attachments | `/v2/attachments` | GET |
| Get attachment metadata by UUID | `/v2/attachments/{uuid}` | GET |
| Get attachment file as base64 | `/v2/attachments/{uuid}/base64` | GET |
## Get a list of attachments
**Use this endpoint to list all attachments** available to your company. You can optionally filter by entity type or related ID.
### Endpoint
`GET /v2/attachments`
### cURL Request
```curl cURL theme={null}
curl -X GET \
"https://public-api.mx.clara.com/api/v2/attachments" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```
### Sample JSON Response
```json JSON theme={null}
[
{
"uuid": "attachment-001",
"fileName": "receipt_q2.jpg",
"entityUuid": "txn-123",
"entityType": "TRANSACTION",
"mimeType": "image/jpeg",
"createdAt": "2025-06-10T18:22:00Z"
}
]
```
## Get Single Attachment information with the pre signed URL
Use this to retrieve detailed metadata for a specific attachment by its UUID. This includes file name, type, entity association, and creation date.
### Endpoint
`GET /v2/attachments/{uuid}`
### cURL Request
```curl cURL theme={null}
curl -X GET \
"https://public-api.mx.clara.com/api/v2/attachments/attachment-001" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```
## Get Attachment File as Base64
Use this endpoint to download the file in base64 format, allowing you to render or store the file securely in your system
### Endpoint
`GET /v2/attachments/{uuid}/base64`
### cURL Request
```curl cURL theme={null}
curl -X GET \
"https://public-api.mx.clara.com/api/v2/attachments/attachment-001/base64" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```
### Sample JSON Response
```json JSON theme={null}
{
"fileName": "receipt_q2.jpg",
"mimeType": "image/jpeg",
"base64": "/9j/4AAQSkZJRgABAQEAYABgAAD..."
}
```
**π‘ Tip:** You can use the base64 content to display the file inline in web or mobile apps, or decode and store it in your system.
\*\*β οΈ Note: \*\*Attachments can be large. Avoid retrieving large batches unless necessary. Use pagination and lazy-loading in UIs where possible.
***
## Endpoint Reference
### `GET /api/v2/attachments`
Get a list of attachments and it's respective transactions
### `GET /api/v2/attachments/{uuid}`
Get a single attachment information with the pre signed URL
**Parameters:**
| Parameter | In | Type | Required | Description |
| --------- | ---- | ------ | -------- | ---------------------- |
| `uuid` | path | string | β
| UUID of the attachment |
### `GET /api/v2/attachments/{uuid}/base64`
Get a single attachment in base 64
**Parameters:**
| Parameter | In | Type | Required | Description |
| --------- | ---- | ------ | -------- | ---------------------- |
| `uuid` | path | string | β
| UUID of the attachment |
# Billing Statements
Source: https://developers.clara.team/api-reference/billing-statements
Access monthly billing statements and their associated transactions.
Recommended for all new integrations.
The API provides endpoints to:
1. **Retrieve all billing statements**
2. **Retrieve a specific billing statement by UUID**
3. **Retrieve all transactions from a specific billing statement**
Each of these endpoints returns structured financial data, including statement periods, totals, and associated transaction details.
## Retrieve All Billing Statements
Use this endpoint to list **all billing statements** associated with the account.
### Endpoint
`GET /v3/billing-statements`
### cURL Request
```curl cURL theme={null}
curl -X GET \
"https://public-api.mx.clara.com/api/v3/billing-statements" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```
### Sample JSON Response
```curl JSON theme={null}
[
{
"uuid": "e4a50134-447f-4c34-b6b6-78cdb43d3fd5",
"statementStartDate": "2024-06-01",
"statementEndDate": "2024-06-30",
"currency": "MXN",
"totalAmount": 10000.00
}
]
```
## Retrieve a Billing Statement by UUID
Use this endpoint to retrieve the full details of a specific billing statement, including amounts, dates, and metadata.
### Endpoint
`GET /v3/billing-statements/{uuid}`
### cURL Request
```curl cURL theme={null}
curl -X GET \
"https://public-api.mx.clara.com/api/v3/billing-statements/e4a50134-447f-4c34-b6b6-78cdb43d3fd5" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```
### Sample JSON Response
```curl JSON theme={null}
{
"uuid": "e4a50134-447f-4c34-b6b6-78cdb43d3fd5",
"currency": "MXN",
"totalAmount": 10000.00,
"statementStartDate": "2024-06-01",
"statementEndDate": "2024-06-30",
"status": "closed",
"generatedAt": "2024-07-01T10:00:00Z"
}
```
## Retrieve Transactions from a Billing Statement
Use this endpoint to get all transactions associated with a given billing statement.
### Endpoint
`GET /v3/billing-statements/{uuid}/transactions`
### cURL Request
```curl cURL theme={null}
curl -X GET \
"https://public-api.mx.clara.com/api/v3/billing-statements/e4a50134-447f-4c34-b6b6-78cdb43d3fd5/transactions" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```
### Sample JSON Response
```curl JSON theme={null}
[
{
"uuid": "0fa38f1b-8ae6-4ac6-9171-d3dba4dfecbe",
"amount": 1200.00,
"currency": "MXN",
"description": "Flight booking",
"category": "Travel",
"date": "2024-06-10"
}
]
```
π‘ Tip: Billing statements and their transactions are useful for automating your month-end reconciliation process.
β οΈ Note: The sample data shown is for illustrative purposes only and does not represent actual financial or tax calculations.
***
## Endpoint Reference
### `GET /api/v3/billing-statements`
List billing statements (v3)
**Response Schema (`BillingStatementPageV3`):**
| Field | Type | Example |
| --------------- | --------------------------------- | ------- |
| `content` | array of BillingStatementResponse | |
| `totalElements` | integer | |
| `totalPages` | integer | |
| `size` | integer | |
| `number` | integer | |
### `GET /api/v3/billing-statements/current`
Get current billing statement (v3)
**Response Schema (`BillingStatementResponse`):**
| Field | Type | Example |
| ------------------ | ------------- | -------------------------------------- |
| `uuid` | string (uuid) | `221e5a80-0123-1d02-1e23-1fe23d74f5e6` |
| `periodStartDate` | string (date) | `2025-08-03` |
| `periodEndDate` | string (date) | `2025-09-02` |
| `statementDate` | string (date) | `2025-09-02` |
| `currentBalance` | string | `750.01` |
| `requiredPayment` | string | `750.01` |
| `paymentLimitDate` | string (date) | `2025-09-12` |
| `paidAmount` | string | `800.01` |
| `unpaid` | boolean | `False` |
### `GET /api/v3/billing-statements/{uuid}`
Get billing statement by UUID (v3)
**Parameters:**
| Parameter | In | Type | Required | Description |
| --------- | ---- | ------------- | -------- | ----------- |
| `uuid` | path | string (uuid) | β
| |
**Response Schema (`BillingStatementResponse`):**
| Field | Type | Example |
| ------------------ | ------------- | -------------------------------------- |
| `uuid` | string (uuid) | `221e5a80-0123-1d02-1e23-1fe23d74f5e6` |
| `periodStartDate` | string (date) | `2025-08-03` |
| `periodEndDate` | string (date) | `2025-09-02` |
| `statementDate` | string (date) | `2025-09-02` |
| `currentBalance` | string | `750.01` |
| `requiredPayment` | string | `750.01` |
| `paymentLimitDate` | string (date) | `2025-09-12` |
| `paidAmount` | string | `800.01` |
| `unpaid` | boolean | `False` |
## What is the Billing Statements API?
The **Billing Statements API (v2)** provides access to your company's monthly billing statements. Each statement summarizes expenses and payments made during a given billing cycle.
You can use this API to:
* Retrieve the **current billing statement** (the active billing cycle)
* Retrieve a **past billing statement** by specifying the month and year
* Automate reconciliation and reporting processes
## Available Endpoints
| Operation | Endpoint | Method |
| ----------------------------- | --------------------------------------- | ------ |
| Get current billing statement | `/v2/billing-statements/current` | GET |
| Get billing statement by date | `/v2/billing-statements/{month}/{year}` | GET |
## Get current billing statement
Retrieve the billing statement that is currently open for the ongoing cycle.
### Endpoint
`GET /v2/billing-statements/current`
### cURL Request
```curl cURL theme={null}
curl -X GET \
"https://public-api.mx.clara.com/api/v2/billing-statements/current" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```
### Sample JSON Response
```json JSON theme={null}
{
"month": 7,
"year": 2025,
"status": "OPEN",
"statementUuid": "b6a81f58-4ebc-4e93-822d-2b0917ae845c",
"totalAmount": 150000.50,
"currency": "MXN",
"closingDate": "2025-07-31"
}
```
## Get current billing statement
Retrieve a billing statement for a specific month and year (e.g. June 2024).
### Endpoint
`GET /v2/billing-statements/{month}/{year}`
### cURL Request
```curl cURL theme={null}
curl -X GET \
"https://public-api.mx.clara.com/api/v2/billing-statements/6/2024" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```
### Sample JSON Response
```json JSON theme={null}
{
"month": 6,
"year": 2024,
"status": "CLOSED",
"statementUuid": "e1f349d4-cf35-4b78-bdbf-1d35f0a8e014",
"totalAmount": 132500.00,
"currency": "MXN",
"closingDate": "2024-06-30"
}
```
\*\*π‘ Tip: \*\*Use the status field to distinguish between open and closed billing cycles.
**β οΈ Note:** The current billing statement is subject to change until the cycle closes.
***
## Endpoint Reference
### `GET /api/v2/billing-statements`
List billing statements (v2)
**Response Schema (`BillingStatementPageV3`):**
| Field | Type | Example |
| --------------- | --------------------------------- | ------- |
| `content` | array of BillingStatementResponse | |
| `totalElements` | integer | |
| `totalPages` | integer | |
| `size` | integer | |
| `number` | integer | |
# Boleto Payments
Source: https://developers.clara.team/api-reference/boleto-payments
Create and retrieve boleto bill payments (Brazil only).
This service is not yet available in v3. Available in **v2** only.
## What is the Boleto Payments?
The **Boleto Payments API (v2)** allows you to programmatically manage and execute boleto bancΓ‘rio payments (bank slips) in Brazil, including both:
* **Manual boletos** (initiated via barcode)
* **DDA (DΓ©bito Direto Autorizado)** pre-authorized invoices retrieved automatically from financial institutions
You can use this API to:
* Fetch and display pending DDA bills
* Initiate boleto payments (DDA or manual)
* Retrieve a complete payment history
## Available Endpoints
| Operation | Endpoint | Method |
| ----------------------- | ------------------------- | ------ |
| Get all DDA invoices | `/v2/payments/dda` | GET |
| Get DDA invoice by UUID | `/v2/payments/dda/{uuid}` | GET |
| Create boleto payment | `/v2/payments` | POST |
| Get all boleto payments | `/v2/payments` | GET |
## Get all DDA invoices
Use this endpoint to **retrieve all DDA invoices** (pending or unpaid) available to your company. These invoices are issued by suppliers or creditors and automatically associated with your account by the banking network.
### Endpoint
`GET /v2/payments/dda`
### cURL Request
```curl cURL theme={null}
curl -X GET \
"https://public-api.mx.clara.com/api/v2/payments/dda" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```
### Sample JSON Response
```json JSON theme={null}
[
{
"uuid": "dda-uuid-001",
"issuer": "Empresa XYZ",
"amount": 350.75,
"dueDate": "2025-07-20",
"status": "PENDING"
}
]
```
## Get DDA Invoice by UUID
Use this endpoint to retrieve detailed information for a specific DDA invoice using its uuid.
### Endpoint
`GET /v2/payments/dda/{uuid}`
### cURL Request
```curl cURL theme={null}
curl -X GET \
"https://public-api.mx.clara.com/api/v2/payments/dda/dda-uuid-001" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```
### Sample JSON Response
```json JSON theme={null}
{
"uuid": "dda-uuid-001",
"issuer": "Empresa XYZ",
"amount": 350.75,
"dueDate": "2025-07-20",
"status": "PENDING",
"barcodeDigitableLine": "23791887700000350758091001100123456789000000000"
}
```
## Create a Boleto Payment
Use this endpoint to initiate a boleto payment using a valid barcodeDigitableLine. This works for both DDA and manually obtained boletos.
You can optionally attach metadata to link this payment to specific internal processes.
### Endpoint
`POST /v2/payments`
### cURL Request
```curl cURL theme={null}
curl -X POST \
"https://public-api.mx.clara.com/api/v2/payments" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"barcodeDigitableLine": "23791887700000350758091001100123456789000000000"
}'
```
### Sample JSON Response
```json JSON theme={null}
{
"uuid": "payment-uuid-001",
"status": "PROCESSING",
"amount": 350.75,
"dueDate": "2025-07-20",
"executedAt": "2025-07-18T12:00:00Z"
}
```
## Get All Boleto Payments
Use this endpoint to retrieve the list of all boleto payments initiated from your account, including both DDA and manual payments.
You can apply filters such as status, startDate, or endDate.
### Endpoint
`GET /v2/payments`
### cURL Request
```curl cURL theme={null}
curl -X GET \
"https://public-api.mx.clara.com/api/v2/payments?status=SUCCESS&startDate=2025-07-01" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```
### Sample JSON Response
```json JSON theme={null}
[
{
"uuid": "payment-uuid-001",
"barcodeDigitableLine": "23791887700000350758091001100123456789000000000",
"amount": 350.75,
"status": "SUCCESS",
"executedAt": "2025-07-18T12:00:00Z"
},
{
"uuid": "payment-uuid-002",
"barcodeDigitableLine": "00193373700000001000500940144816060652304638300",
"amount": 100.00,
"status": "FAILED",
"executedAt": "2025-07-15T10:30:00Z"
}
]
```
\*\*π‘ Tip: \*\*Use the DDA endpoints to show users their pre-approved invoices. You can pay them by simply passing the barcodeDigitableLine to the /v2/payments endpoint.
\*\*β οΈ Note: \*\*All payments must comply with due dates and available balance. Payment execution is not guaranteed if validation fails or if the boleto is expired.
***
## Endpoint Reference
### `GET /api/v2/payments`
List payments (v2)
### `POST /api/v2/payments`
Create payment (v2)
**Request Body (`PaymentRequest`):**
| Field | Type | Example |
| --------- | ---------------------- | ------- |
| `boletos` | array of BoletoRequest | |
### `GET /api/v2/payments/dda`
List DDA payments (v2)
### `GET /api/v2/payments/{barcode_digitableline}`
Get payment by barcode or digitable line (v2). Returns merged payment data from all matching payment attempts. Path parameter must be numeric only.
**Parameters:**
| Parameter | In | Type | Required | Description |
| ----------------------- | ---- | ------ | -------- | -------------------------------------------------------------------- |
| `barcode_digitableline` | path | string | β
| Numeric barcode or digitable line (digits only, pattern: `^[0-9]+$`) |
**Response Schema (`PaymentMergedV2`):**
| Field | Type | Description | Example |
| --------------------------- | ------------------------- | ------------------------------------- | ---------------------------------------------------------- |
| `barcode` | string | Boleto barcode | `"23793381286000000003281000108399191460000010000"` |
| `digitableLine` | string | 47/48-digit digitable line | `"23793.38128 60000.000038 28100.010839 9 19146000001000"` |
| `amount` | number (decimal) | Payment amount | `100.0` |
| `beneficiaryDocumentNumber` | string | Beneficiary CPF/CNPJ | `"45690845000194"` |
| `beneficiaryName` | string | Beneficiary name | `"EMPRESA EXEMPLO LTDA"` |
| `paid` | boolean | Whether any attempt has status `PAID` | `true` |
| `externalId` | string | External reference ID | |
| `transactionId` | string | Associated transaction ID | |
| `paymentDatetime` | string (date-time) | Payment execution datetime | |
| `attempts` | array of `PaymentAttempt` | History of payment attempts | |
**`PaymentAttempt` fields:**
| Field | Type | Description |
| -------------- | ------------------ | ----------------------------------- |
| `externalId` | string | External identifier for the attempt |
| `status` | string | Attempt status (e.g., `PAID`) |
| `errorMessage` | string \| null | Error message if attempt failed |
| `timestamp` | string (date-time) | When the attempt was made |
# Card Configurations
Source: https://developers.clara.team/api-reference/card-configurations
Create and manage card configuration templates.
This service is not yet available in v3. Available in **v2** only.
Clara's Cards Configuration API allows you to:
* Usage periods (with the option to automatically delete the card after the defined period)
* ATM withdrawals (only for physical cards)
* Days of the week
* Vendor categories
These configurations can be combined and used simultaneously.
## Usage Periods
This configuration is intended for card usage on scheduled dates, with the option to automatically delete the card after the defined period. The start and end date indicate the window this card will be active, and the start and end time indicate what time of the day it will be possible to use it.
* `startDate`: Specifies the starting date to enable the card for usage, in the format YYYY-MM-DD.
* `endDate`: Specifies the ending date to enable the card for usage, in the format YYYY-MM-DD.
* `startTime`: Specifies the starting time to use the card date to enable the card for usage, in the format HH:MM
* `endTime`: Specifies the ending time to use the card date to enable the card for usage, in the format HH:MM
* `enableAutoDeletion`: A boolean flag that indicates if the card will be automatically deleted after the period expiry.
\*\*Note: \*\*if the enableAutoDeletion is set, the card will be deleted even with other configurations.
In this example, the card will be active from December 1st, 2024, to December 31st, 2024, from 8 a.m. to 8 p.m. After the end date, it will be automatically deleted.
```json theme={null}
{
"period": {
"startDate": "2024-12-01",
"endDate": "2024-12-31",
"startTime": "08:00",
"endTime": "20:00",
"enableAutoDeletion": true
}
}
```
## ATM Withdrawals
This configuration applies only to physical cards and allows the cardholder to withdraw the specified amount from an ATM.
* atmCashLimit: Specifies the amount that can be withdrawn from ATM.
* Applies only to physical cards
**Note:** the currency is always the currency where the contract is signed. MXN to Mexico, BRL to Brazil, and COL to Colombia.
In this example it allows the cardholder to withdraw \$ 100 MX
```json theme={null}
{
"atmCashLimit": 100
}
```
## Days of the Week
This configuration is indicated to cards daily operations and without a scheduled date to end.
* `values`: A list of values that indicates the days of the week. Allowed values, always in uppercase.
* MONDAY
* TUESDAY
* WEDNESDAY
* THURSDAY
* FRIDAY
* SATURDAY
* SUNDAY
* `allowedDaysOfUse`: true or false (boolean)
In this case, we have a card that can be used from Monday to Friday, but it can't be used on the weekends.
```json theme={null}
{
"weekdays": {
"values": ["SATURDAY", "SUNDAY"],
"allowedDaysOfUse": false
}
}
```
## Vendor Categories
This configuration is used to restrict the category of the vendor where the card can make expenses.
* `values`: A list of values that indicates the categories. Allowed values, always in uppercase.
* RETAIL
* OFFICE
* OTHERS
* HEALTH
* ENTERTAINMENT
* SPECIALTY\_STORES
* TEIXTILE\_PRODUCTS
* SOFTWARE\_AND\_HARDWARE
* ELECTRONICS
* SUBSCRIPTIONS
* FOOD
* BARS\_OR\_ALCOHOLIC\_BEVERAGES
* GOVERNMENT\_PAYMENTS
* CHARITY\_AND\_SOCIAL
* PROFESSIONAL\_SERVICES
* REAL\_ESTATE
* TRANSPORTATION
* CAR\_RENTALS
* TRAVEL\_AND\_LODGING
* FUEL\_GOODS
* COMMUNICATION
* DIGITAL\_ADS
* DIGITAL\_COMMERCE
* CONTRACTORS\_AND\_CONSTRUCTION
* SPECIAL\_SERVICES
* EDUCATION
* JEWELRY\_CASINOS\_AND\_FINES
* `allowedMerchants`: true = allow, false = restrict (boolean)
Example:
```json theme={null}
{
"merchants": {
"values": ["TRANSPORTATION", "CAR_RENTALS", "TRAVEL_AND_LODGING"],
"allowedMerchants": true
}
}
```
## Retrieve Card Configuration
To fetch the current configuration of a specific card:
**Endpoint:** `GET /api/v2/cards/{uuid}/configurations`
| Parameter | In | Type | Required | Description |
| --------- | ---- | ------------- | -------- | ----------- |
| `uuid` | path | string (UUID) | β
| Card UUID |
Returns a `CardConfigurationResponse` object with the same structure as the create/update request body: `period`, `atmCashLimit`, `weekdays`, and `merchants`.
**Example Response:**
```json theme={null}
{
"period": {
"startDate": "2024-12-01",
"endDate": "2024-12-07",
"startTime": "08:00",
"endTime": "20:00",
"enableAutoDeletion": true
},
"atmCashLimit": 5000.0,
"weekdays": {
"values": ["SATURDAY", "SUNDAY"],
"allowedDaysOfUse": false
},
"merchants": {
"values": ["TRANSPORTATION", "CAR_RENTALS", "TRAVEL_AND_LODGING"],
"allowedMerchants": true
}
}
```
***
## Combine Configurations
**Example:** Consider a typical use case where an employee is traveling for work *from December 1st, 2024, to December 7th, 2024*. In this scenario, the card will be active during the first week of December, with *expenses allowed only on weekdays*, from *8 a.m. to 8 p.m.*, and *within specific categories* such as car rentals, hotels, buses, and taxis. After this period, the card will be *automatically deleted*.
```json theme={null}
{
"period": {
"startDate": "2024-12-01",
"endDate": "2024-12-07",
"startTime": "08:00",
"endTime": "20:00",
"enableAutoDeletion": true
},
"weekdays": {
"values": ["SATURDAY", "SUNDAY"],
"allowedDaysOfUse": false
},
"merchants": {
"values": ["TRANSPORTATION", "CAR_RENTALS", "TRAVEL_AND_LODGING"],
"allowedMerchants": true
}
}
```
# Cards
Source: https://developers.clara.team/api-reference/cards
Issue, manage, lock, and cancel corporate cards.
Recommended for all new integrations.
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 | `/api/v3/cards` | GET |
| Find card by UUID | `/api/v3/cards/{uuid}` | GET |
| Find all card requests by batch ID | `/api/v3/cards/requests/batches/{id}` | GET |
| Find all card requests by ID | `/api/v3/cards/requests/{id}` | GET |
| Find all card requests | `/api/v3/cards/requests` | GET |
| Create cards | `/api/v3/cards/bulk-create` | POST |
| Single create card | `/api/v3/cards` | POST |
| Update single card threshold | `/api/v3/cards/{uuid}/threshold` | PATCH |
| Update multiple cards threshold | `/api/v3/cards/threshold` | PATCH |
| Lock/unlock a single card | `/api/v3/cards/{uuid}/lock` | PATCH |
| Lock/unlock multiple cards | `/api/v3/cards/lock` | PATCH |
| Delete card | `/api/v3/cards/{uuid}` | DELETE |
| Delete cards | `/api/v3/cards/delete` | POST |
## Find All Cards
List **all cards** in your account.
### Endpoint
`GET /api/v3/cards`
### cURL Request
```curl cURL theme={null}
curl -X GET "https://public-api.mx.clara.com/api/v3/cards/" \
--cert /path/to/client-cert.pem \
--key /path/to/client-key.pem \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```
### Sample JSON Response
```json JSON theme={null}
{
"content": [
{
"uuid": "dd9bf99c-648b-419d-8316-32201ef91289",
"claraStatus": "ACTIVE",
"status": "ACTIVE",
"lockCode": "UNLOCKED",
"alias": "Marketing Card",
"threshold": 1000.0,
"periodicity": "MONTHLY",
"maskedPan": "510979******9579",
"type": "MASTER_VIRTUAL",
"user": {
"uuid": "c3fb1f07-5e7f-47b8-9819-0b09151b8099",
"fullName": "Ana GarcΓa",
"username": "ana.garcia@company.com"
}
}
],
"totalElements": 379,
"totalPages": 190,
"size": 2,
"number": 0
}
```
### 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).
## Find Card by UUID
Fetch a **single card** by its UUID.
### Endpoint
`GET /api/v3/cards/{uuid}`
### cURL Request
```curl cURL theme={null}
curl -X GET "https://public-api.mx.clara.com/api/v3/cards/5d1e2f83-1c90-4c34-9400-bfef9ac85c6e" \
--cert /path/to/client-cert.pem \
--key /path/to/client-key.pem \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```
### Sample JSON Response
```json JSON theme={null}
{
"uuid": "dd9bf99c-648b-419d-8316-32201ef91289",
"claraStatus": "ACTIVE",
"status": "ACTIVE",
"lockCode": "UNLOCKED",
"alias": "Marketing Card",
"threshold": 1000.0,
"periodicity": "MONTHLY",
"maskedPan": "510979******9579",
"type": "MASTER_VIRTUAL",
"cvv": "705",
"expiryDate": "12/30",
"numberOnCard": "5109790205009579",
"user": {
"uuid": "c3fb1f07-5e7f-47b8-9819-0b09151b8099",
"fullName": "Ana GarcΓa",
"username": "ana.garcia@company.com"
}
}
```
## Create Cards (Bulk)
Create multiple cards asynchronously.
### Endpoint
`POST /api/v3/cards/bulk-create`
### cURL Request
```curl cURL theme={null}
curl -X POST "https://public-api.mx.clara.com/api/v3/cards/bulk-create" \
--cert /path/to/client-cert.pem \
--key /path/to/client-key.pem \
-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.
## Create Single Card
Create one card directly.
### Endpoint
`POST /api/v3/cards`
### cURL Request
```curl cURL theme={null}
curl -X POST "https://public-api.mx.clara.com/api/v3/cards" \
--cert /path/to/client-cert.pem \
--key /path/to/client-key.pem \
-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` |
## Update Card Threshold
Adjust the spending limit for a card.
### Endpoint
`PATCH /api/v3/cards/{uuid}/threshold`
### cURL Request
```curl cURL theme={null}
curl -X PATCH "https://public-api.mx.clara.com/api/v3/cards/abc-123/threshold" \
--cert /path/to/client-cert.pem \
--key /path/to/client-key.pem \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"threshold": 800}'
```
## Toggle Card Lock
Lock or unlock a card.
### Endpoint
`PATCH /api/v3/cards/{uuid}/lock`
### cURL Request
```curl cURL theme={null}
curl -X PATCH "https://public-api.mx.clara.com/api/v3/cards/abc-123/lock" \
--cert /path/to/client-cert.pem \
--key /path/to/client-key.pem \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"locked": true, "lockCode": 16}'
```
### Request Body
| Field | Type | Required | Description |
| ---------- | ------- | -------- | ------------------------------------ |
| `locked` | boolean | β
| `true` to lock, `false` to unlock |
| `lockCode` | integer | β
| Must be `16` for API-initiated locks |
### Response (202 Accepted β async)
```json theme={null}
{
"batchId": "836ce8d6-e767-4a3f-827c-14919413638c",
"id": "8034e101-adc9-4a65-8cfc-ddd98c4377e0",
"uuid": "dd9bf99c-648b-419d-8316-32201ef91289",
"status": "UPDATED"
}
```
### lockCode values
The `lockCode` field identifies who is initiating the lock. Use `16` for API-initiated locks.
| `lockCode` | Initiated by | Description |
| ---------- | ----------------- | -------------------------------------------------------------------------------- |
| `16` | API / integration | Standard user-initiated lock. Use this for programmatic lock/unlock via the API. |
Locks can also be applied by manager hierarchy (Master Lock) or by Clara's internal team (Clara Blocked). These originate from different sources and cannot be set via the API β they are reflected in the `lockCode` field when you read the card back with `GET /api/v3/cards/{uuid}`.
## Delete a Card
Cancel (soft-delete) a single card.
### Endpoint
`DELETE /api/v3/cards/{uuid}`
### cURL Request
```curl cURL theme={null}
curl -X DELETE "https://public-api.mx.clara.com/api/v3/cards/abc-123" \
--cert /path/to/client-cert.pem \
--key /path/to/client-key.pem \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```
## Delete Multiple Cards
Cancel multiple cards in one request.
### Endpoint
`POST /api/v3/cards/delete`
### cURL Request
```curl cURL theme={null}
curl -X POST "https://public-api.mx.clara.com/api/v3/cards/delete" \
--cert /path/to/client-cert.pem \
--key /path/to/client-key.pem \
-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.
***
## Endpoint Reference
### `GET /api/v3/cards`
List all cards (v3)
**Parameters:**
| Parameter | In | Type | Required | Description |
| ------------- | ----- | ------------- | -------- | ---------------------------------------------------- |
| `userUuid` | query | string (uuid) | | Filter by user UUID |
| `username` | query | string | | Filter by username |
| `status` | query | string | | Filter by card status |
| `periodicity` | query | string | | Filter by periodicity |
| `type` | query | string | | Filter by card type |
| `userErpId` | query | string | | Filter by user ERP ID (only if userUuid not present) |
| `claraStatus` | query | string | | \[DEPRECATED] Use 'status' instead |
**Response Schema (`CardPageV3`):**
| Field | Type | Example |
| --------------- | --------------- | ------- |
| `content` | array of CardV3 | |
| `totalElements` | integer | |
| `totalPages` | integer | |
| `size` | integer | |
| `number` | integer | |
### `POST /api/v3/cards`
Create card (v3)
**Request Body (`CreateCardRequestV3`):**
| Field | Type | Example |
| -------------- | ---------------- | -------------------------------------- |
| `type` | string (enum) | `VIRTUAL`/`PHYSICAL` |
| `alias` | string | `Card Name` |
| `userUuid` | string (uuid) | `a0c82a20-ac09-4cfd-b429-d0623585911e` |
| `threshold` | number (decimal) | `1000` |
| `businessType` | string (enum) | `BUSINESS`/`WORLD_ELITE` |
| `periodicity` | string (enum) | `MONTHLY`/`DAILY` |
### `GET /api/v3/cards/{uuid}`
Get card by UUID (v3)
**Parameters:**
| Parameter | In | Type | Required | Description |
| --------- | ---- | ------------- | -------- | ----------- |
| `uuid` | path | string (uuid) | β
| |
**Response Schema (`CardV3`):**
| Field | Type | Example |
| -------------- | ---------------- | ---------------------------------------------------------- |
| `uuid` | string (uuid) | `a0c82a20-ac09-4cfd-b429-d0623585911e` |
| `claraStatus` | string | `ACTIVE` |
| `status` | string | `ACTIVE`, `LOCKED`, `MASTER_LOCKED`, `CANCELLED` |
| `lockCode` | string | `UNLOCKED`, `TEMPORAL_LOCKED` |
| `alias` | string | `Card Name` |
| `threshold` | number (decimal) | `1000` |
| `periodicity` | string | `MONTHLY`, `DAILY` |
| `maskedPan` | string | `514509******5946` |
| `type` | string | `MASTER_VIRTUAL`, `MASTER_CORPORATE`, `MASTER_WORLD_ELITE` |
| `user` | object | `{uuid, fullName, username, links}` |
| `cvv` | string | `705` β only present on `GET /{uuid}` |
| `expiryDate` | string | `12/30` β only present on `GET /{uuid}` |
| `numberOnCard` | string | `5109790205009579` β only present on `GET /{uuid}` |
| `links` | array of Link | |
### `DELETE /api/v3/cards/{uuid}`
Delete card (v3)
**Parameters:**
| Parameter | In | Type | Required | Description |
| --------- | ---- | ------------- | -------- | ----------- |
| `uuid` | path | string (uuid) | β
| |
### `PATCH /api/v3/cards/{uuid}/lock`
Toggle card lock (v3)
**Parameters:**
| Parameter | In | Type | Required | Description |
| --------- | ---- | ------------- | -------- | ----------- |
| `uuid` | path | string (uuid) | β
| |
**Request Body (`ToggleCardLockRequest`):**
| Field | Type | Required | Example |
| ---------- | ------- | -------- | --------------------------------- |
| `locked` | boolean | β
| `true` to lock, `false` to unlock |
| `lockCode` | integer | β
| `16` |
**Response (`202 Accepted`):** `{batchId, id, uuid, status: "UPDATED"}`
### `PATCH /api/v3/cards/{uuid}/threshold`
Update card threshold (v3)
**Parameters:**
| Parameter | In | Type | Required | Description |
| --------- | ---- | ------------- | -------- | ----------- |
| `uuid` | path | string (uuid) | β
| |
**Request Body (`UpdateCardThresholdRequest`):**
| Field | Type | Example |
| ----------- | ---------------- | ------- |
| `threshold` | number (decimal) | `5000` |
### `POST /api/v3/cards/bulk-create`
Bulk create cards (v3)
**Request Body (`BulkCreateCardRequest`):**
| Field | Type | Example |
| ------- | ---------------------------- | ------- |
| `cards` | array of CreateCardRequestV3 | |
### `POST /api/v3/cards/delete`
Bulk delete cards (v3)
**Request Body (`BulkDeleteCardsRequest`):**
| Field | Type | Example |
| ------- | --------------- | ------- |
| `uuids` | array of string | |
### `PATCH /api/v3/cards/lock`
Bulk toggle card lock (v3). Returns `202 Accepted` β async, result delivered via webhook.
**Request Body:**
| Field | Type | Required | Description |
| ------------------- | ----- | -------- | -------------------------------------------------- |
| `cardsLockRequests` | array | β
| Each item: `{uuid, locked: boolean, lockCode: 16}` |
**Example:**
```json theme={null}
{
"cardsLockRequests": [
{ "uuid": "dd9bf99c-648b-419d-8316-32201ef91289", "locked": true, "lockCode": 16 }
]
}
```
**Response (`202`):**
```json theme={null}
{
"id": "9e9fe2c0-a194-4b81-9025-df45753b0f79",
"message": "Your request has been received but still in progress, you will get the response via webhook",
"cardsLockResponses": [
{ "batchId": "9e9fe2c0-...", "id": "0dae8e5c-...", "uuid": "dd9bf99c-...", "status": "SENT" }
]
}
```
### `PATCH /api/v3/cards/threshold`
Bulk update card thresholds (v3). Returns `202 Accepted` β async, result delivered via webhook.
**Request Body:**
| Field | Type | Required | Description |
| ------------------------------ | ----- | -------- | -------------------------------------- |
| `updateCardsThresholdRequests` | array | β
| Each item: `{uuid, threshold: number}` |
**Example:**
```json theme={null}
{
"updateCardsThresholdRequests": [
{ "uuid": "dd9bf99c-648b-419d-8316-32201ef91289", "threshold": 1500.00 }
]
}
```
**Response (`202`):**
```json theme={null}
{
"id": "85e01930-3d69-4aed-85b6-0080d6792c44",
"message": "Your request has been received but still in progress, you will get the response via webhook",
"updateCardsThresholdResponses": [
{ "batchId": "85e01930-...", "id": "88d35238-...", "uuid": "dd9bf99c-...", "status": "SENT" }
]
}
```
## Creating Cards
**Requirements:**
* New user creation. To enable the Clara API, you must create a user with the Company Owner role. This user is essential for creating resources in Clara. Separating this user helps distinguish actions from automated processes and those from other users on the platform, enhancing clarity and accountability.
* mTLS. Our API employs a secure authentication process that requires you to configure the client making the calls with the certificates provided when the API is enabled. This ensures a high level of security and a 2FA for your communications.
**Required Fields:**
* `type`: 1 = physical, 2 = virtual
* `alias`: A nickname or identifier for the card
* `userUUID`: The unique identifier for the user in Clara (Find from user's endpoint)
* `threshold`: Max limit - with Minimum amount of R$50 (BR), $500 (MX), \$100,000 (CO)
* `periodicityType`: 1 = monthly, 2 = daily
**Examples:**
***Create: Virtual Card (MX)***
```json theme={null}
{
"type": 2,
"alias": "Example",
"userUUID": "42c7cc6b-06f7-46b8-b4f5-e876fbf57335",
"threshold": 500,
"periodicityType": 2
}
```
In this example:
* The type 2 indicates a virtual card.
* The alias helps identify the card.
* The threshold is 500 (MXN), allowing daily spending.
* The periodicity type 2 means the limit resets daily.
***Create: Physical Card (MX)**:*
```json theme={null}
{
"type": 1,
"alias": "Example",
"userUUID": "42c7cc6b-06f7-46b8-b4f5-e876fbf57335",
"threshold": 500,
"periodicityType": 1
}
```
In this example:
* The type 1 indicates a physical card.
* The alias helps identify the card.
* The threshold is 500 (MXN), allowing monthly spending.
* The periodicity type 1 means the limit resets monthly.
## Limitations
* Threshold must be β€ company credit line
* User must be active (email verified, 2FA)
* Only one card creation per user at a time (prevent fraud) - If you need multiple cards for one user, wait until the current card creation is complete before making another request.
* Monitor card count to avoid max limit - Clara has a maximum limit on valid cards for each company (active or locked)
## Card Operations
* \*\*Update limit (threshold): \*\*Card must be active, additionally, the new limit for this card must not exceed the company's total limit.
* \*\*Lock card: \*\*Must be active (card locked - modifications not applied, with exception for card cancelling)
* \*\*Unlock card: \*\*Must be locked
* \*\*Cancel card: \*\*To free up space to create new cards (you can cancel cards that are active or locked) - After cancellation, the card can't be used or recovered.
## Card Life Cycle
Creation β Activation (physical) β Active β Locking β Canceling β Closure
* **Creation:** The card is generated and assigned to a user. At this stage, details such as card type, limits, and user information are defined.
* \*\*Activation: \*\*The card is activated for use. This may involve confirming the user's identity and setting up necessary security measures. This process is only for physical cards, virtual cards are created and active by default.
* \*\*Active: \*\*The card is actively used for transactions. Users can spend up to the defined limits. In this stage, changes can be made to the card, such as adjusting spending limits, updating user information, and configuring the spending rules.
* **Locking:** If necessary, the card can be locked to prevent further transactions. This is often done in cases of suspected fraud, lost cards, or by direct action from the user.
* \*\*Canceling: \*\*By canceling the card, it becomes deactivated and no longer valid for transactions. This may occur when a user no longer needs the card or when it reaches its expiration date.
* \*\*Closure: \*\*The card is officially closed and removed from the system. This typically follows deactivation and is the final step in the card's life cycle.
**Notes:** Cards that are not canceled or closed are considered valid and count toward the maximum number of valid cards; once a card is canceled, it can't be recovered.
## Virtual Card
\*\*Note: \*\*Virtual cards are created as "active" by default, no activation is needed.
## Physical Card
**Note:** The statuses "locked," "master locked," and "Clara blocked" indicate the same state for the card but originate from different sources:
### Lock States Explained
* **Locked** = by user
* **Master Locked** = by manager or user's hierarchy
* **Clara Blocked** = by our internal team
### Status Change Events
* Lock (Locked, Master Locked, Clara Blocked), unlock, or cancel by client, manager, or Clara
## Common Errors
* **`B013 Threshold exceeds company limit`**: This error occurs when the threshold (limit) set for a card exceeds the allowable amount, or the card limit exceeds the company's overall limit.
* **`B022 User is not activated`**: This error may occur if the user has been deleted or is not active on the Clara platform, like a new user.
* **`B033 Core service failure`**: This error indicates an internal failure and further investigation is needed to identify the problem.
* **`This user already has a card in the creation queue. Try again in 2 minutes`**: This error occurs because cards for the same user cannot be created concurrently. To solve this issue, you need to wait for the current card creation process to finish or allow the timeout for creation to occur in our system.
***
## Endpoint Reference
### `GET /api/v2/cards`
List all cards (v2)
**Parameters:**
| Parameter | In | Type | Required | Description |
| ------------- | ----- | ------------- | -------- | ---------------------------------------------------- |
| `userUuid` | query | string (uuid) | | Filter by user UUID |
| `username` | query | string | | Filter by username |
| `status` | query | string | | Filter by card status |
| `periodicity` | query | string | | Filter by periodicity |
| `type` | query | string | | Filter by card type |
| `userErpId` | query | string | | Filter by user ERP ID (only if userUuid not present) |
**Response Schema (`CardPageV3`):**
| Field | Type | Example |
| --------------- | --------------- | ------- |
| `content` | array of CardV3 | |
| `totalElements` | integer | |
| `totalPages` | integer | |
| `size` | integer | |
| `number` | integer | |
### `GET /api/v2/cards/{uuid}`
Get card by UUID (v2)
**Parameters:**
| Parameter | In | Type | Required | Description |
| --------- | ---- | ------------- | -------- | ----------- |
| `uuid` | path | string (uuid) | β
| |
**Response Schema (`CardV2`):**
| Field | Type | Example |
| ------------- | ---------------- | ------------------------------------------------------------------------------ |
| `uuid` | string (uuid) | `1b23c45c-c678-90f1-abef-efc12fc3d4aa` |
| `status` | string | `ACTIVE`, `LOCKED`, `PENDING_TO_COLLECT_DUE_TO_SERVICE_CANCELLATION` |
| `claraStatus` | string | `ACTIVE`, `DELETED` |
| `lockCode` | string | `UNLOCKED`, `TEMPORAL_LOCKED` |
| `alias` | string | `Marketing Card` |
| `threshold` | number (decimal) | `100.0` |
| `periodicity` | string | `MONTHLY`, `DAILY` |
| `brand` | string | `MASTER` |
| `maskedPan` | string | `514501******3540` |
| `type` | string | `MASTER_VIRTUAL`, `MASTER_CORPORATE`, `MASTER_WORLD_ELITE` |
| `user` | object | `{uuid, userFullName, username, role, taxIdentifier, erpId, status, location}` |
### `GET /api/v2/cards/{cardUuid}/configurations`
Get card configurations (v2)
**Parameters:**
| Parameter | In | Type | Required | Description |
| ---------- | ---- | ------------- | -------- | ----------- |
| `cardUuid` | path | string (uuid) | β
| |
### `PUT /api/v2/cards/{cardUuid}/configurations`
Update card configurations (v2)
**Parameters:**
| Parameter | In | Type | Required | Description |
| ---------- | ---- | ------------- | -------- | ----------- |
| `cardUuid` | path | string (uuid) | β
| |
**Request Body (`CardConfigurationRequest`):**
| Field | Type | Example |
| -------------- | ---------------------------- | ------- |
| `period` | object (CardConfigPeriod) | |
| `atmCashLimit` | number (decimal) | `5000` |
| `weekdays` | object (CardConfigWeekdays) | |
| `merchants` | object (CardConfigMerchants) | |
v1 is legacy and read-only. Migrate to v3 for full card management.
## What is the Transactions API?
The **Cards API v1** allows you to retrieve information about the physical and virtual cards issued to users in your Clara account. This includes the card's metadata such as type, status, last four digits, and issuing user.
This version of the API is **read-only**, and is commonly used to:
* Display or validate card metadata in internal tools
* Reconcile cards with transactions or user profiles
* Generate reports or dashboards based on card status or type
π Note: For card creation, updates, and controls, use [Cards API v2](#).
## Available Endpoints
| Operation | Endpoint | Method |
| ----------------- | ------------------ | ------ |
| Find all cards | `/v1/cards` | GET |
| Find card by UUID | `/v1/cards/{uuid}` | GET |
## Find all cards
Use this endpoint to **list all cards** associated with your account. The response includes card type, status, last digits, and user references.
### Endpoint
`GET /v1/cards`
### cURL Request
```curl cURL theme={null}
curl -X GET \
"https://public-api.mx.clara.com/api/v1/cards" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```
### Sample JSON Response
```json JSON theme={null}
{
"content": [
{
"uuid": "bedeeadc-1138-4123-a2f9-84bd81c434a7",
"status": "ACTIVE",
"alias": "Marketing Card",
"threshold": 1000.0,
"periodicity": "MONTHLY",
"cardNumber": "510979******4423",
"type": "MASTER_CORPORATE",
"userUuid": "75d45b4f-91db-4ca2-a204-c9ac2d04b031"
}
],
"totalElements": 528,
"totalPages": 264,
"size": 2,
"number": 0
}
```
## Find cards by UUID
Use this endpoint to retrieve detailed information for a specific card using its unique identifier.
### Endpoint
`GET /v1/cards/{uuid}`
### cURL Request
```curl cURL theme={null}
curl -X GET \
"https://public-api.mx.clara.com/api/v1/cards/card-001" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```
### Sample JSON Response
```json JSON theme={null}
{
"uuid": "bedeeadc-1138-4123-a2f9-84bd81c434a7",
"status": "ACTIVE",
"alias": "Marketing Card",
"threshold": 1000.0,
"periodicity": "MONTHLY",
"cardNumber": "510979******4423",
"type": "MASTER_CORPORATE",
"userUuid": "75d45b4f-91db-4ca2-a204-c9ac2d04b031"
}
```
**π‘ Tip:** Use the userUuid to cross-reference card ownership and track usage per employee.
\*\*β οΈ Note: \*\*This API version does not support locking, unlocking, issuing, or updating cards β only retrieval.
***
## Endpoint Reference
### `GET /api/v1/cards`
Find all cards
**Parameters:**
| Parameter | In | Type | Required | Description |
| ----------------- | ----- | --------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------- |
| `page` | query | integer | | Zero-based page index (0..N) |
| `size` | query | integer | | The size of the page to be returned |
| `userUuid` | query | string | | UUID of the user for which to retrieve cards |
| `status` | query | string | | Filter by card status (e.g., `ACTIVE`, `LOCKED`, `CANCELLED`) |
| `periodicityType` | query | enum: `DAILY`/`MONTHLY` | | Periodicity of the cards |
| `type` | query | enum: `MASTER_WORLD_ELITE`/`MASTER_CORPORATE`/`MASTER_VIRTUAL`/`VISA_PHYSICAL`/`VISA_VIRTUAL` | | Type of the cards |
### `GET /api/v1/cards/{uuid}`
Find cards by UUID
**Parameters:**
| Parameter | In | Type | Required | Description |
| --------- | ---- | ------ | -------- | ----------- |
| `uuid` | path | string | β
| Card UUID |
# DDA - Authorized Direct Debit
Source: https://developers.clara.team/api-reference/dda
Manage authorized direct debit (DDA) payments (Brazil only).
This service is not yet available in v3. Available in **v2** only.
## Getting Started with DDA
\*\*DDA (Direct Debit Authorization) \*\*is a secure, paperless solution for boleto payment management. It digitizes the entire billing flow, bringing agility, control, and cost savings to businesses.
By using DDA, payments are automatically registered in the banking environment - eliminating the need for manual entry and reducing fraud risk.
## Key Benefits
* Paperless and automated boleto handling
* Centralized control of your payments
* Reduced operational overhead
* Real-time registration with banks
## How to Enable It
To begin using DDA:
1. Enable the feature on Clara's platform
2. Newly registered payments will be visible via the Clara API
**Note:** This feature is currently available only in Brazil.
# Digital Account
Source: https://developers.clara.team/api-reference/digital-account
Access digital account transactions including PIX, TED, and bill payments (Brazil only).
This service is available in **v3** only.
## How to get Transactions from digital account via Clara API
This guide explains how to use the `GET /api/v3/digital-accounts` endpoint to retrieve transactions in the Clara API system.
***
## Authentication Requirements
To access this endpoint, ensure the following:
* Use **mutual TLS (MTLS)** for secure two-way certificate validation.
* Obtain an **OAuth2 access token** via the `/oauth/token` endpoint.
* Include the **Bearer token** in the `Authorization` header of your request.
***
## Endpoint
```
GET /v3/digital-accounts
```
***
## Query Parameters (Optional)
This section lists the optional filters available for the Digital Account endpoint. All parameters can be **combined** and are intended to narrow results by **date range** and **transaction types**:
* Dates are supplied in local **`yyyy-MM-dd`** format; the SDK **normalizes them to end-of-day UTC** before building the URL.
* Validation (format, list size, and date ordering) happens **client-side** before the request is sent.
*
| Parameter | Type | Format / Allowed values | Description | Example |
| --------------------- | ------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
| `startDate` | string | `yyyy-MM-dd` | Start of the date range (local). The SDK normalizes it to **endβofβday UTC** before sending the request. | `startDate=2025-08-01` |
| `endDate` | string | `yyyy-MM-dd` | End of the date range (local). The SDK normalizes it to **endβofβday UTC**; must be **β₯ `startDate`**. | `endDate=2025-08-10` |
| `transactionTypeName` | string (enum) | `PIX` \| `TED` \| `BILL` \| `TRANSACTION` | Human-friendly alias. The SDK maps it to one or more `transactionTypes` codes; if mapping yields no codes, nothing is added. | `transactionTypeName=PIX` |
### Clientβside validation rules
These rules are applied by `DigitalAccountTransactionFilter` before the request is built:
* `startDate`, `endDate`: `@Pattern("\d{4}-\d{2}-\d{2}")` β error: *Date must be in ISO format (yyyy-MM-dd).*
* `transactionTypeName`: `@Pattern("PIX|TED|BILL|TRANSACTION")` β error: *transactionTypeName must be one of: PIX, TED, BILL, TRANSACTION.*
* Date range: `@AssertTrue` ensures `startDate <= endDate` when both dates are present and parsable β error: *startDate must be less than or equal to endDate.*
> **Note:** Endβofβday UTC normalization happens **after** the ISO date format check.
***
## Examples
### 1. Filter by date range
**Request (query):**
```
GET /v3/digital-accounts?startDate=2025-08-01&endDate=2025-08-10
```
### 2. Filter by type alias (`transactionTypeName`)
**Request (query):**
```
GET /v3/digital-accounts?transactionTypeName=PIX
```
### 3. Combined
**Request (query):**
```
GET /v3/digital-accounts?startDate=2025-08-03&endDate=2025-08-10&transactionTypeName=PIX
```
## Validation messages (client)
* `Date must be in ISO format (yyyy-MM-dd)`
* `transactionTypeName must be one of: PIX, TED, BILL, TRANSACTION`
* `startDate must be less than or equal to endDate`
> The backend may return additional validation errors.
> β οΈ **Important Notes:**
>
> * Response is a JSON array (no envelope with totalElements).
> * Keep paging until an empty page or a page with \< size items is returned.
## Successful Response
| Status | Meaning |
| ------ | ---------------------------------- |
| 200 | OK - List of transactions returned |
***
## Error Responses
| Status | Meaning |
| ------ | ------------ |
| 400 | Bad Request |
| 401 | Unauthorized |
| 403 | Forbidden |
***
## Example cURL Request
```bash theme={null}
curl --location --request GET 'https://public-api.br.clara.com/api/v3/digital-accounts?page=0&size=50' \
--header 'Authorization: Bearer {your_access_token}' \
--cert {client_cert_path} \
--key {client_key_path}
```
Replace `{your_access_token}`, `{client_cert_path}`, and `{client_key_path}` with actual values.
***
## Example Response Object
```json General Response theme={null}
{
"data": [
{
"id": 2317547016,
"transactionDate": "2025-09-09T00:00:00",
"amount": 0.01,
"method": "PIX",
"type": "Reversal of sent transfer",
"source": {
"name": "ABCD EJAF ",
"taxId": "123.038.XSJ",
"institution": "18236301"
},
"beneficiary": {
"name": "CLARA PARTICIPACOES LTDA",
"taxId": "42367512309812",
"institution": "14290914"
}
}
],
"meta": {
"totalPages": 39,
"totalItems": 388,
"itemsPerPage": 10,
"currentPage": 0
}
}
```
```json Bill Response theme={null}
{
"data": [
{
"id": 3925095764,
"transactionDate": "2025-07-03T00:00:00",
"amount": 9.00,
"method": "Bill",
"type": "Transfer sent",
"source": {
"name": "CLARA INSTITUIΓΓO DE PAGAMENTO LTDA",
"taxId": "41818339000586",
"institution": "BTG Pactual"
},
"beneficiary": {
"name": "CLARA INSTITUICAO DE PAGAMENTO LTDA",
"taxId": "41818339000586",
"institution": null
},
"description": "Boleto integral",
"digitableLine": null,
"charges": {
"discount": 0.0,
"fee": 0.0,
"interest": 0.0,
"totalFees": null
}
}
],
"meta": {
"totalPages": 39,
"totalItems": 388,
"itemsPerPage": 10,
"currentPage": 0
}
}
```
***
## Field reference
| Field | Type | Description | Example |
| ----------------- | --------------------------- | ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `id` | number | Unique transaction identifier. | `3671272250` |
| `transactionDate` | string (ISO-8601 date-time) | Transaction date/time. | `2025-08-25T00:00:00` |
| `amount` | number (decimal) | Currency amount in **units** (not cents). In typed languages, use `BigDecimal`. | `0.10` |
| `method` | string (enum) | Payment method. | `PIX` Β· `TED` Β· `Bill` Β· `Transfer` Β· `Undefined` |
| `type` | string | Business label describing the transaction. | `Transfer sent` Β· `Deposit in account` Β· `Reversal of sent transfer` |
| `description` | string \| null | Optional description (mostly for bills). | `"Boleto integral"` |
| `digitableLine` | string \| null | Bill (bank slip) digitable line when available. | `"23793.38127 60000.000123 45000.567890 1 23450000010000"` |
| `charges` | object \| null | Bill fee breakdown: `discount`, `fee`, `interest`, `totalFees`. | `{ "discount": 0.0, "fee": 0.0, "interest": 0.0, "totalFees": null }` |
| `source` | object \| null | Origin party: `{ name, taxId, institution }`. | `{ "name": "CLARA PARTICIPACOES LTDA", "taxId": "45690845000194", "institution": "41538335" }` |
| `beneficiary` | object \| null | Destination party: `{ name, taxId, institution }`. | `{ "name": "CLARA PAGAMENTOS LTDA", "taxId": "41538335000145", "institution": null }` |
> β οΈ Note: some fields may be `null` depending on the `method`/`type`.
***
## Endpoint Reference
### `GET /api/v3/digital-accounts`
List digital account transactions (v3, Brazil only)
# Documents
Source: https://developers.clara.team/api-reference/documents
Retrieve documents (receipts, invoices) associated with transactions.
This service is available in **v3** only.
## When a Transaction Has Attachments
If a transaction has attachments:
* The `hasAttachments` field is set to `true`
* You'll receive a\*\* link to download them\*\*
* URLs are valid for **12 hours**
Format: `.../v3/transactions/{uuid}/documents`
## Endpoint Format
`GET /v3/transactions/{uuid}/documents`
Use this endpoint to retrieve the download links for all attachments related to a specific transaction.
## Example: Getting Attachments for a Transaction
In the following example, we will get the URLs for the transaction with the UUID "47f8ed9e-4d7b-450b-ad6a-f1d83e3ce4e1" in Mexico.
### cURL Request
```curl cURL theme={null}
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
```curl JSON theme={null}
{
"transactionUuid": "47f8ed9e-4d7b-450b-ad6a-f1d83e3ce4e1",
"attachments": [
{
"uuid": "18589896-d30e-4cca-a4e6-716ba323b937",
"fileName": "receipt.jpg",
"updateAt": "2024-12-09T01:35:26.426484Z",
"format": "jpeg",
"download": {
"urlExpiration": "2024-12-14T07:40:15.144358891Z",
"url": "https://company-9fefb4f5-491d-4028-8c4d-f7b20ff98e29.s3.amazonaws.com/user_docs/1dbf684e-4cdd-467d-b240-3e8e45d63887/51/5465258?response-content-disposition=attachment%3B%20filename%3D%22oneOoneHuixquilucan_241208193512.jpg%22&response-content-type=jpeg&X-Amz-Security-Token=FwoGZXIvYXdzEDUaDJAr429nJB6KRbni%2FiKwAbLEsGgPIsSE8kV0DdR905%2FXd4wYq9zQ2P99MHz06fykkTuaylb7xbpkANXyqQpTJw2M23Q%2FabFuakuazkVDPCQ%2BHwDM3LmJ%2BqWhng87m1q6p6JlacCyMqlQbVtpwYFcts1hMjSXASha79Cs%2FLm9onR2txbq6rTn5%2BW0vtKFk%2FyD7x%2FhGhfmMuZyUgD37dp7FSzUo0Z4ZjLhHjrc6tt%2F2f2C15sN1ps9tCtoyyCiKJ2b8roGMi0W6DxWRVjX7xCGyIT07lfVCMnw9v1MsbpscZ5%2BORVmaTq9CfU3kezypy%2B0M%3D&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20241213T194014Z&X-Amz-SignedHeaders=host&X-Amz-Expires=43199&X-Amz-Credential=ASIASUFA8KD3C1GJLWK%2F20241213%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=3038ebf880b3cd0a0e8b24a0440f047e52ec1f4c1b88f210c637928747a688cc"
}
}
]
}
```
β οΈ The download URL is time-sensitive and will expire 12 hours after it's generated. Make sure to use it within that window.
***
## Endpoint Reference
### `GET /api/v3/transactions/{uuid}/documents`
Get a transaction by UUID
**Parameters:**
| Parameter | In | Type | Required | Description |
| --------- | ---- | ------ | -------- | ---------------- |
| `uuid` | path | string | β
| Transaction UUID |
**Response Schema (`AttachmentDocuments`):**
| Field | Type | Example |
| ----------------- | ------------------------------- | -------------------------------------- |
| `transactionUuid` | string | `5ea3a09a-5c1c-9303-b833-c93780c21dbc` |
| `attachments` | array of AttachmentTransactions | |
### `GET /api/v3/transactions/{uuid}/extracted-documents`
Find extracted documents for a Transaction by uuid
**Parameters:**
| Parameter | In | Type | Required | Description |
| ------------------ | ----- | ------------------------------------------------------------- | -------- | ---------------------------------------- |
| `uuid` | path | string | β
| Transaction UUID |
| `page` | query | integer | | Zero-based page index (0..N) |
| `size` | query | integer | | The size of the page to be returned |
| `uuid` | query | string | | Unique identifier of the document |
| `type` | query | enum: `MEXICAN_FISCAL_INVOICE`/`INVOICE`/`RECEIPT`/`OTHER` | | Type of the extracted document |
| `validationStatus` | query | enum: `VALIDATED_BY_CLARA`/`VALIDATED_BY_USER`/`NOT_VERIFIED` | | Status of the validation of the document |
**Response Schema (`ExtractedDocumentPage`):**
| Field | Type | Example |
| ------------------ | -------------------------- | ------- |
| `totalPages` | integer (int32) | |
| `totalElements` | integer (int64) | |
| `first` | boolean | |
| `last` | boolean | |
| `size` | integer (int32) | |
| `content` | array of ExtractedDocument | |
| `number` | integer (int32) | |
| `sort` | object (SortObject) | |
| `pageable` | object (PageableObject) | |
| `numberOfElements` | integer (int32) | |
| `empty` | boolean | |
**`sort` object (SortObject):**
| Field | Type | Example |
| ---------- | ------- | ------- |
| `empty` | boolean | |
| `sorted` | boolean | |
| `unsorted` | boolean | |
**`pageable` object (PageableObject):**
| Field | Type | Example |
| ------------ | ------------------- | ------- |
| `offset` | integer (int64) | |
| `sort` | object (SortObject) | |
| `paged` | boolean | |
| `pageNumber` | integer (int32) | |
| `pageSize` | integer (int32) | |
| `unpaged` | boolean | |
# Extracted Documents
Source: https://developers.clara.team/api-reference/extracted-documents
Retrieve structured fiscal documents (XML invoices, receipts) tied to transactions.
This service is available in **v3** only.
## Authentication Requirements
To access this endpoint, ensure the following:
* Use **mutual TLS (MTLS)** for secure two-way certificate validation.
* Obtain an **OAuth2 access token** via the `/oauth/token` endpoint.
* Include the **Bearer token** in the `Authorization` header of your request.
## Endpoint
```
GET /api/v3/transactions/{uuid}/extracted-documents
```
* **Base URL examples**:
* `https://public-api.mx.clara.com`
* `https://public-api.br.clara.com`
* `https://public-api.co.clara.com`
## Path Parameter
| Name | Type | Required | Description |
| ---- | ------ | -------- | ----------------------- |
| uuid | string | β
Yes | UUID of the transaction |
## Query Parameters (Optional)
| Name | Type | Description |
| ---------------- | ------- | ------------------------------------------------------------------------------------- |
| page | integer | Page index, zero-based. Default: 0 |
| size | integer | Items per page. Default: 20 |
| uuid | uuid | Filter by extracted document UUID |
| type | enum | Filter by document type: MEXICAN\_FISCAL\_INVOICE, INVOICE, RECEIPT, OTHER |
| validationStatus | enum | Filter by validation status: VALIDATED\_BY\_CLARA, VALIDATED\_BY\_USER, NOT\_VERIFIED |
## Response
Returns a paginated list of extracted documents associated with the transaction. Each document includes metadata and content such as:
### Example Document Object
```json theme={null}
{
"uuid": "123e4567-e89b-12d3-a456-426614174000",
"type": "INVOICE",
"userUuid": "cd22be0b-c074-41d3-8645-77e1507c8562",
"data": {
"folioFiscalUuid": "123e4567-e89b-12d3-a456-426614174000",
"invoiceId": "INV-2023-001",
"receiptDate": "2023-10-15",
"issueDate": "2023-10-15",
"billingDate": "2023-10-31",
"country": "MX",
"issuer": {
"legalName": "ACME Corporation",
"taxIdentifier": "ABC123456XYZ"
},
"items": [
{
"name": "Office Chair",
"unitPrice": 149.99,
"quantity": 2,
"total": 299.98
}
],
"itemsDescription": "Office supplies",
"amount": {
"currency": "USD",
"subTotal": 100.0,
"taxesAmount": 16.0,
"tipAmount": 10.0,
"total": 126.0,
"taxPercentage": 16.0,
"tipPercentage": 10.0
}
},
"fileValidation": {
"status": "VALIDATED_BY_CLARA",
"date": "2023-10-15T14:30:00",
"user": "John Doe",
"userUuid": "123e4567-e89b-12d3-a456-426614174000"
}
}
```
## Validation Status Details
| Status | Description |
| -------------------- | ------------------------------------ |
| VALIDATED\_BY\_CLARA | Automatically validated successfully |
| VALIDATED\_BY\_USER | Validated manually by a user |
| NOT\_VERIFIED | Document could not be validated |
## Successful Response
| Status | Meaning |
| ------ | ----------------------------------------- |
| 200 | OK - List of extracted documents returned |
## Error Responses
| Status | Meaning |
| ------ | ------------ |
| 400 | Bad Request |
| 401 | Unauthorized |
| 403 | Forbidden |
## Example cURL Request
```bash theme={null}
curl --location --request GET 'https://public-api.mx.clara.com/api/v3/transactions/{uuid}/extracted-documents' \
--header 'Authorization: Bearer {your_access_token}' \
--cert {client_cert_path} \
--key {client_key_path}
```
Replace `{uuid}`, `{your_access_token}`, `{client_cert_path}`, and `{client_key_path}` with actual values.
## Summary
This endpoint enables retrieval of structured, validated financial documents (invoices, receipts, etc.) tied to a transaction. It supports robust filtering and pagination, and enforces secure access through MTLS and OAuth2.
***
## Endpoint Reference
### `GET /api/v3/transactions/{uuid}/extracted-documents`
Find extracted documents for a Transaction by uuid
**Parameters:**
| Parameter | In | Type | Required | Description |
| ------------------ | ----- | ------------------------------------------------------------- | -------- | ---------------------------------------- |
| `uuid` | path | string | β
| Transaction UUID |
| `page` | query | integer | | Zero-based page index (0..N) |
| `size` | query | integer | | The size of the page to be returned |
| `uuid` | query | string | | Unique identifier of the document |
| `type` | query | enum: `MEXICAN_FISCAL_INVOICE`/`INVOICE`/`RECEIPT`/`OTHER` | | Type of the extracted document |
| `validationStatus` | query | enum: `VALIDATED_BY_CLARA`/`VALIDATED_BY_USER`/`NOT_VERIFIED` | | Status of the validation of the document |
**Response Schema (`ExtractedDocumentPage`):**
| Field | Type | Example |
| ------------------ | -------------------------- | ------- |
| `totalPages` | integer (int32) | |
| `totalElements` | integer (int64) | |
| `first` | boolean | |
| `last` | boolean | |
| `size` | integer (int32) | |
| `content` | array of ExtractedDocument | |
| `number` | integer (int32) | |
| `sort` | object (SortObject) | |
| `pageable` | object (PageableObject) | |
| `numberOfElements` | integer (int32) | |
| `empty` | boolean | |
**`sort` object (SortObject):**
| Field | Type | Example |
| ---------- | ------- | ------- |
| `empty` | boolean | |
| `sorted` | boolean | |
| `unsorted` | boolean | |
**`pageable` object (PageableObject):**
| Field | Type | Example |
| ------------ | ------------------- | ------- |
| `offset` | integer (int64) | |
| `sort` | object (SortObject) | |
| `paged` | boolean | |
| `pageNumber` | integer (int32) | |
| `pageSize` | integer (int32) | |
| `unpaged` | boolean | |
# Groups
Source: https://developers.clara.team/api-reference/groups
Create, update, retrieve, and delete groups/departments.
## What is the Groups API?
The **Groups API** allows you to manage user-defined groups within your organization. These groups can represent teams, departments, or any custom segmentation of users, and are useful for assigning policies, budgets, or approval rules.
This API enables you to:
* Create and update groups
* Retrieve details of individual or all groups
* Delete groups when no longer needed
## Available Endpoints
| Operation | Endpoint | Method |
| :------------------- | :------------------ | :----- |
| Retrieve all groups | `/v2/groups` | GET |
| Retrieve group by ID | `/v2/groups/{uuid}` | GET |
| Create group | `/v2/groups` | POST |
| Update group | `/v2/groups/{uuid}` | PATCH |
| Delete group | `/v2/groups/{uuid}` | DELETE |
## Retrieve All Groups
List all groups defined in your organization.
### Endpoint
`GET /v2/groups`
### cURL Request
```curl cURL theme={null}
curl -X GET \
"https://public-api.mx.clara.com/api/v2/groups" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```
### Sample JSON Response
```json JSON theme={null}
[
{
"uuid": "group-123",
"name": "Finance",
"description": "Handles all financial operations",
"status": "ACTIVE"
},
{
"uuid": "group-456",
"name": "Engineering",
"description": "Software and product development",
"status": "ACTIVE"
}
]
```
## Retrieve Group by UUID
Get full details of a specific group by its UUID.
### Endpoint
`GET /v2/groups/{uuid}`
### cURL Request
```curl cURL theme={null}
curl -X GET \
"https://public-api.mx.clara.com/api/v2/groups/group-123" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```
### Sample JSON Response
```json JSON theme={null}
{
"uuid": "group-123",
"name": "Finance",
"description": "Handles all financial operations",
"status": "ACTIVE"
}
```
## Create a Group
Create a new user group by specifying a name and optional description.
### Endpoint
`POST /v2/groups`
### cURL Request
```curl cURL theme={null}
curl -X POST \
"https://public-api.mx.clara.com/api/v2/groups" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Operations",
"description": "Logistics and supply chain team"
}'
```
### Sample JSON Response
```json JSON theme={null}
{
"uuid": "group-789",
"name": "Operations",
"description": "Logistics and supply chain team",
"status": "ACTIVE"
}
```
## Update a Group
Edit the name or description of an existing group.
### Endpoint
`PATCH /v2/groups/{uuid}`
### cURL Request
```curl cURL theme={null}
curl -X PATCH \
"https://public-api.mx.clara.com/api/v2/groups/group-789" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Ops",
"description": "Updated name for Operations team"
}'
```
## Delete a Group
Remove a group from your organization by UUID. Use with caution, as this may impact user-role associations or policy rules.
### Endpoint
`DELETE /v2/groups/{uuid}`
### cURL Request
```curl cURL theme={null}
curl -X DELETE \
"https://public-api.mx.clara.com/api/v2/groups/group-789" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```
\*\*π‘ Tip: \*\* Groups can be used to assign policies, budgets, or approval flows in a centralized way.
\*\*β οΈ Note: \*\* Deleting a group does not affect users, but it may disrupt processes tied to that group such as approval chains or spend limits.
***
## Endpoint Reference
### `GET /api/v2/groups`
Find all groups
**Parameters:**
| Parameter | In | Type | Required | Description |
| --------- | ----- | ------- | -------- | ----------------------------------- |
| `page` | query | integer | | Zero-based page index (0..N) |
| `size` | query | integer | | The size of the page to be returned |
### `PUT /api/v2/groups`
Update group details
### `POST /api/v2/groups`
Create Group
### `GET /api/v2/groups/{uuid}`
Find group by UUID
**Parameters:**
| Parameter | In | Type | Required | Description |
| --------- | ---- | ------ | -------- | ----------- |
| `uuid` | path | string | β
| Group UUID |
### `DELETE /api/v2/groups/{uuid}`
Delete a single group by UUID
**Parameters:**
| Parameter | In | Type | Required | Description |
| --------- | ---- | ------ | -------- | --------------------------- |
| `uuid` | path | string | β
| UUID of the group to delete |
v1 is legacy and read-only. Migrate to v2 for full group management.
## What is the Transactions API?
The **Groups API v1** allows you to retrieve information about the user groups defined in your Clara account. Groups are typically used to organize users into departments, business units, or approval chains.
This API can be used to:
* Display group options when assigning users or policies
* Link transactions or cards to internal teams
* Build internal reporting dashboards by group
π Note: This version of the API is **read-only**. To create, update, or delete groups, use [Groups API v2](#).
## Available Endpoints
| Operation | Endpoint | Method |
| ------------------ | ------------------- | ------ |
| Find all groups | `/v1/groups` | GET |
| Find group by UUID | `/v1/groups/{uuid}` | GET |
## Find all groups
Use this endpoint to **retrieve the list of all groups** configured in your organization. Each group includes metadata such as name, status, and unique ID.
### Endpoint
`GET /v1/groups`
### cURL Request
```curl cURL theme={null}
curl -X GET \
"https://public-api.mx.clara.com/api/v1/groups" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```
### Sample JSON Response
```json JSON theme={null}
[
{
"uuid": "group-001",
"name": "Finance",
"status": "ACTIVE"
},
{
"uuid": "group-002",
"name": "Sales",
"status": "ACTIVE"
}
]
```
## Find group by UUID
Use this endpoint to fetch details for a specific group by its UUID.
### Endpoint
`GET /v1/groups/{uuid}`
### cURL Request
```curl cURL theme={null}
curl -X GET \
"https://public-api.mx.clara.com/api/v1/groups/group-001" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```
### Sample JSON Response
```json JSON theme={null}
{
"uuid": "group-001",
"name": "Finance",
"status": "ACTIVE"
}
```
\*\*π‘ Tip: \*\*Use the uuid of a group to associate users, approval flows, or reporting filters with that group.
\*\*β οΈ Note: \*\*The v1 API does not allow modifying groups β it is read-only and intended for lookup operations.
***
## Endpoint Reference
### `GET /api/v1/groups`
Find all groups
**Parameters:**
| Parameter | In | Type | Required | Description |
| --------- | ----- | ------- | -------- | ----------------------------------- |
| `page` | query | integer | | Zero-based page index (0..N) |
| `size` | query | integer | | The size of the page to be returned |
### `GET /api/v1/groups/{uuid}`
Find group by UUID
**Parameters:**
| Parameter | In | Type | Required | Description |
| --------- | ---- | ------ | -------- | ----------- |
| `uuid` | path | string | β
| Group UUID |
# Invoices
Source: https://developers.clara.team/api-reference/invoices
Access CFDI fiscal invoice data linked to transactions (Mexico only).
Recommended for all new integrations.
## When a Transaction Has an Invoice
If a transaction has invoice:
* The `hasInvoice` field is set to `true`
* You'll receive a **link to download them**
* URLs are valid for **12 hours**
## Endpoint Format
`GET /v3/transactions/{uuid}/invoices`
Use this endpoint to retrieve XML invoice details and metadata associated with a specific transaction.
## Example: Getting Invoices for a Transaction
In the following example, we will get the invoice information for the transaction with the UUID "47f8ed9e-4d7b-450b-ad6a-f1d83e3ce4e1" in Mexico.
### cURL Request
```curl cURL theme={null}
curl -X GET
"https://public-api.mx.clara.com/api/v3/transactions/47f8ed9e-4d7b-450b-ad6a-f1d83e3ce4e1/invoices" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```
### Sample JSON Response
```curl JSON theme={null}
{
"transactionUuid": "47f8ed9e-4d7b-450b-ad6a-f1d83e3ce4e1",
"invoices": [
{
"invoiceId": "54cd6b23-5146-437f-b133-879c432e6776",
"invoiceNumber": null,
"taxRegime": "621",
"issuer": {
"rfc": "CLARA123XML",
"businessName": "CLARA"
},
"taxReceipts": {
"cfdi": "G03",
"paymentMethod": "Q4"
},
"tax": {
"retained": {
"isr": 0.75,
"iva": null,
"ieps": null
},
"transferred": {
"iva": 0.0,
"ieps": 0.0
}
},
"amount": {
"total": 400.00,
"subTotal": 300.00,
"currency": "MXN"
},
"documentDate": "2024-10-01",
"xmlStatus": "Vigente",
"xmlCode": "S β Comprobante obtenido satisfactoriamente."
}
]
}
```
β οΈ The download URL is temporary and will expire 12 hours after generation. Ensure you download and store the file before it expires.
βΉοΈ Note: The example provided contains mock data and does not reflect real tax calculations or financial details.
***
## Endpoint Reference
### `GET /api/v3/transactions/{uuid}/invoices`
Get a transaction by UUID
**Parameters:**
| Parameter | In | Type | Required | Description |
| --------- | ---- | ------ | -------- | ---------------- |
| `uuid` | path | string | β
| Transaction UUID |
**Response Schema (`TransactionInvoiceResponse`):**
| Field | Type | Example |
| ----------------- | ------------------------ | -------------------------------------- |
| `transactionUuid` | string | `4ea5a94a-2c3c-4601-b623-c30260c21dbc` |
| `invoices` | array of InvoiceResponse | |
### `GET /api/v3/invoices`
Find all Invoices with optional filters
**Parameters:**
| Parameter | In | Type | Required | Description |
| ------------------------ | ----- | ------- | -------- | ------------------------------------------------------------------------------------------ |
| `page` | query | integer | | Zero-based page index (0..N) |
| `size` | query | integer | | The size of the page to be returned |
| `invoiceNumber` | query | string | | Invoice number to filter invoices |
| `issuerRfc` | query | string | | RFC Issuer number to filter invoices |
| `transactionUuid` | query | string | | Transaction UUID to filter invoices |
| `invoiceId` | query | string | | Invoice ID to filter invoices |
| `documentDateRangeStart` | query | string | | Start date for invoice date range filter (must be used together with documentDateRangeEnd) |
| `documentDateRangeEnd` | query | string | | End date for invoice date range filter (must be used together with documentDateRangeStart) |
**Response Schema (`InvoicePageV3`):**
| Field | Type | Example |
| ------------------ | ----------------------- | ------- |
| `totalPages` | integer (int32) | |
| `totalElements` | integer (int64) | |
| `first` | boolean | |
| `last` | boolean | |
| `size` | integer (int32) | |
| `content` | array of InvoiceV3 | |
| `number` | integer (int32) | |
| `sort` | object (SortObject) | |
| `pageable` | object (PageableObject) | |
| `numberOfElements` | integer (int32) | |
| `empty` | boolean | |
**`sort` object (SortObject):**
| Field | Type | Example |
| ---------- | ------- | ------- |
| `empty` | boolean | |
| `sorted` | boolean | |
| `unsorted` | boolean | |
**`pageable` object (PageableObject):**
| Field | Type | Example |
| ------------ | ------------------- | ------- |
| `offset` | integer (int64) | |
| `sort` | object (SortObject) | |
| `paged` | boolean | |
| `pageNumber` | integer (int32) | |
| `pageSize` | integer (int32) | |
| `unpaged` | boolean | |
## What is the Invoices API?
The **Invoices API v2** allows you to **retrieve invoice records** associated with transactions made through Clara. These invoices may be manually uploaded by users or automatically extracted from provider documents such as CFDI XML files (in Mexico).
This API is useful for:
* Reviewing fiscal documents linked to card transactions
* Building tax compliance or expense reconciliation tools
* Filtering invoices by multiple criteria such as number, transaction, date, or document ID
## Available Endpoints
| Operation | Endpoint | Method |
| -------------------------------------- | -------------- | ------ |
| Get all invoices with optional filters | `/v2/invoices` | GET |
## Find all invoices with optional filters
Use this endpoint to **fetch a paginated list of invoices**, optionally filtered by:
* `invoiceNumber`
* `transactionUuid`
* `invoiceId`
* `documentDateRangeStart`
* `documentDateRangeEnd`
π **Note:** The date range filter is only applied if **both** `documentDateRangeStart` and `documentDateRangeEnd` are present
### Endpoint
`GET /v2/invoices`
### Available Query Parameters
| Parameter | Type | Required | Description |
| ------------------------ | ------ | -------- | ---------------------------------------------------------- |
| `invoiceNumber` | string | optional | Filters by invoice number |
| `transactionUuid` | string | optional | Filters by associated transaction UUID |
| `invoiceId` | string | optional | Filters by internal invoice ID |
| `documentDateRangeStart` | string | optional | Start date in ISO format (requires `documentDateRangeEnd`) |
| `documentDateRangeEnd` | string | optional | End date in ISO format (requires `documentDateRangeStart`) |
### cURL Request
```curl cURL theme={null}
curl -X GET \
"https://public-api.mx.clara.com/api/v2/invoices?transactionUuid=txn-123&documentDateRangeStart=2024-06-01&documentDateRangeEnd=2024-06-30" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```
### Sample JSON Response
```json JSON theme={null}
{
"content": [
{
"uuid": "inv-001",
"invoiceNumber": "A123",
"transactionUuid": "txn-123",
"amount": 400.00,
"currency": "MXN",
"documentDate": "2024-06-15",
"xmlStatus": "Valid",
"issuer": {
"rfc": "ABC123456T89",
"businessName": "Proveedor S.A. de C.V."
}
}
],
"page": 0,
"size": 20,
"totalElements": 1,
"totalPages": 1
}
```
**π‘ Tip:** You can combine filters to narrow down invoices by vendor, date, or linked transactions.
\*\*β οΈ Note: \*\*This endpoint uses pagination, so be sure to handle page and size parameters or iterate through results if needed.
# Labels
Source: https://developers.clara.team/api-reference/labels
Create, update, retrieve, and delete transaction labels.
This service is not yet available in v3. Available in **v2** only.
## What is the Labels API?
The **Labels API (v2)** allows you to manage custom classification tags (called *labels*) in your Clara account. Labels are useful for organizing transactions, users, or workflows based on internal categorization (e.g., "Client A", "Internal Event", "R\&D", etc.).
With this API, you can:
* Create, update, and delete labels
* Retrieve all existing labels or a specific one
* Bulk-delete labels when no longer needed
## Available Endpoints
| Operation | Endpoint | Method |
| ---------------------- | ------------------- | ------ |
| List all labels | `/v2/labels` | GET |
| Get label by UUID | `/v2/labels/{uuid}` | GET |
| Create multiple label | `/v2/labels` | POST |
| Update a label | `/v2/labels/{uuid}` | PATCH |
| Delete a label | `/v2/labels/{uuid}` | DELETE |
| Delete multiple labels | `/v2/labels/delete` | POST |
## List all labels
**Use this endpoint to retrieve all the labels that have been created in your organization.**\
You can use this data to show label options in a UI, filter transactions by label, or review current classification structures.
### Endpoint
`GET /v2/labels`
### cURL Request
```curl cURL theme={null}
curl -X GET \
"https://public-api.mx.clara.com/api/v2/labels" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```
### Sample JSON Response
```json JSON theme={null}
[
{
"uuid": "label-123",
"name": "Marketing",
"description": "Marketing-related expenses",
"status": "ACTIVE"
}
]
```
## Get Label by UUID
Use this to fetch full details for a specific label, including its name, description, status, and metadata.
### Endpoint
`GET /v2/labels/{uuid}`
### cURL Request
```curl cURL theme={null}
curl -X GET \
"https://public-api.mx.clara.com/api/v2/labels/label-123" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```
### Sample JSON Response
```json JSON theme={null}
{
"uuid": "label-123",
"name": "Marketing",
"description": "Marketing-related expenses",
"status": "ACTIVE"
}
```
## Create multiple Labels
Use this to create a new label, specifying its name and an optional description. You can later assign this label to transactions or users.
### Endpoint
`POST /v2/labels`
### cURL Request
```curl cURL theme={null}
curl -X POST \
"https://public-api.mx.clara.com/api/v2/labels" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Events",
"description": "Internal event budgets"
}'
```
### Sample JSON Response
```json JSON theme={null}
{
"uuid": "label-789",
"name": "Events",
"description": "Internal event budgets",
"status": "ACTIVE"
}
```
## Update a Label details
Use this endpoint to modify an existing label, such as changing the label name or updating its description.
### Endpoint
`PATCH /v2/labels/{uuid}`
### cURL Request
```curl cURL theme={null}
curl -X PATCH \
"https://public-api.mx.clara.com/api/v2/labels/label-789" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Events & Sponsorships",
"description": "Updated name and scope"
}'
```
## Delete a single Label
Use this to delete a single label by UUID. This is useful when a label is no longer relevant or has been replaced by another.
**β οΈ Note:** Deleting a label doesn't remove it from historical data, but it will no longer be assignable.
### Endpoint
`DELETE /v2/labels/{uuid}`
### cURL Request
```curl cURL theme={null}
curl -X DELETE \
"https://public-api.mx.clara.com/api/v2/labels/label-789" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```
## Delete Multiple Labels
Use this endpoint to bulk-delete labels. This is especially useful for cleanup tasks or automated workflows where multiple labels must be removed at once.
### Endpoint
`POST /v2/labels/delete`
### cURL Request
```curl cURL theme={null}
curl -X POST \
"https://public-api.mx.clara.com/api/v2/labels/delete" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"uuids": ["label-123", "label-456"]
}'
```
**π‘ Tip:** Labels can be used across transactions, reports, and internal workflows for custom tracking and analysis.
\*\*β οΈ Note: \*\*Once deleted, a label cannot be reassigned to new entities.
***
## Endpoint Reference
### `GET /api/v2/labels`
List all labels (v2)
### `POST /api/v2/labels`
Create labels (v2)
**Request Body (`CreateLabelsRequest`):**
| Field | Type | Example |
| ------- | --------------- | ------- |
| `names` | array of string | |
### `PUT /api/v2/labels/{uuid}`
Update label (v2)
**Parameters:**
| Parameter | In | Type | Required | Description |
| --------- | ---- | ------------- | -------- | ----------- |
| `uuid` | path | string (uuid) | β
| |
**Request Body (`UpdateLabelRequest`):**
| Field | Type | Example |
| ------ | ------ | -------------------- |
| `name` | string | `Updated Label Name` |
### `DELETE /api/v2/labels/{uuid}`
Delete label (v2)
**Parameters:**
| Parameter | In | Type | Required | Description |
| --------- | ---- | ------------- | -------- | ----------- |
| `uuid` | path | string (uuid) | β
| |
### `DELETE /api/v2/labels/bulk-delete`
Bulk delete labels (v2)
**Request Body (`BulkDeleteLabelsRequest`):**
| Field | Type | Example |
| ------- | --------------- | ------- |
| `uuids` | array of string | |
# Locations
Source: https://developers.clara.team/api-reference/locations
Retrieve company cost centers and locations.
## What is the Locations API?
The **Locations API (v2)** allows you to retrieve information about your organization's locations (also known as cost centers or office sites). These locations can later be associated with users, transactions, cards, and policies.
This API is typically used to:
* Fetch a list of all available locations in your company
* Get detailed data for a specific location by UUID
* Integrate location metadata into internal tools or reporting systems
## Available Endpoints
| Operation | Endpoint | Method |
| ---------------------- | ---------------------- | ------ |
| Retrieve all locations | `/v2/locations` | GET |
| Get location by UUID | `/v2/locations/{uuid}` | GET |
## Retrieve all locations
Get a complete list of all locations associated with your company.
### Endpoint
`GET /v2/locations`
### cURL Request
```curl cURL theme={null}
curl -X GET \
"https://public-api.mx.clara.com/api/v2/locations" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```
### Sample JSON Response
```json JSON theme={null}
[
{
"uuid": "e8b5b764-f8d9-42d0-861a-f13aa2312734",
"name": "Headquarters - CDMX",
"code": "CDMX-HQ",
"status": "ACTIVE"
},
{
"uuid": "a2a8b29f-3c84-4d58-bcb1-b2dc3b23cf01",
"name": "Warehouse - GDL",
"code": "GDL-WHS",
"status": "ACTIVE"
}
]
```
## Retrieve Location by UUID
Fetch detailed information about a specific location using its UUID.
### Endpoint
`GET /v2/locations/{uuid}`
### cURL Request
```curl cURL theme={null}
curl -X GET \
"https://public-api.mx.clara.com/api/v2/locations/e8b5b764-f8d9-42d0-861a-f13aa2312734" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```
### Sample JSON Response
```json JSON theme={null}
{
"uuid": "e8b5b764-f8d9-42d0-861a-f13aa2312734",
"name": "Headquarters - CDMX",
"code": "CDMX-HQ",
"status": "ACTIVE",
"createdAt": "2023-10-15T10:30:00Z"
}
```
**π‘ Tip:** Location UUIDs can be used when creating users, cards, or setting approval policies to associate activity with a specific office or department.
**β οΈ Note:** Locations marked as INACTIVE are still returned, but should not be assigned to new resources.
***
## Endpoint Reference
### `GET /api/v2/locations`
Find all locations
**Parameters:**
| Parameter | In | Type | Required | Description |
| --------- | ----- | ------- | -------- | ----------------------------------- |
| `page` | query | integer | | Zero-based page index (0..N) |
| `size` | query | integer | | The size of the page to be returned |
### `GET /api/v2/locations/{uuid}`
Find location by UUID
**Parameters:**
| Parameter | In | Type | Required | Description |
| --------- | ---- | ------ | -------- | ------------- |
| `uuid` | path | string | β
| Location UUID |
v1 is legacy and read-only. Migrate to v2 for full location management.
## What is the Locations API?
The **Locations API v1** allows you to retrieve the list of physical or organizational locations configured in your Clara account. Locations often represent cost centers, departments, office branches, or teams, and are used to organize users and expenses.
This API can be used to:
* Display location options when assigning users or filtering data
* Map transactions or cards to specific business units
* Support reporting or internal structure alignment
π Note: This is a **read-only** version. To manage or create locations, use [Locations API v2](#).
## Available Endpoints
| Operation | Endpoint | Method |
| -------------------- | ---------------------- | ------ |
| List all locations | `/v1/locations` | GET |
| Get location by UUID | `/v1/locations/{uuid}` | GET |
## Find all locations
Use this endpoint to **retrieve the full list of locations** configured in your organization. Each location includes metadata such as name, code, and status.
### Endpoint
`GET /v1/locations`
### cURL Request
```curl cURL theme={null}
curl -X GET \
"https://public-api.mx.clara.com/api/v1/locations" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```
### Sample JSON Response
```json JSON theme={null}
[
{
"uuid": "loc-001",
"name": "Headquarters - CDMX",
"code": "CDMX-HQ",
"status": "ACTIVE"
},
{
"uuid": "loc-002",
"name": "Warehouse - Monterrey",
"code": "MTY-WHS",
"status": "INACTIVE"
}
]
```
## Find Location by UUID
Use this endpoint to get detailed information about a specific location using its unique identifier (uuid).
### Endpoint
`GET /v1/locations/{uuid}`
### cURL Request
```curl cURL theme={null}
curl -X GET \
"https://public-api.mx.clara.com/api/v1/locations/loc-001" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```
### Sample JSON Response
```json JSON theme={null}
{
"uuid": "loc-001",
"name": "Headquarters - CDMX",
"code": "CDMX-HQ",
"status": "ACTIVE"
}
```
**π‘ Tip:** Use the code field to link internal systems (e.g., ERP or HR) with Clara locations for consistency in reporting.
**β οΈ Note:** This version of the API does not support creating or updating locations β only retrieval is available.
***
## Endpoint Reference
### `GET /api/v1/locations`
Find all locations
**Parameters:**
| Parameter | In | Type | Required | Description |
| --------- | ----- | ------- | -------- | ----------------------------------- |
| `page` | query | integer | | Zero-based page index (0..N) |
| `size` | query | integer | | The size of the page to be returned |
### `GET /api/v1/locations/{uuid}`
Find location by UUID
**Parameters:**
| Parameter | In | Type | Required | Description |
| --------- | ---- | ------ | -------- | ------------- |
| `uuid` | path | string | β
| Location UUID |
# Logs
Source: https://developers.clara.team/api-reference/logs
Retrieve API access logs by month or day.
This service is not yet available in v3. Available in **v1** only.
The Clara Logs API offers structured access to historical API logs, allowing clients to retrieve request-level data and usage statistics within a defined temporal scope. This is especially useful for monitoring, auditing, billing analytics, and debugging purposes.
## Access Control
* Logs API access is restricted by design.
* Requests must include date-based filters: year, month, and optionally day.
* No endpoint available to list all logs without any time constraint.
## Endpoints Overview
| Endpoint | Description |
| ------------------------- | -------------------------------------------------------- |
| `/api/v1/logs/yyyy/MM` | Get logs for a specific month (year and month required). |
| `/api/v1/logs/yyyy/MM/dd` | Get logs for a specific day. |
| `/api/v1/logs/current` | Get logs for the current month. |
## Filtering Rules
* **year** and **month** required
* **day-level** filtering is optional
* No wildcard or unbounded access to the full log history.
This structure ensures controlled data volumes and better performance.
## Response Structure
Every response contains two main components:
### Stats:
* `total`: Total number of requests
* `chargeable`: Number of requests marked as chargeable
* `nonChargeable`: Requests that are not chargeable
### Requests (list of detailed logs):
* `id`: Unique identifier of the log entry
* `responseStatus`: HTTP status code returned
* `projectTokenId`: Project identifier for the request
* `requestUri`: URI requested by the client
* `method`: HTTP method used (GET, POST, etc)
* `chargeable`: Boolean flag indicating billing impact
* `instant`: Timestamp of the request (epoch milliseconds)
## Example Response
```json theme={null}
{
"stats": {
"total": 1,
"chargeable": 1,
"nonChargeable": 0
},
"requests": [
{
"id": "1",
"responseStatus": "200",
"projectTokenId": "project-123",
"requestUri": "/api/v1/charge",
"method": "POST",
"chargeable": true,
"instant": 123141241
}
]
}
```
# Reimbursements
Source: https://developers.clara.team/api-reference/reimbursements
Retrieve reimbursement data for out-of-pocket expenses.
This service is available in **v3** only.
## How to Find Reimbursements via Clara API
This guide explains how to use the `GET /api/v3/reimbursements` endpoint to retrieve reimbursements in the Clara API system.
***
## Authentication Requirements
To access this endpoint, ensure the following:
* Use **mutual TLS (MTLS)** for secure two-way certificate validation.
* Obtain an **OAuth2 access token** via the `/oauth/token` endpoint.
* Include the **Bearer token** in the `Authorization` header of your request.
***
## Endpoint
```
GET /api/v3/reimbursements
```
* **Base URL examples**:
* `https://public-api.mx.clara.com`
* `https://public-api.br.clara.com`
* `https://public-api.co.clara.com`
***
## Query Parameters (Optional)
| Name | Type | Description | Example |
| ------------------------ | --------- | ------------------------------------------------ | -------------------------------------------------------------------------- |
| page | integer | Zero-based page index (0..N). Default: 0 | 0 |
| size | integer | The size of the page to be returned. Default: 20 | 20 |
| requestCreationDateStart | string | Start date for request creation (yyyy-MM-dd) | 2023-01-01 |
| requestCreationDateEnd | string | End date for request creation (yyyy-MM-dd) | 2023-12-31 |
| expenseDateStart | string | Start date for expense (yyyy-MM-dd) | 2023-01-01 |
| expenseDateEnd | string | End date for expense (yyyy-MM-dd) | 2023-12-31 |
| finalApprovalDateStart | string | Start date for final approval (yyyy-MM-dd) | 2023-01-01 |
| finalApprovalDateEnd | string | End date for final approval (yyyy-MM-dd) | 2023-12-31 |
| paymentDateStart | string | Start date for payment (yyyy-MM-dd) | 2023-01-01 |
| paymentDateEnd | string | End date for payment (yyyy-MM-dd) | 2023-12-31 |
| lastUpdateDateStart | string | Start date for last update (yyyy-MM-dd) | 2023-01-01 |
| lastUpdateDateEnd | string | End date for last update (yyyy-MM-dd) | 2023-12-31 |
| categoryCodes | string\[] | Category codes (digits only), comma-separated | 23,25 |
| requesterUuids | uuid\[] | UUIDs of requesters (comma-separated list) | a0c82a20-ac09-4cfd-b429-d0623585911e, b1d93b31-bd10-5dfe-c530-e0734696022f |
| statuses | enum\[] | Reimbursement statuses: PENDING, APPROVED, etc. | PENDING, APPROVED |
| requesterName | string | Name of the requester | John Doe |
| uuids | uuid\[] | UUIDs of reimbursements (comma-separated list) | a0c82a20-ac09-4cfd-b429-d0623585911e, b1d93b31-bd10-5dfe-c530-e0734696022f |
***
## Successful Response
| Status | Meaning |
| ------ | ------------------------------------ |
| 200 | OK - List of reimbursements returned |
***
## Error Responses
| Status | Meaning |
| ------ | ------------ |
| 400 | Bad Request |
| 401 | Unauthorized |
| 403 | Forbidden |
***
## Example cURL Request
```bash theme={null}
curl --location --request GET 'https://public-api.mx.clara.com/api/v3/reimbursements?page=0&size=10&statuses=PENDING' \
--header 'Authorization: Bearer {your_access_token}' \
--cert {client_cert_path} \
--key {client_key_path}
```
Replace `{your_access_token}`, `{client_cert_path}`, and `{client_key_path}` with actual values.
***
## Example Response Object
```json theme={null}
{
"totalElements": 1,
"totalPages": 1,
"content": [
{
"uuid": "a0c82a20-ac09-4cfd-b429-d0623585911e",
"description": "Airport trip for client meeting",
"audit": {
"requestCreationDate": "2023-05-08",
"expenseDate": "2023-05-07",
"finalApprovalDate": "2023-05-08",
"paymentDate": "2023-05-09",
"lastUpdateDate": "2023-05-09"
},
"labels": [
{
"uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "Business Travel",
"links": [
{
"rel": "self",
"href": "https://public-api.mx.clara.com/api/v2/labels/3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
]
}
],
"merchant": {
"name": "Uber",
"description": "Ride sharing service",
"categoryCode": 16,
"category": "Travel",
"countryCode": "US"
},
"requester": {
"uuid": "c616af9c-43ee-42e9-ba25-8bfacea036a4",
"name": "Jane Doe",
"links": [
{
"rel": "self",
"href": "https://public-api.mx.clara.com/api/v3/users/c616af9c-43ee-42e9-ba25-8bfacea036a4"
}
]
},
"groups": [
{
"uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "Marketing Department",
"links": [
{
"rel": "self",
"href": "https://public-api.mx.clara.com/api/v2/groups/3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
]
}
],
"locations": [
{
"uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "San Francisco Office",
"links": [
{
"rel": "self",
"href": "https://public-api.mx.clara.com/api/v2/locations/3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
]
}
],
"amountValue": {
"currency": "USD",
"amount": 75.5
},
"validationStatus": {
"status": "APPROVED",
"comment": "Approved by manager on 2023-05-08"
},
"attachments": [
{
"uuid": "88a2b46c-ceb7-4c87-89c9-a3452a7c3ae3",
"fileName": "uber-receipt.pdf",
"links": [
{
"rel": "self",
"href": "https://public-api.mx.clara.com/api/v2/attachments/88a2b46c-ceb7-4c87-89c9-a3452a7c3ae3"
}
]
}
],
"paymentDetail": {
"paymentMethod": "CREDIT_LINE",
"paymentMethodNote": "Paid via corporate credit card",
"markedAsPaidBy": "finance@company.com"
}
}
]
}
```
***
***
## Lifecycle Statuses (ValidationStatus β Reimbursements)
The lifecycle of a reimbursement request typically flows through these statuses:
* `PENDING`: Request has been created and is pending review or approval.
* `APPROVED`: Request has passed validation and been approved.
* `SENT_TO_PAY`: Approved and submitted for financial processing.
* `PAYMENT_IN_PROGRESS`: Payment execution has started.
* `PAID`: Funds have been disbursed.
* `REJECTED`: Request did not meet policy or was denied.
* `FINANCE_REJECTED`: Rejected specifically by the finance department.
* `CANCELLED`: Request was manually cancelled before payment.
* `NOT_FOUND`: No matching reimbursement record exists.
* `UNAUTHORIZED`: Request not allowed under current user permissions.
***
## Lifecycle Flow (Reimbursements)
**Create β Pending β Approve/Reject β Sent to Pay β Payment In Progress β Paid**
1. **Creation**: A reimbursement request is submitted. Initial status: `PENDING`.
2. **Approval**: The request may be `APPROVED` or `REJECTED` based on validations.
3. **Cancellation**: A `PENDING` request can be cancelled, moving to `CANCELLED`.
4. **Financial Routing**: Once approved, it moves to `SENT_TO_PAY`.
5. **Payment**: Transitions to `PAYMENT_IN_PROGRESS` as disbursement begins.
6. **Completion**: Final state is `PAID` once the process completes.
Exceptional states like `NOT_FOUND` and `UNAUTHORIZED` are returned for invalid operations or permissions.
***
## Summary
* Use the `GET /api/v3/reimbursements` endpoint to retrieve reimbursement records with rich filtering options.
* Apply filters such as creation date, approval date, requester UUIDs, or statuses for granular access.
* Use the lifecycle and validation statuses to interpret reimbursement processing stages.
* Ensure mutual TLS and OAuth2-based access to securely consume the API.
***
## Endpoint Reference
### `GET /api/v3/reimbursements`
List reimbursements (v3)
**Parameters:**
| Parameter | In | Type | Required | Description |
| ----------- | ----- | ------------- | -------- | ------------------------------ |
| `status` | query | string | | Filter by reimbursement status |
| `userUuid` | query | string (uuid) | | Filter by requester UUID |
| `startDate` | query | string (date) | | Filter by expense date start |
| `endDate` | query | string (date) | | Filter by expense date end |
### `GET /api/v3/reimbursements/{uuid}`
Get reimbursement by UUID (v3)
**Parameters:**
| Parameter | In | Type | Required | Description |
| --------- | ---- | ------------- | -------- | ----------- |
| `uuid` | path | string (uuid) | β
| |
**Response Schema (`ReimbursementV3`):**
| Field | Type | Example |
| ------------------ | -------------------------------- | -------------------------------------- |
| `uuid` | string (uuid) | `a0c82a20-ac09-4cfd-b429-d0623585911e` |
| `description` | string | `Airport trip for client meeting` |
| `audit` | object (ReimbursementAudit) | |
| `labels` | array of ReimbursementLabel | |
| `merchant` | object (ReimbursementMerchant) | |
| `requester` | object (BasicUser) | |
| `groups` | array of GroupV2 | |
| `locations` | array of LocationV2 | |
| `amountValue` | object (CurrencyAmount) | |
| `validationStatus` | object (ValidationStatus) | |
| `attachments` | array of ReimbursementAttachment | |
| `paymentDetail` | object (PaymentDetail) | |
# Webhook Subscribers
Source: https://developers.clara.team/api-reference/subscribers
Manage webhook subscribers: create, update, add events, delete.
This service is not yet available in v3. Available in **v1** only.
# How to Use Subscribers Endpoints
This document focuses specifically on managing WebHook **Subscribers** using the Clara API endpoints under `/api/v1/subscribers`.
Each section includes request format, parameters, example payloads, and HTTP responses.
# How to Use Subscribers via Clara API
This document provides detailed usage instructions for the `/api/v1/subscribers` endpoint, including payloads, descriptions, and HTTP status codes.
***
## Create Subscriber
### Endpoint
```
POST /api/v1/subscribers
```
### Request Body
| Field | Type | Required | Description |
| ----------- | --------- | -------- | ---------------------------------------------------- |
| name | string | β
Yes | Name of the webhook subscriber |
| callbackUrl | string | β
Yes | URL to which webhook POSTs will be delivered |
| events | string\[] | β
Yes | List of subscribed event types (e.g. `PAYMENT_PAID`) |
| enabled | boolean | β No | Whether the subscriber is active |
| companyUuid | uuid | β No | Company UUID if not passed in credential |
### Example
```json theme={null}
{
"name": "My Webhook",
"callbackUrl": "https://example.com/my/webhook/endpoint",
"events": [
"PAYMENT_PAID",
"CARD_CREATION_REQUEST_CREATED"
],
"enabled": true,
"companyUuid": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed"
}
```
### Responses
| Status | Meaning |
| ------ | ------------------------------- |
| 201 | Subscriber created successfully |
| 400 | Bad Request |
| 401 | Unauthorized |
| 403 | Forbidden |
***
## Update Subscriber
### Endpoint
```
PATCH /api/v1/subscribers/{uuid}
```
### Request Body
| Field | Type | Required | Description |
| ----------- | --------- | -------- | --------------------------------------- |
| name | string | β No | Updated name |
| callbackUrl | string | β No | New webhook target URL |
| events | string\[] | β No | Updated list of event types |
| enabled | boolean | β No | Whether the subscriber is active or not |
| companyUuid | uuid | β No | Optional company identifier |
### Example
```json theme={null}
{
"name": "Updated Webhook",
"callbackUrl": "https://api.company.com/hook",
"events": [
"CARD_CREATION_REQUEST_ERROR"
],
"enabled": false
}
```
### Responses
| Status | Meaning |
| ------ | ------------------ |
| 200 | Subscriber updated |
| 400 | Bad Request |
| 401 | Unauthorized |
| 403 | Forbidden |
***
## Add Event to Subscriber
### Endpoint
```
POST /api/v1/subscribers/add-event
```
### Request Body
| Field | Type | Required | Description |
| ----------- | ------ | -------- | --------------------------------------------------- |
| callbackUrl | string | β
Yes | Callback URL of the target subscriber |
| event | string | β
Yes | Event to add (e.g. `CARD_CREATION_REQUEST_CREATED`) |
| companyUuid | uuid | β No | Optional company UUID |
### Example
```json theme={null}
{
"callbackUrl": "https://example.com/my/webhook/endpoint",
"event": "CARD_CREATION_REQUEST_CREATED"
}
```
### Responses
| Status | Meaning |
| ------ | ------------ |
| 201 | Event added |
| 400 | Bad Request |
| 401 | Unauthorized |
| 403 | Forbidden |
***
## Delete Event from Subscriber
### Endpoint
```
DELETE /api/v1/subscribers/delete-event
```
### Request Body
| Field | Type | Required | Description |
| ----------- | ------ | -------- | ------------------------------ |
| callbackUrl | string | β
Yes | Callback URL of the subscriber |
| event | string | β
Yes | Event to remove |
| companyUuid | uuid | β No | Optional company UUID |
### Example
```json theme={null}
{
"callbackUrl": "https://example.com/my/webhook/endpoint",
"event": "CARD_CREATION_REQUEST_CREATED"
}
```
### Responses
| Status | Meaning |
| ------ | ------------- |
| 204 | Event removed |
| 400 | Bad Request |
| 401 | Unauthorized |
| 403 | Forbidden |
***
## Delete Subscriber
### Endpoint
```
DELETE /api/v1/subscribers/{uuid}
```
### Request Body
| Field | Type | Required | Description |
| ----------- | ---- | -------- | --------------------- |
| companyUuid | uuid | β No | Optional company UUID |
### Example
```json theme={null}
{
"companyUuid": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed"
}
```
### Responses
| Status | Meaning |
| ------ | ------------------ |
| 204 | Subscriber deleted |
| 400 | Bad Request |
| 401 | Unauthorized |
| 403 | Forbidden |
# Transactions
Source: https://developers.clara.team/api-reference/transactions
Retrieve and manage card transactions with filtering, labels, and attachments.
Recommended for all new integrations.
In version 3 of the Transactions API, Clara offers real-time access to card transactions through a paginated RESTful service.
## When does a Transactions Appear?
Most transactions appear in the API almost instantly. However, some are delayed until Mastercard confirms them through the reconciliation process. This can take up to **2 business days**. Initially, you'll see a **pre-authorization**, which becomes **authorized** after confirmation.
## Transaction Types
* **PURCHASE:** A cardholder buys a product/service.
* **REFUND:** A merchant reimburses the cardholder usually due to a product return or an error in processing the purchase.
* **FEE:** Additional charges from services or admin costs.
* **CREDIT:** Clara adds balance to the account (e.g., refund, adjustments, rewards).
* **PAYMENT:** Outgoing payment, like a credit card bill, a debt, or any other financial obligation
## Transaction Lifecycle
Transactions can have different statuses, which may change throughout the transaction cycle.
* **NOTIFICATION (ON):** Initial transaction record.
* **PRE\_AUTHORIZED (AU):** Issuer confirms funds and card validity.
* **AUTHORIZED (OP):** Reconciled and finalized.
* **REJECTED (RJ):** Failed or canceled transaction.
* **SYSTEM\_TRANSACTION (EC):** Special status for FEE, PAYMENT, or CREDIT.
## Pagination Details
Each page shows up to 100 transactions, with support for filters and sorting to tailor responses.
```curl cURL theme={null}
curl -X GET
"https://public-api.mx.clara.com/api/v3/transaction?size=1" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```
```curl JSON theme={null}
{
"transactionUuid": "47f8ed9e-4d7b-450b-ad6a-f1d83e3ce4e1",
"invoices": [
{
"invoiceId": "54cd6b23-5146-437f-b133-879c432e6776",
"invoiceNumber": null,
"taxRegime": "621",
"issuer": {
"rfc": "CLARA123XML",
"businessName": "CLARA"
},
"taxReceipts": {
"cfdi": "G03",
"paymentMethod": "Q4"
},
"tax": {
"retained": {
"isr": 0.75,
"iva": null,
"ieps": null
},
"transferred": {
"iva": 0.0,
"ieps": 0.0
}
},
"amount": {
"total": 400.00,
"subTotal": 300.00,
"currency": "MXN"
},
"documentDate": "2024-10-01",
"xmlStatus": "Vigente",
"xmlCode": "S β Comprobante obtenido satisfactoriamente."
}
]
}
```
## How to Retrieve Attachments
As a platform, Clara provides its clients with the ability to attach files to transactions, such as receipts, invoices, or other relevant information that can assist in their reconciliation process. To facilitate this, we provide download links for these attachments.
If a transaction has attachments:
* The `hasAttachments` field is set to `true`
* You'll receive a\*\* link to download them\*\*
* URLs are valid for **12 hours**
Format: `.../v3/transactions/{uuid}/documents`
In the following example, we will get the URLs for the transaction with the UUID "47f8ed9e-4d7b-450b-ad6a-f1d83e3ce4e1" in Mexico.
```curl cURL theme={null}
curl -X GET
"https://public-api.mx.clara.com/api/v3/transactions/47f8ed9e-4d7b-450b-ad6a-f1d83e3ce4e1/documents" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```
```curl JSON theme={null}
{
"transactionUuid": "47f8ed9e-4d7b-450b-ad6a-f1d83e3ce4e1",
"attachments": [
{
"uuid": "18589896-d30e-4cca-a4e6-716ba323b937",
"fileName": "receipt.jpg",
"updateAt": "2024-12-09T01:35:26.426484Z",
"format": "jpeg",
"download": {
"urlExpiration": "2024-12-14T07:40:15.144358891Z",
"url": "https://company-9fefb4f5-491d-4028-8c4d-f7b20ff98e29.s3.amazonaws.com/user_docs/1dbf684e-4cdd-467d-b240-3e8e45d63887/51/5465258?response-content-disposition=attachment%3B%20filename%3D%22oneOoneHuixquilucan_241208193512.jpg%22&response-content-type=jpeg&X-Amz-Security-Token=FwoGZXIvYXdzEDUaDJAr429nJB6KRbni%2FiKwAbLEsGgPIsSE8kV0DdR905%2FXd4wYq9zQ2P99MHz06fykkTuaylb7xbpkANXyqQpTJw2M23Q%2FabFuakuazkVDPCQ%2BHwDM3LmJ%2BqWhng87m1q6p6JlacCyMqlQbVtpwYFcts1hMjSXASha79Cs%2FLm9onR2txbq6rTn5%2BW0vtKFk%2FyD7x%2FhGhfmMuZyUgD37dp7FSzUo0Z4ZjLhHjrc6tt%2F2f2C15sN1ps9tCtoyyCiKJ2b8roGMi0W6DxWRVjX7xCGyIT07lfVCMnw9v1MsbpscZ5%2BORVmaTq9CfU3kezypy%2B0M%3D&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20241213T194014Z&X-Amz-SignedHeaders=host&X-Amz-Expires=43199&X-Amz-Credential=ASIASUFA8KD3C1GJLWK%2F20241213%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=3038ebf880b3cd0a0e8b24a0440f047e52ec1f4c1b88f210c637928747a688cc"
}
}
]
}
```
## Invoice Info (Mexico Only)
Clara also provides a space to upload invoice XML files, available only in Mexico.
If a transaction has invoice:
* The `hasInvoice` field is set to `true`
* You'll receive a **link to download them**
* URLs are valid for **12 hours**
Format: `.../v3/transactions/{uuid}/invoices`
In the following example, we will get the invoice information for the transaction with the UUID "47f8ed9e-4d7b-450b-ad6a-f1d83e3ce4e1" in Mexico.
```curl cURL theme={null}
curl -X GET
"https://public-api.mx.clara.com/api/v3/transactions/47f8ed9e-4d7b-450b-ad6a-f1d83e3ce4e1/invoices" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```
```curl JSON theme={null}
{
"transactionUuid": "47f8ed9e-4d7b-450b-ad6a-f1d83e3ce4e1",
"invoices": [
{
"invoiceId": "54cd6b23-5146-437f-b133-879c432e6776",
"invoiceNumber": null,
"taxRegime": "621",
"issuer": {
"rfc": "CLARA123XML",
"businessName": "CLARA"
},
"taxReceipts": {
"cfdi": "G03",
"paymentMethod": "Q4"
},
"tax": {
"retained": {
"isr": 0.75,
"iva": null,
"ieps": null
},
"transferred": {
"iva": 0.0,
"ieps": 0.0
}
},
"amount": {
"total": 400.00,
"subTotal": 300.00,
"currency": "MXN"
},
"documentDate": "2024-10-01",
"xmlStatus": "Vigente",
"xmlCode": "S β Comprobante obtenido satisfactoriamente."
}
]
}
```
Note: The examples provided do not contain real data, and they do not reflect actual calculations for fees, taxes, or any other financial details.
## How to Retrieve Extracted Documents
Use `GET /api/v3/transactions/{uuid}/extracted-documents` to get structured, validated documents like XML invoices or receipts.
## Authentication:
* Use MTLS for secure two-way certificate validation.
* Include a valid OAuth2 token, via the `/oauth/token` endpoint.
* Include the Bearer token in the `Authorization` header of your request.
## Endpoint:
```curl Text theme={null}
GET
"/api/v3/transactions/{uuid}/extracted-documents"
```
Base URL examples:
* `https://public-api.mx.clara.com`
* `https://public-api.br.clara.com`
* `https://public-api.co.clara.com`
## Path Parameter:
| Name | | Type | Required | Description |
| ---- | :- | ------ | -------- | ----------------------- |
| uuid | | string | β
Yes | UUID of the transaction |
## Query Parameters:
| Name | Type | Description |
| ---------------- | ------- | -------------------------------------------------------------------------------------- |
| page | integer | Page index, zero-based. Default: 0 |
| size | integer | Items per page. Default: 20 |
| uuid | uuid | Filter by extracted document UUID |
| type | enum | Filter by document type: `MEXICAN_FISCAL_INVOICE`, `INVOICE`, `RECEIPT`, `OTHER` |
| validationStatus | enum | Filter by validation status: `VALIDATED_BY_CLARA`, `VALIDATED_BY_USER`, `NOT_VERIFIED` |
## Response:
Returns a paginated list of extracted documents associated with the transaction. Each document includes metadata and content such as:
```curl JSON theme={null}
{
"uuid": "123e4567-e89b-12d3-a456-426614174000",
"type": "INVOICE",
"userUuid": "cd22be0b-c074-41d3-8645-77e1507c8562",
"data": {
"folioFiscalUuid": "123e4567-e89b-12d3-a456-426614174000",
"invoiceId": "INV-2023-001",
"receiptDate": "2023-10-15",
"issueDate": "2023-10-15",
"billingDate": "2023-10-31",
"country": "MX",
"issuer": {
"legalName": "ACME Corporation",
"taxIdentifier": "ABC123456XYZ"
},
"items": [
{
"name": "Office Chair",
"unitPrice": 149.99,
"quantity": 2,
"total": 299.98
}
],
"itemsDescription": "Office supplies",
"amount": {
"currency": "USD",
"subTotal": 100.0,
"taxesAmount": 16.0,
"tipAmount": 10.0,
"total": 126.0,
"taxPercentage": 16.0,
"tipPercentage": 10.0
}
},
"fileValidation": {
"status": "VALIDATED_BY_CLARA",
"date": "2023-10-15T14:30:00",
"user": "John Doe",
"userUuid": "123e4567-e89b-12d3-a456-426614174000"
}
}
```
## Validation Status Details
| Status | Description |
| -------------------- | ------------------------------------ |
| VALIDATED\_BY\_CLARA | Automatically validated successfully |
| VALIDATED\_BY\_USER | Validated manually by a user |
| NOT\_VERIFIED | Document could not be validated |
## Successful Response
| Status | Meaning |
| ------ | ----------------------------------------- |
| 200 | OK - List of extracted documents returned |
## Error Responses
| Status | Meaning |
| ------ | ------------ |
| 400 | Bad Request |
| 401 | Unauthorized |
| 403 | Forbidden |
***
## Example cURL Request
```bash theme={null}
curl --location --request GET 'https://public-api.mx.clara.com/api/v3/transactions/{uuid}/extracted-documents' \
--header 'Authorization: Bearer {your_access_token}' \
--cert {client_cert_path} \
--key {client_key_path}
```
Replace `{uuid}`, `{your_access_token}`, `{client_cert_path}`, and `{client_key_path}` with actual values.
## Summary
This endpoint enables retrieval of structured, validated financial documents (invoices, receipts, etc.) tied to a transaction. It supports robust filtering and pagination, and enforces secure access through MTLS and OAuth2.
***
## Endpoint Reference
### `GET /api/v3/transactions`
List all transactions (v3)
**Parameters:**
| Parameter | In | Type | Required | Description |
| -------------------------- | ----- | ------------- | -------- | ----------------------------------------- |
| `page` | query | integer | | Page index, zero-based. Default: `0` |
| `size` | query | integer | | Items per page. Default: `20`, max: `100` |
| `lastUpdateDateRangeStart` | query | string (date) | | Filter by last update date start |
| `lastUpdateDateRangeEnd` | query | string (date) | | Filter by last update date end |
| `operationDateRangeStart` | query | string (date) | | Filter by operation date start |
| `operationDateRangeEnd` | query | string (date) | | Filter by operation date end |
| `accountingDateRangeStart` | query | string (date) | | Filter by accounting date start |
| `accountingDateRangeEnd` | query | string (date) | | Filter by accounting date end |
| `userUuid` | query | string (uuid) | | Filter by user UUID |
| `cardUuid` | query | string (uuid) | | Filter by card UUID |
| `cardLastDigits` | query | string | | Filter by last 4 digits of card |
| `userErpId` | query | string | | Filter by user ERP ID |
| `status` | query | string | | Filter by transaction status |
| `operationTypeCode` | query | string | | Filter by operation type code |
**Response Schema (`TransactionPageV3`):**
| Field | Type | Example |
| --------------- | ------------------------------ | ------- |
| `content` | array of TransactionResponseV3 | |
| `totalElements` | integer | `150` |
| `totalPages` | integer | `8` |
| `size` | integer | `20` |
| `number` | integer | `0` |
### `GET /api/v3/transactions/{uuid}`
Get transaction by UUID (v3)
**Parameters:**
| Parameter | In | Type | Required | Description |
| --------- | ---- | ------------- | -------- | ----------- |
| `uuid` | path | string (uuid) | β
| |
**Response Schema (`TransactionResponseV3`):**
| Field | Type | Example |
| ----------------------- | --------------------------------------- | -------------------------------------- |
| `uuid` | string (uuid) | `4ea5a94a-2c3c-4601-b623-c30260c21dbc` |
| `type` | string | `PURCHASE` |
| `transactionLabel` | string | `OPENAI SUBSCR` |
| `labels` | array of TransactionLabel | |
| `status` | string | `AUTHORIZED` |
| `comment` | string | `Tool to improve` |
| `billingStatement` | object (BillingStatementTransactionRef) | |
| `accountingFields` | array of AccountingFields | |
| `audit` | object (Audit) | |
| `merchant` | object (Merchant) | |
| `card` | object (TransactionCard) | |
| `user` | object (TransactionUser) | |
| `authorizationNumber` | string | `001921` |
| `originalAmount` | object (CurrencyAmount) | |
| `amountValue` | object (CurrencyAmount) | |
| `validationStatus` | object (ValidationStatus) | |
| `hasInvoice` | object (Has) | |
| `hasAttachments` | object (Has) | |
| `hasExtractedDocuments` | object (Has) | |
| `installment` | string | `None` |
| `installmentNumber` | string | `None` |
| `bankConcept` | object (BankConcept) | |
| `links` | array of Link | |
### `POST /api/v3/transactions/{uuid}/comment`
Add a comment to a transaction.
**Parameters:**
| Parameter | In | Type | Required | Description |
| --------- | ---- | ------------- | -------- | ----------- |
| `uuid` | path | string (uuid) | β
| |
**Request Body:**
| Field | Type | Required | Description |
| --------- | ------ | -------- | ------------ |
| `comment` | string | β
| Comment text |
**Response (`201`):**
```json theme={null}
{
"comment": "Expense approved by finance",
"transactionsUuids": ["8108ed5a-3de7-479e-8431-b5824db5044d"]
}
```
### `DELETE /api/v3/transactions/{uuid}/comment`
Remove the comment from a transaction. Returns `204 No Content`.
**Parameters:**
| Parameter | In | Type | Required | Description |
| --------- | ---- | ------------- | -------- | ----------- |
| `uuid` | path | string (uuid) | β
| |
### `GET /api/v3/transactions/{uuid}/invoices`
Get transaction invoices (Mexico fiscal)
**Parameters:**
| Parameter | In | Type | Required | Description |
| --------- | ---- | ------------- | -------- | ----------- |
| `uuid` | path | string (uuid) | β
| |
**Response Schema (`TransactionInvoiceResponse`):**
| Field | Type | Example |
| --------------- | ------------------ | ------- |
| `content` | array of InvoiceV3 | |
| `totalElements` | integer | |
| `totalPages` | integer | |
| `size` | integer | |
| `number` | integer | |
### `POST /api/v3/transactions/comments/bulk`
Bulk add comments to multiple transactions in a single request.
**Request Body:**
| Field | Type | Description |
| -------------- | ----- | ----------------------------------------------------------------------- |
| `transactions` | array | Each item must include `uuid` (transaction UUID) and `comment` (string) |
**Example:**
```json theme={null}
{
"transactions": [
{ "uuid": "4ea5a94a-2c3c-4601-b623-c30260c21dbc", "comment": "Approved" },
{ "uuid": "8108ed5a-3de7-479e-8431-b5824db5044d", "comment": "Pending review" }
]
}
```
### `POST /api/v3/transactions/labels/bulk`
Bulk bind labels to multiple transactions in a single request.
**Request Body:**
| Field | Type | Description |
| -------------- | ----- | ---------------------------------------------------------------------------------------- |
| `transactions` | array | Each item must include `uuid` (transaction UUID) and `labelsUuid` (array of label UUIDs) |
**Example:**
```json theme={null}
{
"transactions": [
{
"uuid": "4ea5a94a-2c3c-4601-b623-c30260c21dbc",
"labelsUuid": ["0169fe8b-b5e1-46f0-895d-a79d2753fee1"]
}
]
}
```
### `GET /api/v3/transactions/{uuid}/documents`
Get transaction documents (v3)
**Parameters:**
| Parameter | In | Type | Required | Description |
| --------- | ---- | ------------- | -------- | ----------- |
| `uuid` | path | string (uuid) | β
| |
**Response Schema (`AttachmentDocuments`):**
| Field | Type | Example |
| ------------- | ----------------------- | ------- |
| `uuid` | string (uuid) | |
| `attachments` | array of AttachmentItem | |
### `GET /api/v3/transactions/{uuid}/extracted-documents`
Get extracted documents for transaction (v3)
**Parameters:**
| Parameter | In | Type | Required | Description |
| ------------------ | ----- | ------------------------------------------------------------- | -------- | --------------------------- |
| `uuid` | path | string (uuid) | β
| |
| `documentUuid` | query | string (uuid) | | Filter by document UUID |
| `type` | query | string | | Filter by document type |
| `validationStatus` | query | enum: `VALIDATED_BY_CLARA`/`VALIDATED_BY_USER`/`NOT_VERIFIED` | | Filter by validation status |
**Response Schema (`ExtractedDocumentPage`):**
| Field | Type | Example |
| --------------- | -------------------------- | ------- |
| `content` | array of ExtractedDocument | |
| `totalElements` | integer | |
| `totalPages` | integer | |
| `size` | integer | |
| `number` | integer | |
## What is the Transactions API?
The **Transactions API (v2)** allows you to programmatically access expense data made with Clara cards. This includes both **physical** and **virtual card transactions**, with detailed metadata such as amount, currency, merchant, category, and status.
You can use this API to:
* Build automated reporting dashboards
* Analyze spend by user, team, or category
* Monitor transaction activity in near real-time
## Available Endpoints
| Operation | Endpoint | Method |
| ------------------------- | ------------------------- | ------ |
| Retrieve all transactions | `/v2/transactions` | GET |
| Get transaction by UUID | `/v2/transactions/{uuid}` | GET |
## Retrieve all transactions
Fetch a list of all transactions for your company. You can apply optional filters such as `status`, `userUuid`, or `date range`.
### Endpoint
`GET /v2/transactions`
### cURL Request
```curl cURL theme={null}
curl -X GET \
"https://public-api.mx.clara.com/api/v2/transactions" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```
π‘ You can add filters as query parameters, for example: `/v2/transactions?status=APPROVED&userUuid=abc-123`
### Sample JSON Response
```json JSON theme={null}
[
{
"uuid": "txn-123",
"amount": 580.00,
"currency": "MXN",
"status": "APPROVED",
"merchant": "Amazon",
"userUuid": "user-456",
"category": "Office Supplies",
"createdAt": "2024-06-10T15:30:00Z"
},
{
"uuid": "txn-124",
"amount": 1200.00,
"currency": "MXN",
"status": "PENDING",
"merchant": "Uber",
"userUuid": "user-789",
"category": "Transportation",
"createdAt": "2024-06-11T09:00:00Z"
}
]
```
## Retrieve Transaction by UUID
Fetch full details for a single transaction using its unique identifier.
### Endpoint
`GET /v2/transactions/{uuid}`
### cURL Request
```curl cURL theme={null}
curl -X GET \
"https://public-api.mx.clara.com/api/v2/transactions/txn-123" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```
### Sample JSON Response
```json JSON theme={null}
{
"uuid": "txn-123",
"amount": 580.00,
"currency": "MXN",
"status": "APPROVED",
"merchant": "Amazon",
"category": "Office Supplies",
"description": "Team supplies",
"user": {
"uuid": "user-456",
"fullName": "Ana GΓ³mez"
},
"card": {
"uuid": "card-789",
"lastFour": "4321",
"type": "virtual"
},
"createdAt": "2024-06-10T15:30:00Z"
}
```
\*\*π‘ Tip: \*\* Use the transaction status field to filter transactions by lifecycle stage (e.g. PENDING, APPROVED, DECLINED, etc.).
**β οΈ Note:** Some fields like description, category, or user may be updated after the transaction is first created, depending on reconciliation and review processes.
***
## Endpoint Reference
### `GET /api/v2/transactions`
List all transactions (v2)
**Parameters:**
| Parameter | In | Type | Required | Description |
| -------------------------- | ----- | ------------- | -------- | -------------------------------- |
| `lastUpdateDateRangeStart` | query | string (date) | | Filter by last update date start |
| `lastUpdateDateRangeEnd` | query | string (date) | | Filter by last update date end |
| `operationDateRangeStart` | query | string (date) | | Filter by operation date start |
| `operationDateRangeEnd` | query | string (date) | | Filter by operation date end |
| `accountingDateRangeStart` | query | string (date) | | Filter by accounting date start |
| `accountingDateRangeEnd` | query | string (date) | | Filter by accounting date end |
| `userUuid` | query | string (uuid) | | Filter by user UUID |
| `cardUuid` | query | string (uuid) | | Filter by card UUID |
| `cardLastDigits` | query | string | | Filter by last 4 digits of card |
| `userErpId` | query | string | | Filter by user ERP ID |
| `status` | query | string | | Filter by transaction status |
| `operationTypeCode` | query | string | | Filter by operation type code |
**Response Schema (`TransactionPageV3`):**
| Field | Type | Example |
| --------------- | ------------------------------ | ------- |
| `content` | array of TransactionResponseV3 | |
| `totalElements` | integer | `150` |
| `totalPages` | integer | `8` |
| `size` | integer | `20` |
| `number` | integer | `0` |
### `GET /api/v2/transactions/{uuid}`
Get transaction by UUID (v2)
**Parameters:**
| Parameter | In | Type | Required | Description |
| --------- | ---- | ------------- | -------- | ----------- |
| `uuid` | path | string (uuid) | β
| |
**Response Schema (`TransactionResponseV3`):**
| Field | Type | Example |
| ----------------------- | --------------------------------------- | -------------------------------------- |
| `uuid` | string (uuid) | `4ea5a94a-2c3c-4601-b623-c30260c21dbc` |
| `type` | string | `PURCHASE` |
| `transactionLabel` | string | `OPENAI SUBSCR` |
| `labels` | array of TransactionLabel | |
| `status` | object (TransactionStatus) | |
| `comment` | string | `Tool to improve` |
| `billingStatement` | object (BillingStatementTransactionRef) | |
| `accountingFields` | array of AccountingFields | |
| `audit` | object (Audit) | |
| `merchant` | object (Merchant) | |
| `card` | object (TransactionCard) | |
| `user` | object (TransactionUser) | |
| `authorizationNumber` | string | `001921` |
| `originalAmount` | object (CurrencyAmount) | |
| `amountValue` | object (CurrencyAmount) | |
| `validationStatus` | object (ValidationStatus) | |
| `hasInvoice` | object (Has) | |
| `hasAttachments` | object (Has) | |
| `hasExtractedDocuments` | object (Has) | |
| `installment` | string | `None` |
| `installmentNumber` | string | `None` |
| `bankConcept` | object (BankConcept) | |
v1 is legacy and read-only. Migrate to v3 for full transaction access.
## What is the Transactions API?
The **Transactions API v1** allows you to retrieve expense data generated by Clara cards within your organization. Each transaction includes metadata such as amount, currency, date, merchant, and the associated user and card.
This version is **read-only**, ideal for use cases like:
* Expense reconciliation
* Transaction history visualization
* Internal reporting and dashboards
π Note: For enhanced filtering or expanded metadata, consider using [Transactions API v2](#).
## Available Endpoints
| Operation | Endpoint | Method |
| ------------------------ | ------------------------- | ------ |
| Find all transactions | `/v1/transactions` | GET |
| Find transaction by UUID | `/v1/transactions/{uuid}` | GET |
## Find all transactions
Use this endpoint to **fetch a list of all transactions**. The response is paginated and includes key information about each transaction such as amount, status, category, and user.
### Endpoint
`GET /v1/transactions`
### cURL Request
```curl cURL theme={null}
curl -X GET \
"https://public-api.mx.clara.com/api/v1/transactions" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```
### Sample JSON Response
```json JSON theme={null}
[
[
{
"uuid": "txn-001",
"amount": 1250.50,
"currency": "MXN",
"status": "APPROVED",
"merchant": "Amazon",
"category": "Office Supplies",
"userUuid": "user-001",
"cardUuid": "card-001",
"createdAt": "2025-06-15T12:30:00Z"
}
]
```
## Find transaction by UUID
Use this endpoint to get full details of a specific transaction by its UUID. This is useful for audit views, drill-downs in dashboards, or reconciliation workflows.
### Endpoint
`GET /v1/transactions/{uuid}`
### cURL Request
```curl cURL theme={null}
curl -X GET \
"https://public-api.mx.clara.com/api/v1/transactions/txn-001" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```
### Sample JSON Response
```json JSON theme={null}
{
"uuid": "txn-001",
"amount": 1250.50,
"currency": "MXN",
"status": "APPROVED",
"merchant": "Amazon",
"category": "Office Supplies",
"description": "Purchase of printer toner",
"userUuid": "user-001",
"cardUuid": "card-001",
"createdAt": "2025-06-15T12:30:00Z"
}
```
**π‘ Tip:** Use the userUuid and cardUuid fields to join transaction data with user and card profiles for enriched analysis.
**β οΈ Note:** This API is paginated. Make sure to handle pagination parameters when retrieving large datasets.
***
## Endpoint Reference
### `GET /api/v1/transactions`
Find all transactions
**Parameters:**
| Parameter | In | Type | Required | Description |
| ----------------------------- | ----- | -------------------------------------------------- | -------- | --------------------------------------------------------------------------------------- |
| `page` | query | integer | | Zero-based page index (0..N) |
| `size` | query | integer | | The size of the page to be returned |
| `operationDateRangeStart` | query | string | | Operation start date |
| `operationDateRangeEnd` | query | string | | Operation max date |
| `accountingDateRangeStart` | query | string | | Accounting start date |
| `accountingDateRangeEnd` | query | string | | Accounting max date |
| `userUuid` | query | string | | UUID of the user associated with the transactions |
| `cardUuid` | query | string | | UUID of the card associated with the transactions |
| `merchantCategoryDescription` | query | string | | Merchant category of the transactions |
| `operationTypeCode` | query | enum: `PURCHASE`/`REFUND`/`FEE`/`CREDIT`/`PAYMENT` | | Operation status. Values include 'AU' for Pending and 'OP' for Authorized transactions. |
### `GET /api/v1/transactions/{uuid}`
Find transaction by UUID
**Parameters:**
| Parameter | In | Type | Required | Description |
| --------- | ---- | ------ | -------- | ---------------- |
| `uuid` | path | string | β
| Transaction UUID |
# Users
Source: https://developers.clara.team/api-reference/users
Create, update, retrieve, and delete users in a company account.
Recommended for all new integrations.
## What is the Users API?
Version 3 of Clara's Users API lets you manage user accounts securely, with support for:
* Role and location handling
* Advance filtering through query parameters
* User lifecycle operations support (onboarding, status tracking, updating, and deletion)
All operations are secured via Mutual TLS and OAuth 2 authentication protocols.
## Authentication
To use the API:
1. Obtain your client certificate and credentials via the Clara platform.
2. Request an access token via `POST /oauth/token` with your `client_id` and `client_secret`.
3. Use the access token in the `Authorization` header for all subsequent API requests.
## Core Use Cases
### **List Users**
Retrieve a list of users with optional filters like status, role, or name.
* \*\*`GET /api/v3/users` \*\*- with filters for status, role, name.
* **Successful Response HTTP Status:**
`200 OK` : List of users successfully returned
* **Query Parameters:**
| Parameter | Type | Default | Example | Description |
| ---------------- | ------- | ------- | ------------------------------------------------- | -------------------------------------------------------------- |
| `page` | integer | 0 | | Zero-based page index (default: 0) |
| `size` | integer | 50 | | Number of users per page (default: 50) |
| `status` | string | | ACTIVE | Filter by user status (e.g., ACTIVE, LOCKED) |
| `role` | string | | EMPLOYEE | Filter by role (EMPLOYEE, MANAGER, COMPANY\_OWNER, BOOKKEEPER) |
| `uuid` | string | | 90a50162-f673-4be0-bfa0-67dc0adde16f | Filter by specific user UUID |
| `name` | string | | John | Filter by first name |
| `lastName` | string | | Cena | Filter by last name |
| `fullName` | string | | John Cena | Filter by full name |
| `email` | string | | [johncena@clara.team](mailto:johncena@clara.team) | Filter by email address |
| `mobilePhone` | string | | 5512345678 | Filter by mobile phone number |
| `taxIdentifier` | string | | DANT120619Z45 | Filter by tax identifier |
| `erpId` | string | | SADSADASDASDAS351345 | Filter by ERP ID |
| `createdAtStart` | string | | 2022-03-28 | Filter users created after this date (YYYY-MM-DD) |
| `createdAtEnd` | string | | 2025-03-28 | Filter users created before this date (YYYY-MM-DD) |
| `locationUuid` | string | | 90a50162-f673-4be0-bfa0-67dc0adde16f | Filter by location UUID |
| `locationName` | string | | Barcelona | Filter by location name |
| `managerUuid` | string | | 90a50162-f673-4be0-bfa0-67dc0adde16f | Filter by manager UUID |
* **Example Request:**
```http theme={null}
GET /api/v3/users?page=0&size=5&status=ACTIVE&role=EMPLOYEE HTTP/1.1
Host: public-api.mx.clara.com
Authorization: Bearer YOUR_ACCESS_TOKEN
```
* **Example Response:**
```json theme={null}
{
"totalElements": 1,
"content": [
{
"uuid": "a0c82a20-ac09-4cfd-b429-d0623585911e",
"fullName": "John Doe",
"name": "John",
"lastName": "Doe",
"email": "johndoe@clara.team",
"mobilePhone": "5512345678",
"taxIdentifier": "DANT120619Z45",
"role": "EMPLOYEE",
"erpId": "SADSADASDASDAS351345",
"status": "ACTIVE",
"createdAt": "2023-10-01T12:00:00",
"location": {
"uuid": "loc-123",
"name": "Barcelona",
"_links": {
"self": {
"href": "https://public-api.mx.clara.com/api/v3/locations/loc-123"
}
}
},
"manager": {
"uuid": "manager-uuid",
"_links": {
"self": {
"href": "https://public-api.mx.clara.com/api/v3/users/manager-uuid"
}
}
},
"_links": {
"self": {
"href": "https://public-api.mx.clara.com/api/v3/users/a0c82a20-ac09-4cfd-b429-d0623585911e"
}
}
}
]
}
```
### **Create User**
* `POST /api/v3/users` - add a new user to your organization.
* **Successful Response HTTP Status:**
`201 Created`: User successfully created
* **Request Body Parameters:**
| Parameter | Type | Required | Description |
| --------------- | ------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `email` | string | β
| User's email address which also serves as their username. This is the primary identifier for the user in the system and is used for login purposes and notifications. It must be unique within the company and is a required field for user creation. |
| `name` | string | β
| User's first name. Used for display purposes throughout the system. This field is used in reports, notifications, and user interfaces. It is a required field for user creation and part of the user's identity in the system. |
| `lastName` | string | β
| User's last name. Used for display purposes throughout the system. This field is used in reports, notifications, and user interfaces. It is a required field for user creation and part of the user's identity in the system. |
| `groups` | string | β | List of group UUIDs that the user will be assigned to. Groups determine the user's access permissions and organizational structure. This field is required for all users except those with the COMPANY\_OWNER role. At least one group must be provided for non-company owner users. |
| `lada` | string | β | User's phone country code (lada). Used for contact information. If not provided, defaults to +52 for Mexico, +55 for Brazil, and +57 for Colombia based on company location. This field is used together with mobilePhone for user notifications and contact purposes. |
| `mobilePhone` | string | β
| User's mobile phone number. Used for contact information and notifications. This is a required field for user creation and is used for sending important notifications to the user. The format should follow the country's phone number standard without the country code. |
| `role` | string | β
| User's role in the system. Determines the user's permissions and access level. This is a required field for user creation and affects the validation of other fields. COMPANY\_OWNER users have special privileges and different validation rules. Common values include EMPLOYEE, MANAGER, COMPANY\_OWNER, and BOOKKEEPER. |
| `managerUuid` | string | β | UUID of the user's direct manager or supervisor. Used to establish the organizational hierarchy and reporting structure. This field is optional but recommended for proper organizational structure visualization. It affects approval workflows and reporting relationships in the system. |
| `locationUuid` | string | β | UUID of the location where the user is assigned. Associates the user with a specific physical or organizational location in the company. This field is required for all users except those with the COMPANY\_OWNER role. It affects location-based reports, filters, and organizational structure. |
| `erpId` | string | β | User's Enterprise Resource Planning (ERP) identifier. Used to link the user with external ERP systems. This field facilitates integration with other business systems and is optional. If provided, it should match the identifier used in the connected ERP system. |
| `taxIdentifier` | string | β | User's tax identification number. Used for financial and tax-related purposes. This field is required for financial transactions and tax reporting. Updating this field will change the user's tax information in the system. The length must be valid for the country: MX (11 or 13), CO (7, 8, 9, or 10), BR (11). |
| `foreign` | boolean | β | Flag indicating if the user is from a foreign country. Affects how the system handles certain validations and processes for the user. If not provided, defaults to false. This field may impact tax calculations and regulatory compliance. |
* **Example Request:**
```json theme={null}
{
"email": "janedoe@clara.team",
"name": "Jane",
"lastName": "Doe",
"mobilePhone": 5512345678,
"lada": "+52",
"role": "EMPLOYEE",
"groups": ["a0c82a20-ac09-4cfd-b429-d0623585911e"],
"locationUuid": "409e3ccd-4e87-480a-98d5-126c54ff9457",
"managerUuid": "0d761141-6cee-495c-a27e-99875bdce721",
"erpId": "ERP-001",
"taxIdentifier": "RFC123456789",
"foreign": false
}
```
* **Example Response:**
```json theme={null}
{
"uuid": "b1d23c20-bc00-4cfd-b429-d0623585912f"
}
```
### **Retrieve a User by UUID**
* `GET /api/v3/users/{uuid}` - fetch details of a single user using their UUID
* **Successful Response HTTP Status:**
`200 OK`: User successfully retrieved
* **Path Parameter:**
| Parameter | Type | Description |
| --------- | ------ | ---------------- |
| `uuid` | string | UUID of the user |
* **Example Request:**
```http theme={null}
GET /api/v3/users/a0c82a20-ac09-4cfd-b429-d0623585911e HTTP/1.1
Authorization: Bearer YOUR_ACCESS_TOKEN
```
* **Example Response:**
```json theme={null}
{
"uuid": "a0c82a20-ac09-4cfd-b429-d0623585911e",
"fullName": "John Doe",
"name": "John",
"lastName": "Doe",
"email": "johndoe@clara.team",
"mobilePhone": "5512345678",
"taxIdentifier": "RFC987654321",
"role": "EMPLOYEE",
"erpId": "ERP-001",
"status": "ACTIVE",
"createdAt": "2023-10-01T12:00:00",
"groups": [
{
"uuid": "group-123",
"name": "Engineering",
"_links": {
"self": {
"href": "https://public-api.mx.clara.com/api/v3/groups/group-123"
}
}
}
],
"location": {
"uuid": "loc-456",
"name": "Mexico City",
"_links": {
"self": {
"href": "https://public-api.mx.clara.com/api/v3/locations/loc-456"
}
}
},
"cards": [
{
"uuid": "card-001",
"status": "ACTIVE",
"lockCode": "UNLOCKED",
"alias": "Main Card",
"threshold": 1000,
"periodicity": "MONTHLY",
"maskedPan": "514509******5946",
"type": "MASTER_VIRTUAL",
"_links": {
"self": {
"href": "https://public-api.mx.clara.com/api/v3/cards/card-001"
}
}
}
],
"manager": {
"uuid": "manager-uuid-789",
"name": "Jane",
"lastName": "Smith",
"email": "janesmith@clara.team",
"erpId": "ERP-002",
"_links": {
"self": {
"href": "https://public-api.mx.clara.com/api/v3/users/manager-uuid-789"
}
}
},
"_links": {
"self": {
"href": "https://public-api.mx.clara.com/api/v3/users/a0c82a20-ac09-4cfd-b429-d0623585911e"
}
}
}
```
### **Update User**
* `PATCH /api/v3/users/{uuid}` - modify the details of an existing user.
* **Successful Response HTTP Status:**
`200 OK`: User successfully updated
* **Path Parameter:**
| Parameter | Type | Description |
| --------- | ------ | ---------------- |
| `uuid` | string | UUID of the user |
* **Request Body Parameters:**
| Parameter | Type | Description |
| ---------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `email` | string | User's email/username. Serves as the primary identifier for the user in the system. This field is used for login purposes and notifications. Updating this field will change the user's login credentials. |
| `name` | string | User's first name. Used for display purposes throughout the system. This field is used in reports, notifications, and user interfaces. Updating this field will change how the user's name appears in the system. |
| `lastName` | string | User's last name. Used for display purposes throughout the system. This field is used in reports, notifications, and user interfaces. Updating this field will change how the user's name appears in the system. |
| `lada` | string | User's phone country code (lada). Used for contact information. Must be provided together with mobilePhone or not at all. If one is provided without the other, a validation error will occur. Updating this field will change the user's contact information. |
| `mobilePhone` | string | User's mobile phone number. Used for contact information and notifications. Must be provided together with lada or not at all. If one is provided without the other, a validation error will occur. Updating this field will change the user's contact information. |
| `role` | string | User's role. Determines the user's permissions and access level in the system. Changing a user's role may affect their access to certain features and data. This field triggers an update to the user's role in the system. |
| `locationUuid` | string | User's location UUID. Associates the user with a specific location in the company. This field is used to determine the user's physical or organizational location. Updating this field will change where the user appears in location-based reports and filters. |
| `erpId` | string | User's Enterprise Resource Planning (ERP) identifier. Used to link the user with external ERP systems. This field facilitates integration with other business systems. Updating this field will change how the user is identified in integrated ERP systems. |
| `taxIdentifier` | string | User's tax identification number. Used for financial and tax-related purposes. This field is required for financial transactions and tax reporting. Updating this field will change the user's tax information in the system. The length must be valid for the country: MX (11 or 13), CO (7, 8, 9, or 10), BR (11). |
| `managerUuid` | string | User's manager UUID. Identifies the user's direct supervisor or manager in the organizational hierarchy. This field is used for reporting structures and approval workflows. Updating this field will change the user's position in the organizational chart. |
| `groupsToAdd` | string | User's groups UUIDs to add. Specifies which groups the user should be added to. If provided, must contain at least one group UUID. Cannot contain groups that the user is already a member of unless cleanGroups is true. Cannot contain the same group UUIDs as groupsToRemove. At least one group must be provided when cleanGroups is true. After applying all changes, the user must remain in at least one group. |
| `groupsToRemove` | string | User's groups UUIDs to remove. Specifies which groups the user should be removed from. If provided, must contain at least one group UUID. Must only contain groups that the user is currently a member of. Cannot contain the same group UUIDs as groupsToAdd. Should not be provided when cleanGroups is true. After applying all changes, the user must remain in at least one group. |
| `cleanGroups` | boolean | Flag to indicate if all existing groups should be removed before adding new ones. When true, all of the user's current groups will be removed and replaced with the groups specified in groupsToAdd. When true, groupsToRemove should not be provided as it would be redundant. When true, groupsToAdd must contain at least one group to ensure the user remains in at least one group. Defaults to false if not provided. |
* **Example Request:**
#### Group Management Fields
The following fields enhance how a user's group memberships are updated:
* **`groupsToAdd`**: Adds the user to one or more groups. Must not duplicate existing memberships.
* **`groupsToRemove`**: Removes the user from specified groups. Must already be a member of those groups.
* **`cleanGroups`**: If true, removes all existing groups before adding new ones from `groupsToAdd`.
> β οΈ When `cleanGroups` is true, `groupsToAdd` must include at least one group. The user must always remain in at least one group.
```json theme={null}
{
"name": "Johnathan",
"mobilePhone": 5512345679,
"lada": "+52",
"groupsToAdd": [
"a0c82a20-ac09-4cfd-b429-d0623585911e"
],
"groupsToRemove": [
"10c82a20-ac09-4cfd-b429-d0623585912e"
],
"cleanGroups": false
}
```
* **Example Response:**
```json theme={null}
"User updated"
```
### **Delete User**
* `DELETE /api/v3/users/{uuid}` - delete a user using their UUID.
* **Successful Response HTTP Status:**
`204 No Content`: User successfully deleted
* **Path Parameter:**
| Parameter | Type | Description |
| --------- | ------ | ---------------- |
| `uuid` | string | UUID of the user |
* **Example Request:**
```http theme={null}
DELETE /api/v3/users/a0c82a20-ac09-4cfd-b429-d0623585911e HTTP/1.1
Authorization: Bearer YOUR_ACCESS_TOKEN
```
* **Example Response:**
```http theme={null}
204 No Content
```
## User Lifecycle Status
* `ONBOARDING_CANDIDATE`: User has been created but not fully onboarded.
* `WAITING`: User is awaiting some verification or action.
* `DELETED`: User account has been marked for deletion.
* `ACTIVE`: User is active and can use the system.
* `LOCKED`: User account is locked.
* `INACTIVE`: User is not currently active but may be reactivated.
* `PENDING`: User creation is pending.
* `MASTER_LOCKED`: User is locked at the highest permission level.
* `CLARA_BLOCKED`: User is blocked by the system administrator.
## Lifecycle Flow
1. **Creation**: A user is created via the `POST /api/v3/users` endpoint. Initially, they may be in a status such as `ONBOARDING_CANDIDATE` or `PENDING`.
2. **Activation**: After onboarding steps are completed, the user transitions to `ACTIVE`.
3. **Usage**: The user actively participates in the platform's operations.
4. **Locking/Blocking**: If needed, the user may be `LOCKED`, `MASTER_LOCKED`, or `CLARA_BLOCKED` due to policy violations or security issues.
5. **Deactivation**: Users can be set to `INACTIVE` if no longer participating but still retained in the system.
6. **Deletion**: Finally, the user can be marked as `DELETED` via the `DELETE /api/v3/users/{uuid}` endpoint.
***
## Endpoint Reference
### `GET /api/v3/users`
List all users (v3)
**Parameters:**
| Parameter | In | Type | Required | Description |
| ---------------- | ----- | ------------- | -------- | ----------------------------- |
| `status` | query | string | | Filter by user status |
| `role` | query | string | | Filter by user role |
| `uuid` | query | string (uuid) | | Filter by user UUID |
| `name` | query | string | | Filter by first name |
| `lastName` | query | string | | Filter by last name |
| `fullName` | query | string | | Filter by full name |
| `email` | query | string | | Filter by email |
| `mobilePhone` | query | string | | Filter by mobile phone |
| `taxIdentifier` | query | string | | Filter by tax ID |
| `erpId` | query | string | | Filter by ERP ID |
| `createdAtStart` | query | string (date) | | Filter by creation date start |
| `createdAtEnd` | query | string (date) | | Filter by creation date end |
| `locationUuid` | query | string (uuid) | | Filter by location UUID |
| `locationName` | query | string | | Filter by location name |
| `managerUuid` | query | string (uuid) | | Filter by manager UUID |
**Response Schema (`UserPageV3`):**
| Field | Type | Example |
| --------------- | ------------------- | ------- |
| `content` | array of UserItemV3 | |
| `totalElements` | integer | |
| `totalPages` | integer | |
| `size` | integer | |
| `number` | integer | |
### `POST /api/v3/users`
Create user (v3)
**Request Body (`CreateUserRequestV3`):**
| Field | Type | Example |
| --------------- | ----------------- | -------------------------------------- |
| `email` | string (email) | `johndoe@clara.team` |
| `name` | string | `John` |
| `lastName` | string | `Doe` |
| `groups` | array of string | |
| `lada` | string | `+52` |
| `mobilePhone` | string | `5512345678` |
| `role` | object (UserRole) | |
| `managerUuid` | string (uuid) | `0d761141-6cee-495c-a27e-99875bdce721` |
| `locationUuid` | string (uuid) | `409e3ccd-4e87-480a-98d5-126c54ff9457` |
| `erpId` | string | `SADSADASDASDAS351345` |
| `taxIdentifier` | string | `DANT120619Z45` |
### `GET /api/v3/users/{uuid}`
Get user by UUID (v3)
**Parameters:**
| Parameter | In | Type | Required | Description |
| --------- | ---- | ------------- | -------- | ----------- |
| `uuid` | path | string (uuid) | β
| |
**Response Schema (`UserV3`):**
| Field | Type | Example |
| --------------- | ------------------- | -------------------------------------- |
| `uuid` | string (uuid) | `a0c82a20-ac09-4cfd-b429-d0623585911e` |
| `fullName` | string | `John Doe` |
| `lastName` | string | `Doe` |
| `name` | string | `John` |
| `email` | string (email) | `johndoe@clara.team` |
| `mobilePhone` | string | `5512345678` |
| `taxIdentifier` | string | `DANT120619Z45` |
| `role` | object (UserRole) | |
| `erpId` | string | `SADSADASDASDAS351345` |
| `status` | object (UserStatus) | |
| `createdAt` | string (date-time) | `2023-10-01T12:00:00` |
| `groups` | array of GroupV2 | |
| `cards` | array of UserCardV2 | |
| `manager` | object (BasicUser) | |
| `location` | object (LocationV2) | |
### `PATCH /api/v3/users/{uuid}`
Update user (v3)
**Parameters:**
| Parameter | In | Type | Required | Description |
| --------- | ---- | ------------- | -------- | ----------- |
| `uuid` | path | string (uuid) | β
| |
**Request Body (`UpdateUserRequestV3`):**
| Field | Type | Example |
| ---------------- | ----------------- | -------------------------------------- |
| `email` | string (email) | `johndoe@clara.team` |
| `name` | string | `John` |
| `lastName` | string | `Doe` |
| `lada` | string | `+52` |
| `mobilePhone` | string | `5512345678` |
| `role` | object (UserRole) | |
| `locationUuid` | string (uuid) | `409e3ccd-4e87-480a-98d5-126c54ff9457` |
| `erpId` | string | `SADSADASDASDAS351345` |
| `taxIdentifier` | string | `DANT120619Z45` |
| `managerUuid` | string (uuid) | `0d761141-6cee-495c-a27e-99875bdce721` |
| `groupsToAdd` | array of string | |
| `groupsToRemove` | array of string | |
| `cleanGroups` | boolean | |
### `DELETE /api/v3/users/{uuid}`
Delete user (v3)
**Parameters:**
| Parameter | In | Type | Required | Description |
| --------- | ---- | ------------- | -------- | ----------- |
| `uuid` | path | string (uuid) | β
| |
## What is the Users API?
The **Users API (v2)** allows you to programmatically manage users within your Clara organization. You can create users, list all users, and retrieve detailed information about any user by UUID.
This API is commonly used to:
* Onboard new employees into the platform
* Synchronize users from an external HR system
* Manage user metadata such as job title, department, or phone number
* Prepare users to receive cards, assign roles, or link them to approval workflows
*
## Available Endpoints
| Operation | Endpoint | Method |
| ------------------ | ------------------ | ------ |
| Retrieve all users | `/v2/users` | GET |
| Create a new user | `/v2/users` | POST |
| Get user by UUID | `/v2/users/{uuid}` | GET |
## Retrieve All Users
Fetch a complete list of users registered in your organization.
### Endpoint
`GET /v2/users`
### cURL Request
```curl cURL theme={null}
curl -X GET \
"https://public-api.mx.clara.com/api/v2/users" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```
### Sample JSON Response
```json JSON theme={null}
[
{
"uuid": "3b3123e7-d7b4-4c92-a3b6-57e9f7aafadb",
"email": "john.doe@company.com",
"fullName": "John Doe",
"status": "ACTIVE",
"role": "EMPLOYEE"
}
]
```
## Retrieve All Users
Register a new user with name, email, and optional details like job title, phone number, or department. The new user can later be assigned roles and permissions.
### Endpoint
`POST /v2/users`
### cURL Request
```curl cURL theme={null}
curl -X POST \
"https://public-api.mx.clara.com/api/v2/users" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"fullName": "Jane Smith",
"email": "jane.smith@company.com",
"phoneNumber": "+5215512345678",
"jobTitle": "Operations Manager",
"department": "Operations"
}'
```
### Sample JSON Response
```json JSON theme={null}
{
"uuid": "9d8122e5-4173-497a-9015-f4f2d9482c1a",
"email": "jane.smith@company.com",
"fullName": "Jane Smith",
"status": "PENDING_INVITATION"
}
```
## Retrieve All Users
Fetch detailed information about a specific user using their UUID.
### Endpoint
`GET /v2/users/{uuid}`
### cURL Request
```curl cURL theme={null}
curl -X GET \
"https://public-api.mx.clara.com/api/v2/users/9d8122e5-4173-497a-9015-f4f2d9482c1a" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```
### Sample JSON Response
```json JSON theme={null}
{
"uuid": "9d8122e5-4173-497a-9015-f4f2d9482c1a",
"email": "jane.smith@company.com",
"fullName": "Jane Smith",
"status": "ACTIVE",
"jobTitle": "Operations Manager",
"department": "Operations",
"createdAt": "2024-06-15T12:45:00Z"
}
```
π‘\*\* Tip:\*\* After creating a user, you can assign roles and issue cards programmatically using the Roles and Cards APIs.
β οΈ **Note:** Users with PENDING\_INVITATION status must complete onboarding via the invitation email before accessing Clara's platform.
***
## Endpoint Reference
### `GET /api/v2/users`
List all users (v2)
### `POST /api/v2/users`
Create user (v2)
**Request Body (`CreateUserRequestV2`):**
| Field | Type | Example |
| ------------------ | ------ | ------- |
| `createUserParams` | object | |
### `GET /api/v2/users/{uuid}`
Get user by UUID (v2)
**Parameters:**
| Parameter | In | Type | Required | Description |
| --------- | ---- | ------------- | -------- | ----------- |
| `uuid` | path | string (uuid) | β
| |
**Response Schema (`UserV2`):**
| Field | Type | Example |
| --------------- | ------------------- | ------------------------------------------------- |
| `uuid` | string (uuid) | `1f2e3a4c-5d67-89a0-ba1c-2b3d4b567801` |
| `userFullName` | string | `Manuela Sanchez` |
| `username` | string | `muela.g+3@clara.team` |
| `role` | string (enum) | `EMPLOYEE`/`MANAGER`/`COMPANY_OWNER`/`BOOKKEEPER` |
| `taxIdentifier` | string | `BRZ0000002102` |
| `erpId` | string | `103892` |
| `status` | object (CardStatus) | |
| `location` | object (LocationV2) | |
| `cards` | array of UserCardV2 | |
| `manager` | object (BasicUser) | |
| `groups` | array of GroupV2 | |
v1 is legacy and read-only. Migrate to v3 for full user management.
## What is the Users API?
The **Users API v1** provides read-only access to user profiles registered in your Clara organization. It allows external systems to retrieve user information such as names, emails, roles, and statuses.
This version is ideal for integrations that require:
* Listing users for mapping or sync purposes
* Displaying user names or emails in custom dashboards
* Linking other entities (transactions, cards, policies) with user metadata
π Note: This is a **read-only** API. For user creation and updates, use [Users API v2](#).
## Available Endpoints
| Operation | Endpoint | Method |
| ---------------- | ------------------ | ------ |
| List all users | `/v1/users` | GET |
| Get user by UUID | `/v1/users/{uuid}` | GET |
## List all users
Use this endpoint to **retrieve a list of all users** in your organization. The response includes basic information for each user such as name, email, and status.
### Endpoint
`GET /v1/users`
### cURL Request
```curl cURL theme={null}
curl -X GET \
"https://public-api.mx.clara.com/api/v1/users" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```
### Sample JSON Response
```json JSON theme={null}
[
{
"uuid": "user-123",
"fullName": "Ana GΓ³mez",
"email": "ana.gomez@empresa.com",
"status": "ACTIVE",
"role": "EMPLOYEE"
},
{
"uuid": "user-456",
"fullName": "Luis Torres",
"email": "luis.torres@empresa.com",
"status": "DISABLED",
"role": "ADMIN"
}
]
```
## Find user by UUID
Use this endpoint to retrieve detailed information about a specific user using their unique identifier (uuid).
### Endpoint
`GET /v1/users/{uuid}`
### cURL Request
```curl cURL theme={null}
curl -X GET \
"https://public-api.mx.clara.com/api/v1/users/user-123" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```
### Sample JSON Response
```json JSON theme={null}
{
"uuid": "user-123",
"fullName": "Ana GΓ³mez",
"email": "ana.gomez@empresa.com",
"status": "ACTIVE",
"role": "EMPLOYEE"
}
```
**π‘ Tip:** Combine this API with other entity UUIDs (e.g., transactions or cards) to enrich reporting or audit logs with human-readable user information.
**β οΈ Note:** This API is read-only and does not support creation, update, or deactivation of users.
***
## Endpoint Reference
### `GET /api/v1/users`
Find all users
**Parameters:**
| Parameter | In | Type | Required | Description |
| ------------ | ----- | ------------------------------------------------------------------ | -------- | ----------------------------------- |
| `page` | query | integer | | Zero-based page index (0..N) |
| `size` | query | integer | | The size of the page to be returned |
| `statusName` | query | enum: `ONBOARDING_CANDIDATE`/`WAITING`/`DELETED`/`ACTIVE`/`LOCKED` | | Status of the user |
| `role` | query | enum: `EMPLOYEE`/`MANAGER`/`COMPANY_OWNER`/`BOOKKEEPER` | | Role of the user. |
### `GET /api/v1/users/{uuid}`
Find user by UUID
**Parameters:**
| Parameter | In | Type | Required | Description |
| --------- | ---- | ------ | -------- | ----------- |
| `uuid` | path | string | β
| User UUID |
# Webhooks
Source: https://developers.clara.team/api-reference/webhooks
Subscribe to transaction events via webhooks.
This service is not yet available in v3. Available in **v1** only.
# How WebHooks β Subscribers via Clara API
This guide describes how to manage webhook subscribers using Clara's `/api/v1/subscribers` endpoint, and explains the internal execution and consumption logic via `WebhookConsumerService`.
***
## Authentication Requirements
* Use **mutual TLS (MTLS)** for secure two-way certificate validation.
* Obtain an **OAuth2 access token** via `/oauth/token`.
* Use the token in the `Authorization: Bearer` header for all API requests.
***
## Endpoints
### Retrieve Subscribers
```
GET /api/v1/subscribers
```
Query Parameters:
| Name | Type | Description |
| ----------- | ------- | ----------------------------------------- |
| page | integer | Page index (0-based) |
| size | integer | Number of results per page |
| uuid | uuid | Filter by subscriber UUID |
| name | string | Name of the subscriber |
| callbackUrl | string | Callback URL |
| enabled | boolean | Whether the subscriber is active |
| events | string | Comma-separated list of subscribed events |
| companyUuid | uuid | Optional UUID of the company |
***
### Create a Subscriber
```
POST /api/v1/subscribers
```
Body Example:
```json theme={null}
{
"name": "Accounting Service",
"callbackUrl": "https://example.com/webhook",
"events": ["PAYMENT_PAID", "CARD_CREATION_REQUEST_CREATED"],
"enabled": true,
"companyUuid": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed"
}
```
***
### Update a Subscriber
```
PATCH /api/v1/subscribers/{uuid}
```
***
### Delete a Subscriber
```
DELETE /api/v1/subscribers/{uuid}
```
***
### Manage Events on a Subscriber
* `POST /api/v1/subscribers/add-event`
* `DELETE /api/v1/subscribers/delete-event`
***
## Webhook Execution & Processing Flow
The WebHook event lifecycle consists of two key services working together:
### `WebhookConsumerService` (Kafka Listener & Subscriber Notifier)
This service listens to the Kafka topic and delivers the webhook to external subscribers. It ensures reliable delivery and avoids duplicate processing. It uses WebhookService:
```java theme={null}
@KafkaListener(topics = "${clara.kafka.webhook.topic.create.request}",
containerFactory = "kafkaListenerContainerFactory")
public void consumeWebhookRequest(ConsumerRecord input) {
var webhookRequest = SerdesUtils.deserialize(avroDeserializer, input);
if (Objects.nonNull(webhookRequest)) {
webhookRequestEntityRepository.findById(webhookRequest.getId())
.ifPresentOrElse(webhookRequestEntity -> {}, () -> {
log.debug("Processing webhook with id: {}", webhookRequest.getId());
webhookService.saveAndSendWebHook(webhookRequest);
});
}
}
```
### `WebhookService`
This service delivers Webhooks to external subscribers via a `POST` call
```java theme={null}
webhookService.sendWebHook(
webhookRequest.getCompanyUuid(),
webhookRequest.getId(),
webhookRequest.getEvent(),
webhookRequest.getMetadata(),
webhookRequest.getErrorCode(),
webhookRequest.getErrorMessage()
);
```
Together, these services ensure webhook events are decoupled, auditable, and reliably delivered.
## WebHook Architecture Overview
**Flow Overview:**
1. An **event** is triggered by a source system (e.g., Payments, Cards).
2. `WebhookConsumerService` subscribes to the topic and consumes the event. It uses `WebhookService`
3. The `WebhookService` service sends a `POST` request to the configured **Subscriber Endpoint**.
**Flow Diagram:**
```
[Event Source]
β
βΌ
[WebhookConsumerService]
β
βΌ
[Kafka Topic]
β
βΌ
[WebhookService]
β
βΌ
[Subscriber Endpoint]
```
***
## Summary
* Use `/api/v1/subscribers` to manage your webhook callback endpoints.
* Each subscriber can listen to one or more Clara platform events.
* Events are dispatched by `WebhookService` (implemented in your API) and delivered by `WebhookConsumerService`.
* Clara uses secure, resilient, and decoupled architecture to ensure webhook reliability.
***
## Sending WebHook Events from an API
You can also send WebHook events directly from your service logic or API controller using another `WebhookService`implemented in your API.
Here's an example using the `WebhookRequest` builder:
```java theme={null}
var webhookRequest = WebhookRequest.newBuilder()
.setId(cardResponse.getId())
.setCompanyUuid(UUID.fromString(cardResponse.getData().getCard().getCompanyUuid()))
.setEvent(CARD_CREATION_REQUEST_ERROR.name())
.setTimestamp(LocalDateTime.now())
.setErrorCode(cardResponse.getData().getCard().getErrorCode())
.setErrorMessage(cardResponse.getData().getCard().getErrorMessage())
.build();
webhookService.send(webhookRequest);
```
## This sends a structured webhook event using the built `WebhookRequest`. Ensure `WebhookService.send(...)` is appropriately configured to publish to Kafka or forward via HTTP as needed.
## WebhookService β Implementation Example
Here's how the `WebhookService` class is implemented to send events using Kafka:
```java theme={null}
@Slf4j
@Service
public class WebhookService {
private final KafkaTemplate kafkaTemplate;
private final String requestTopic;
private static final AvroSerializer webhookRequestAvroSerializer =
AvroSerializer.of(WebhookRequest.SCHEMA$);
public WebhookService(KafkaTemplate kafkaTemplate,
@Value("${clara.data-writer.kafka.webhook.topic.create.request}") String requestTopic) {
this.kafkaTemplate = kafkaTemplate;
this.requestTopic = requestTopic;
}
public void send(WebhookRequest webhookRequest) {
KafkaUtils.serializeAndSendNonReactive(
webhookRequestAvroSerializer,
webhookRequest,
webhookRequest.getId(),
requestTopic,
kafkaTemplate
);
}
}
```
This service serializes a `WebhookRequest` object using Avro and sends it to a Kafka topic defined in the application configuration.
# API Versioning
Source: https://developers.clara.team/api-versioning
How Clara versions its API and what to expect from each release.
Clara maintains multiple API versions simultaneously so you can integrate at your own pace without forced migrations.
## Current versions
| Version | Status | Recommendation |
| ------- | ------- | ---------------------------- |
| v3 | Current | Use for all new integrations |
| v2 | Stable | Supported, not deprecated |
| v1 | Legacy | Avoid for new work |
## What constitutes a breaking change
Clara considers these **breaking changes** β they will never happen within a version:
* Removing an existing field from a response
* Changing a field's data type
* Removing an endpoint
* Changing authentication requirements
These are **non-breaking** and may happen without a version bump:
* Adding new optional fields to responses
* Adding new optional query parameters
* Adding new endpoints
* Improving error messages
## Deprecation policy
When Clara deprecates a version:
1. A deprecation notice is published in the [Changelog](/versioning) with at least **6 months' notice**
2. The version remains functional throughout the deprecation period
3. A migration guide is provided before end-of-life
v1 and v2 are currently **not deprecated** β they will continue to receive security fixes.
## Version coexistence
All three versions share the same authentication (mTLS + OAuth 2.0). You can call v2 and v3 endpoints in the same integration using the same credentials β version is determined by the URL path (`/api/v2/...` vs `/api/v3/...`).
## Selecting a version
Use the **v3** tab on any API reference page to see the current interface. If a service is not yet available in v3, the page will indicate which version to use instead.
# Authentication
Source: https://developers.clara.team/authentication
mTLS + OAuth 2.0 Bearer token β both required for every request.
## Overview
Clara's API uses two-layer authentication: **mTLS** (mutual TLS) for the connection and **OAuth 2.0 Bearer token** for each request. Both must be present β a valid token without a client certificate will be rejected, and vice versa.
***
## How it works
1. **Certificate layer (mTLS):** Your client certificate authenticates the connection at the TLS level. Without a valid certificate, the handshake fails before any HTTP request is made.
2. **Token layer (OAuth 2.0):** Each HTTP request must include an `Authorization: Bearer ` header. Tokens are short-lived JWTs obtained from the `/oauth/token` endpoint using your `client_id` and `client_secret`.
Together, these two layers ensure that only authorized clients with valid credentials can interact with the API.
***
## Step 1: Create an API project
API credentials are managed directly from the Clara dashboard β no need to contact support for each new project.
Navigate to **Integrations β Clara API β Project credentials** for your country:
| Country | Dashboard URL |
| -------- | ---------------------------------------------------------------------------------------------------------------- |
| Mexico | [app.clara.cc/settings/integrations/clara-api](https://app.clara.cc/settings/integrations/clara-api) |
| Colombia | [colombia.clara.com/settings/integrations/clara-api](https://colombia.clara.com/settings/integrations/clara-api) |
| Brazil | [brasil.clara.com/settings/integrations/clara-api](https://brasil.clara.com/settings/integrations/clara-api) |
Click **Create project** and fill in the form:
| Field | Description |
| ------------------------ | ---------------------------------------------------------------------------------------------------- |
| **Project** | A name to identify this credential set (e.g., "ERP Integration β Prod") |
| **Validity** | How long the credentials will remain active β up to 360 days |
| **Permissions to write** | Which write operations this project can perform (e.g., Write cards, Write users, Write transactions) |
| **Permissions to read** | Which read operations this project can perform (e.g., Read cards, Read transactions) |
Once created, download your credentials. You will receive three items:
| File | Purpose |
| ----------------------------- | -------------------------------------------------------------------------------------------- |
| **Public key** | Client certificate for encryption/verification |
| **Private key** | Secret key for decryption/signing |
| **Client Credentials (JSON)** | JSON with Client ID, Client Secret, and scopes β use for Postman or automated token requests |
**One-time download only** β certificates won't be accessible once this window closes. Store the private key securely and treat it like a password; it cannot be retrieved again.
Projects expire after the validity period you select (max 360 days). Clara will alert you when projects are approaching expiration. Renew before expiry to avoid service interruption β create the new project first, update your integration, then let the old one expire.
**To request API access for the first time:** Contact your Customer Success Manager or Clara's Customer Happiness team:
* Mexico: [contacto@clara.com](mailto:contacto@clara.com)
* Colombia: [contacto.co@clara.com](mailto:contacto.co@clara.com)
* Brazil: [contato@clara.com](mailto:contato@clara.team)
***
## Step 2: Get an access token
Use your client certificate, private key, `client_id`, and `client_secret` to request a token:
```bash theme={null}
curl --request POST "https://public-api.mx.clara.com/oauth/token" \
--header "Authorization: Basic $(echo -n 'CLIENT_ID:CLIENT_SECRET' | base64)" \
--cert client.crt \
--key client.key
```
The response contains your Bearer token:
```json theme={null}
{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 86400
}
```
The `expires_in` value is in seconds. Store it and refresh the token proactively before it expires β do not wait for a `401` to trigger a refresh.
Token endpoint URLs are country-specific. Use `public-api.mx.clara.com/oauth/token` for Mexico, `public-api.br.clara.com/oauth/token` for Brazil, and `public-api.co.clara.com/oauth/token` for Colombia.
**Best practices for production integrations:**
* Cache the token for its full lifetime to avoid unnecessary token requests.
* If you receive a `401` on a previously working request, refresh the token and retry once before raising an error.
***
## Step 3: Make an authenticated request
Include your client certificate, private key, and Bearer token in every API request:
```bash theme={null}
curl -v https://public-api.mx.clara.com/api/v3/transactions \
--cert /path/to/client-cert.pem \
--key /path/to/client-key.pem \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6..." \
-H "Content-Type: application/json"
```
***
## Multi-entity accounts (X-Tax-Identifier)
If your account manages a group of companies (such as a holding), your token can assume the role of a specific entity without requiring separate credentials. Include the `X-Tax-Identifier` header with the target company's Tax ID:
```bash theme={null}
curl -v https://public-api.mx.clara.com/api/v3/transactions \
--cert /path/to/client-cert.pem \
--key /path/to/client-key.pem \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6..." \
-H "X-Tax-Identifier: ACME8001011H0" \
-H "Content-Type: application/json"
```
The same connection, certificates, and credentials work across all entities in the group β only the `X-Tax-Identifier` value changes per request.
***
## Postman setup
For teams who prefer Postman over raw curl:
1. Download the latest API spec from [api-docs-v3.json](https://docs-public-api.clara.com/api-docs-v3.json) and import it into Postman.
2. In **Settings β Certificates**, upload your CA certificate and client certificate (`.crt` + `.key`) for host `public-api.mx.clara.com` on port `443`.
3. On any endpoint, set Authorization type to **OAuth 2.0**, point the Access Token URL to `public-api.mx.clara.com/oauth/token`, and enter your `client_id` and `client_secret`.
4. Generate the token and start making requests.
If you need further assistance, refer to the [Clara help center](https://ayuda.clara.com.mx/hc/es-mx/articles/17827687040787-Clara-API).
***
## Monitor API usage
The **Insights** section gives you a live view of your integration's performance: requests consumed vs. remaining, success rate, and a breakdown by endpoint.
Navigate to **Integrations β Clara API β API Insights** for your country:
| Country | Insights URL |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| Mexico | [app.clara.cc/settings/integrations/clara-api/insights](https://app.clara.cc/settings/integrations/clara-api/insights) |
| Colombia | [colombia.clara.com/settings/integrations/clara-api/insights](https://colombia.clara.com/settings/integrations/clara-api/insights) |
| Brazil | [brasil.clara.com/settings/integrations/clara-api/insights](https://brasil.clara.com/settings/integrations/clara-api/insights) |
| Metric | What it tells you |
| --------------------------------- | ------------------------------------------------------------------------------------------------------- |
| **Remaining requests** | How many API calls remain in the current billing period |
| **Total requests** | Requests made this month, with trend vs. prior month |
| **Success rate** | Percentage of requests that returned a 2xx response |
| **Service performance breakdown** | Per-service breakdown (e.g., `TransactionsRead`, `OauthTokenWrite`) with request count and success rate |
Use this dashboard to detect unusual traffic spikes, spot failing endpoints before they affect your integration, and plan capacity ahead of billing resets.
# Cards API: How to Use It
Source: https://developers.clara.team/cards-guide
## Creating Cards
**Requirements:**
* New user creation. To enable the Clara API, you must create a user with the Company Owner role. This user is essential for creating resources in Clara. Separating this user helps distinguish actions from automated processes and those from other users on the platform, enhancing clarity and accountability.
* mTLS. Our API employs a secure authentication process that requires you to configure the client making the calls with the certificates provided when the API is enabled. This ensures a high level of security and a 2FA for your communications.
**Required Fields:**
* `type`: `"VIRTUAL"` or `"PHYSICAL"`
* `alias`: A nickname or identifier for the card
* `userUuid`: The unique identifier for the user in Clara (retrieve from the Users endpoint)
* `threshold`: Maximum spend limit. Minimum amounts: BRL 50 (Brazil), MXN 500 (Mexico), COP 100,000 (Colombia)
* `periodicity`: `"MONTHLY"`, `"WEEKLY"`, or `"DAILY"` β determines when the limit resets
**Examples:**
***Create: Virtual Card (MX)***
```json theme={null}
{
"type": "VIRTUAL",
"alias": "Example",
"userUuid": "42c7cc6b-06f7-46b8-b4f5-e876fbf57335",
"threshold": 500,
"periodicity": "DAILY"
}
```
In this example:
* `"VIRTUAL"` creates a virtual card, active immediately (no activation step needed).
* The threshold is 500 MXN, resetting daily.
***Create: Physical Card (MX)**:*
```json theme={null}
{
"type": "PHYSICAL",
"alias": "Example",
"userUuid": "42c7cc6b-06f7-46b8-b4f5-e876fbf57335",
"threshold": 500,
"periodicity": "MONTHLY"
}
```
In this example:
* `"PHYSICAL"` creates a physical card, which requires activation before first use.
* The threshold is 500 MXN, resetting monthly.
## Limitations
* Threshold must be β€ company credit line
* User must be active (email verified, 2FA)
* Only one card creation per user at a time (prevent fraud) - If you need multiple cards for one user, wait until the current card creation is complete before making another request.
* Monitor card count to avoid max limit - Clara has a maximum limit on valid cards for each company (active or locked)
## Card Operations
* \*\*Update limit (threshold): \*\*The new limit for this card must not exceed the company's total limit.
* \*\*Lock card: \*\*Must be active (card locked - Configurations and threshold can still be updated).
* \*\*Unlock card: \*\*Must be locked
* \*\*Cancel card: \*\*To free up space to create new cards (you can cancel cards that are active or locked) - After cancellation, the card canβt be used or recovered.
| Status | Update Threshold | Update Configurations | Cancel Card |
| ------------------ | ---------------- | --------------------- | ----------- |
| Active | β
| β
| β
|
| Locked | β
| β
| β
|
| Frozen | β
| β
| β
|
| Restricted | β
| β
| β
|
| Inactive / Deleted | β | β | β |
## Card Life Cycle
Creation β Activation (physical) β Active β Locking β Canceling β Closure
* **Creation:** The card is generated and assigned to a user. At this stage, details such as card type, limits, and user information are defined.
* \*\*Activation: \*\*The card is activated for use. This may involve confirming the user's identity and setting up necessary security measures. This process is only for physical cards, virtual cards are created and active by default.
* \*\*Active: \*\*The card is actively used for transactions. Users can spend up to the defined limits. In this stage, changes can be made to the card, such as adjusting spending limits, updating user information, and configuring the spending rules.
* **Locking:** If necessary, the card can be locked to prevent further transactions. This is often done in cases of suspected fraud, lost cards, or by direct action from the user.
* \*\*Canceling: \*\*By canceling the card, it becomes deactivated and no longer valid for transactions. This may occur when a user no longer needs the card or when it reaches its expiration date.
* \*\*Closure: \*\*The card is officially closed and removed from the system. This typically follows deactivation and is the final step in the card's life cycle.
**Notes:** Cards that are not canceled or closed are considered valid and count toward the maximum number of valid cards; once a card is canceled, it can't be recovered.
## Virtual Card
\*\*Note: \*\*Virtual cards are created as "active" by default, no activation is needed.
## Physical Card
**Note:** The statuses "locked," "master locked," and "Clara blocked" indicate the same state for the card but originate from different sources:
### Lock States Explained
* **Locked** = by user
* **Master Locked** = by manager or userβs hierarchy
* **Clara Blocked** = by our internal team
### Status Change Events
* Lock (Locked, Master Locked, Clara Blocked), unlock, or cancel by client, manager, or Clara
## Common Errors
* **`B013 Threshold exceeds company limit`**: This error occurs when the threshold (limit) set for a card exceeds the allowable amount, or the card limit exceeds the company's overall limit.
* **`B022 User is not activated`**: This error may occur if the user has been deleted or is not active on the Clara platform, like a new user.
* **`B033 Core service failure`**: This error indicates an internal failure and further investigation is needed to identify the problem.
* **`This user already has a card in the creation queue. Try again in 2 minutes`**: This error occurs because cards for the same user cannot be created concurrently. To solve this issue, you need to wait for the current card creation process to finish or allow the timeout for creation to occur in our system.
# Code Examples by Language
Source: https://developers.clara.team/code-examples
## :zap:***Java***
```java theme={null}
package com.clara.integrations.claraapi.example;
import org.bouncycastle.jce.provider.BouncyCastleProvider;
import org.bouncycastle.util.io.pem.PemObject;
import org.bouncycastle.util.io.pem.PemReader;
import javax.net.ssl.*;
import java.io.*;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.security.*;
import java.security.cert.Certificate;
import java.security.cert.CertificateException;
import java.security.cert.CertificateFactory;
import java.security.spec.PKCS8EncodedKeySpec;
import java.util.Base64;
public class Main {
public static void main(String[] args) throws Exception {
Certificate publicCert = loadFromFile(new File("path-to-your-certificate.crt"));
PrivateKey privateKey = readPKCS8PrivateKey(new File("path-to-your-certificate.crt.key"));
KeyStore ks = loadKeyStore(publicCert, privateKey);
TrustManager[] trustManagers = getTrustManagers();
KeyManager[] keyManagers = getKeyManagers(ks);
SSLContext sslContext = SSLContext.getInstance("SSL");
sslContext.init(keyManagers, trustManagers, new SecureRandom());
String clientId = "YOUR-CLIENT-ID";
String clientSecret = "YOUR-CLIENT-SECRET";
String auth = clientId + ":" + clientSecret;
String encodedAuth = Base64.getEncoder().encodeToString(auth.getBytes());
HttpClient client = HttpClient.newBuilder().sslContext(sslContext).build();
HttpRequest request = HttpRequest.newBuilder(new URI("https://public-api.mx.clara.com/oauth/token")).header("Authorization", "Basic " + encodedAuth).POST(HttpRequest.BodyPublishers.ofByteArray("".getBytes())).build();//use mx, co, br depending on your country you are based
HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println("Status: " + response.statusCode() + " Body: " + response.body());
// Extract token from response, then call a real endpoint
// Assuming token is parsed from response.body() into accessToken variable
String accessToken = "YOUR-ACCESS-TOKEN"; // replace with parsed token
HttpRequest txRequest = HttpRequest.newBuilder(new URI("https://public-api.mx.clara.com/api/v3/transactions"))
.header("Authorization", "Bearer " + accessToken)
.GET()
.build();
HttpResponse txResponse = client.send(txRequest, HttpResponse.BodyHandlers.ofString());
System.out.println("Transactions Status: " + txResponse.statusCode() + " Body: " + txResponse.body());
}
private static Certificate loadFromFile(File file) throws CertificateException, FileNotFoundException {
CertificateFactory fact = CertificateFactory.getInstance("X.509");
return fact.generateCertificate(new FileInputStream(file.getPath()));
}
private static TrustManager[] getTrustManagers() throws NoSuchAlgorithmException, KeyStoreException {
TrustManagerFactory trustManagerFactory = TrustManagerFactory.getInstance(TrustManagerFactory.getDefaultAlgorithm());
trustManagerFactory.init((KeyStore) null);
return trustManagerFactory.getTrustManagers();
}
private static KeyManager[] getKeyManagers(KeyStore identityStore) throws NoSuchAlgorithmException, KeyStoreException, UnrecoverableKeyException {
KeyManagerFactory keyManagerFactory = KeyManagerFactory.getInstance(KeyManagerFactory.getDefaultAlgorithm());
keyManagerFactory.init(identityStore, "".toCharArray());
return keyManagerFactory.getKeyManagers();
}
private static KeyStore loadKeyStore(Certificate cert, PrivateKey privateKey) throws KeyStoreException, CertificateException, IOException, NoSuchAlgorithmException {
KeyStore store;
store = KeyStore.getInstance("pkcs12");
store.load(null, "".toCharArray());
store.setKeyEntry("client", privateKey, "".toCharArray(), new Certificate[] { cert });
return store;
}
private static PrivateKey readPKCS8PrivateKey(File file) throws Exception {
Security.addProvider(new BouncyCastleProvider());
try (FileReader keyReader = new FileReader(file); PemReader pemReader = new PemReader(keyReader)) {
PemObject pemObject = pemReader.readPemObject();
byte[] content = pemObject.getContent();
PKCS8EncodedKeySpec spec = new PKCS8EncodedKeySpec(content);
KeyFactory keyFactory = KeyFactory.getInstance("RSA");
return keyFactory.generatePrivate(spec);
}
}
}
```
## :zap:***C#*** - Windows
**Note**: The Windows platform does not support CRT or PEM files directly in .NET, so you need to convert them into a PFX file. You can do this by running the following command in your terminal using the OpenSSL tool, while generating the file you will be asked to create a password, you can choose a **password** in this step to be used in your code after.
```
openssl pkcs12 -export -out certificate.pfx -inkey certificate.key -in certificate.crt
```
Another step is installing the PEM file into the **Trusted Root Certification Authorities**. In case this file is not being recognized by the Certificate Manager, change its extension to crt and install it on the Local Machine.
```csharp theme={null}
using System;
using System.IO;
using System.Net.Http;
using System.Security.Cryptography;
using System.Security.Cryptography.X509Certificates;
using System.Text;
using System.Threading.Tasks;
namespace Example
{
class Program
{
static async Task Main(string[] args)
{
X509Certificate2 certificate = new X509Certificate2("prod-mx.pfx", "your-password"); //BE SURE THE FILE IS THE FOLDER
var clientHandler = new HttpClientHandler();
clientHandler.ClientCertificates.Add(certificate);
clientHandler.ClientCertificateOptions = ClientCertificateOption.Manual;
clientHandler.SslProtocols = System.Security.Authentication.SslProtocols.Tls12;
var client = new HttpClient(clientHandler);
var clientId = ""; //CHANGE THIS FOR YOUR CREDENTIALS
var clientSecret = ""; //CHANGE THIS FOR YOUR CREDENTIALS
var base64Credentials = System.Convert.ToBase64String(Encoding.GetEncoding("ISO-8859-1").GetBytes(clientId + ":" + clientSecret));;
var request = new HttpRequestMessage(HttpMethod.Post, "https://public-api.mx.clara.com/oauth/token"); //WATCH YOUR COUNTRY
request.Headers.Add("Authorization", "Basic " + base64Credentials);
request.Content = new ByteArrayContent(Encoding.UTF8.GetBytes(""));
var response = await client.SendAsync(request);
var responseBody = await response.Content.ReadAsStringAsync();
Console.WriteLine($"Status: {response.StatusCode}, Body: {responseBody}");
// Use the token to call a real endpoint
// Parse access_token from responseBody JSON, then:
var accessToken = "YOUR-ACCESS-TOKEN"; // replace with parsed token
var txRequest = new HttpRequestMessage(HttpMethod.Get, "https://public-api.mx.clara.com/api/v3/transactions");
txRequest.Headers.Add("Authorization", "Bearer " + accessToken);
var txResponse = await client.SendAsync(txRequest);
var txBody = await txResponse.Content.ReadAsStringAsync();
Console.WriteLine($"Transactions Status: {txResponse.StatusCode}, Body: {txBody}");
}
}
}
```
## :zap:***C#*** - macOs or Linux
```csharp theme={null}
using System;
using System.IO;
using System.Net.Http;
using System.Security.Cryptography;
using System.Security.Cryptography.X509Certificates;
using System.Text;
using System.Threading.Tasks;
namespace Example
{
class Program
{
static async Task Main(string[] args)
{
X509Certificate2 certificate = new X509Certificate2("prod-mx.crt"); //BE SURE THE FILE IS THE FOLDER
using (StreamReader reader = new StreamReader("prod-mx.key")) //BE SURE THE FILE IS THE FOLDER
{
string privateKeyText = await reader.ReadToEndAsync();
RSA privateKey = RSA.Create();
privateKey.ImportFromPem(privateKeyText);
certificate = certificate.CopyWithPrivateKey(privateKey);
}
var clientHandler = new HttpClientHandler();
clientHandler.ClientCertificates.Add(certificate);
clientHandler.ClientCertificateOptions = ClientCertificateOption.Manual;
clientHandler.SslProtocols = System.Security.Authentication.SslProtocols.Tls12;
var client = new HttpClient(clientHandler);
var clientId = ""; //CHANGE THIS FOR YOUR CREDENTIALS
var clientSecret = ""; //CHANGE THIS FOR YOUR CREDENTIALS
var base64Credentials = System.Convert.ToBase64String(Encoding.GetEncoding("ISO-8859-1").GetBytes(clientId + ":" + clientSecret));;
var request = new HttpRequestMessage(HttpMethod.Post, "https://public-api.mx.clara.com/oauth/token"); //WATCH YOUR COUNTRY
request.Headers.Add("Authorization", "Basic " + base64Credentials);
request.Content = new ByteArrayContent(Encoding.UTF8.GetBytes(""));
var response = await client.SendAsync(request);
var responseBody = await response.Content.ReadAsStringAsync();
Console.WriteLine($"Status: {response.StatusCode}, Body: {responseBody}");
// Use the token to call a real endpoint
// Parse access_token from responseBody JSON, then:
var accessToken = "YOUR-ACCESS-TOKEN"; // replace with parsed token
var txRequest = new HttpRequestMessage(HttpMethod.Get, "https://public-api.mx.clara.com/api/v3/transactions");
txRequest.Headers.Add("Authorization", "Bearer " + accessToken);
var txResponse = await client.SendAsync(txRequest);
var txBody = await txResponse.Content.ReadAsStringAsync();
Console.WriteLine($"Transactions Status: {txResponse.StatusCode}, Body: {txBody}");
}
}
}
```
## :zap:***Python 3***
```python theme={null}
import requests
from requests.adapters import HTTPAdapter
from urllib3.util.ssl_ import create_urllib3_context
import base64
class SSLAdapter(HTTPAdapter):
def __init__(self, certfile, keyfile, cafile):
self.context = create_urllib3_context()
self.context.load_cert_chain(certfile, keyfile)
self.context.load_verify_locations(cafile)
super().__init__()
def init_poolmanager(self, *args, **kwargs):
kwargs['ssl_context'] = self.context
return super().init_poolmanager(*args, **kwargs)
client_id = 'YOUR-CLIENT-ID'
client_secret = 'YOUR-CLIENT-SECRET'
auth = base64.b64encode(f"{client_id}:{client_secret}".encode()).decode()
session = requests.Session()
session.mount("https://", SSLAdapter("path-to-your-certificate.crt", "path-to-your-certificate.crt.key", "path-to-ca-cert.pem"))
headers = {
"Authorization": f"Basic {auth}"
}
response = session.post("https://public-api.mx.clara.com/oauth/token", headers=headers)
print(f"Status: {response.status_code} Body: {response.text}")
# Use the token to call a real endpoint
token_data = response.json()
access_token = token_data["access_token"]
tx_headers = {
"Authorization": f"Bearer {access_token}"
}
tx_response = session.get("https://public-api.mx.clara.com/api/v3/transactions", headers=tx_headers)
print(f"Transactions Status: {tx_response.status_code} Body: {tx_response.text}")
```
## :zap:***Go***
```go Go Lang theme={null}
package main
import (
"crypto/tls"
"crypto/x509"
"encoding/base64"
"fmt"
"io/ioutil"
"log"
"net/http"
"os"
)
func main() {
cert, err := tls.LoadX509KeyPair("path-to-your-certificate.crt", "path-to-your-certificate.crt.key")
if err != nil {
log.Fatalf("failed to load client cert: %v", err)
}
caCert, err := ioutil.ReadFile("path-to-ca-cert.pem")
if err != nil {
log.Fatalf("failed to load CA cert: %v", err)
}
caCertPool := x509.NewCertPool()
caCertPool.AppendCertsFromPEM(caCert)
tlsConfig := &tls.Config{
Certificates: []tls.Certificate{cert},
RootCAs: caCertPool,
}
client := &http.Client{
Transport: &http.Transport{
TLSClientConfig: tlsConfig,
},
}
clientID := "YOUR-CLIENT-ID"
clientSecret := "YOUR-CLIENT-SECRET"
auth := base64.StdEncoding.EncodeToString([]byte(clientID + ":" + clientSecret))
req, err := http.NewRequest("POST", "https://public-api.mx.clara.com/oauth/token", nil)
if err != nil {
log.Fatal(err)
}
req.Header.Add("Authorization", "Basic "+auth)
resp, err := client.Do(req)
if err != nil {
log.Fatal(err)
}
defer resp.Body.Close()
body, _ := ioutil.ReadAll(resp.Body)
fmt.Printf("Status: %s Body: %s\n", resp.Status, string(body))
// Use the token to call a real endpoint
// Parse access_token from body JSON, then:
accessToken := "YOUR-ACCESS-TOKEN" // replace with parsed token from body
txReq, err := http.NewRequest("GET", "https://public-api.mx.clara.com/api/v3/transactions", nil)
if err != nil {
log.Fatal(err)
}
txReq.Header.Add("Authorization", "Bearer "+accessToken)
txResp, err := client.Do(txReq)
if err != nil {
log.Fatal(err)
}
defer txResp.Body.Close()
txBody, _ := ioutil.ReadAll(txResp.Body)
fmt.Printf("Transactions Status: %s Body: %s\n", txResp.Status, string(txBody))
}
```
## :zap:***JavaScript/Node.Js***
```javascript theme={null}
const https = require('https');
const fs = require('fs');
const path = require('path');
const clientId = 'YOUR-CLIENT-ID';
const clientSecret = 'YOUR-CLIENT-SECRET';
const auth = Buffer.from(`${clientId}:${clientSecret}`).toString('base64');
const options = {
hostname: 'public-api.mx.clara.com',
port: 443,
path: '/oauth/token',
method: 'POST',
key: fs.readFileSync('path-to-your-certificate.crt.key'),
cert: fs.readFileSync('path-to-your-certificate.crt'),
ca: fs.readFileSync('path-to-ca-cert.pem'),
headers: {
'Authorization': `Basic ${auth}`
}
};
const req = https.request(options, (res) => {
let data = '';
res.on('data', (chunk) => { data += chunk; });
res.on('end', () => {
console.log(`Status: ${res.statusCode} Body: ${data}`);
// Use the token to call a real endpoint
const tokenData = JSON.parse(data);
const accessToken = tokenData.access_token;
const txOptions = {
hostname: 'public-api.mx.clara.com',
port: 443,
path: '/api/v3/transactions',
method: 'GET',
key: fs.readFileSync('path-to-your-certificate.crt.key'),
cert: fs.readFileSync('path-to-your-certificate.crt'),
ca: fs.readFileSync('path-to-ca-cert.pem'),
headers: {
'Authorization': `Bearer ${accessToken}`
}
};
const txReq = https.request(txOptions, (txRes) => {
let txData = '';
txRes.on('data', (chunk) => { txData += chunk; });
txRes.on('end', () => {
console.log(`Transactions Status: ${txRes.statusCode} Body: ${txData}`);
});
});
txReq.on('error', (e) => { console.error(e); });
txReq.end();
});
});
req.on('error', (e) => {
console.error(e);
});
req.end();
```
# Capabilities by Country
Source: https://developers.clara.team/country-features
Quick reference of which API features and payment methods are available in Mexico, Brazil, and Colombia.
Clara operates in three markets, each with its own base URL and a distinct set of available features. Use this page to determine what's available before building your integration.
## Base URLs
| Country | Base URL |
| -------- | --------------------------------- |
| Mexico | `https://public-api.mx.clara.com` |
| Brazil | `https://public-api.br.clara.com` |
| Colombia | `https://public-api.co.clara.com` |
## Feature Availability
| Feature | Mexico | Brazil | Colombia |
| --------------------------------- | :----: | :----: | :------: |
| Corporate cards (physical) | β | β | β |
| Corporate cards (virtual) | β | β | β |
| Card spending configurations | β | β | β |
| Card lock / unlock | β | β | β |
| Transactions API v3 | β | β | β |
| User management (v3) | β | β | β |
| Billing statements | β | β | β |
| Reimbursements | β | β | β |
| Labels | β | β | β |
| VCN (Virtual Card Numbers) | β | β | β |
| Clara MCP | β | β | β |
| **CFDI fiscal invoices** | β | β | β |
| **Digital Account (PIX / TED)** | β | β | β |
| **Boleto payments** | β | β | β |
| **DDA (Authorized Direct Debit)** | β | β | β |
## Currency
| Country | Currency | Code |
| -------- | -------------- | ----- |
| Mexico | Mexican Peso | `MXN` |
| Brazil | Brazilian Real | `BRL` |
| Colombia | Colombian Peso | `COP` |
All `amount` fields in API responses are in currency units (not cents). Use `BigDecimal` or equivalent in typed languages to avoid floating-point errors.
## Country-Specific Endpoints
### Mexico only
**CFDI Fiscal Invoices** β Retrieve SAT-registered XML invoices linked to transactions:
* `GET /api/v3/transactions/{uuid}/invoices` β CFDI invoices for a specific transaction
* `GET /api/v3/invoices` β Query invoices by issuer RFC, date range, or folio fiscal UUID
* `GET /api/v2/invoices` β v2 invoice retrieval
### Brazil only
**Digital Account** β PIX, TED, and bill payment transactions for your Clara digital account:
* `GET /api/v3/digital-accounts` β Filter by date range and `transactionTypeName` (`PIX` | `TED` | `BILL` | `TRANSACTION`)
**Boleto Payments** β Bank slip (boleto bancΓ‘rio) payments:
* `POST /api/v2/payments` β Create a boleto payment with `barcodeDigitableLine`
* `GET /api/v2/payments` β List all boleto payments
* `GET /api/v2/payments/dda` β List DDA (pre-authorized) invoices
**DDA (DΓ©bito Direto Autorizado)** β Pre-authorized invoices retrieved automatically from financial institutions:
* `GET /api/v2/dda` β List available DDA invoices
## Tax Identifier Formats
Tax identifiers are used in user management and multi-entity requests:
| Country | Field | Format |
| -------- | ---------- | ----------------------------------- |
| Mexico | RFC | 11 or 13 characters |
| Brazil | CNPJ / CPF | 14 digits (CNPJ) or 11 digits (CPF) |
| Colombia | NIT | 7, 8, 9, or 10 digits |
Pass the company tax ID in the `X-Tax-Identifier` header to operate on behalf of a specific subsidiary in a multi-entity setup.
## Clara MCP Server URLs
| Country | MCP Server URL |
| -------- | --------------------------- |
| Mexico | `https://mx.clara.team/mcp` |
| Brazil | `https://br.clara.team/mcp` |
| Colombia | `https://co.clara.team/mcp` |
# Error Handling
Source: https://developers.clara.team/error-handling
HTTP status codes, Clara-specific error codes, and retry strategies for building resilient integrations.
## Error Response Format
All errors return a JSON body with at minimum a `message` field:
```json theme={null}
{
"message": "Threshold exceeds company limit",
"code": "B013"
}
```
Some endpoints return additional context in a `details` array or an `error` string field depending on the API version.
***
## HTTP Status Codes
| Code | Meaning | What to do |
| ----- | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `200` | Success | β |
| `400` | Bad request β invalid parameters or missing required fields | Fix the request body or query parameters before retrying |
| `401` | Unauthorized β missing, expired, or invalid Bearer token | Refresh your token and retry |
| `403` | Forbidden β valid token but insufficient permissions | Check the user role (requires Administrator or the relevant scope) |
| `404` | Not found β resource does not exist | Verify the UUID or path parameter |
| `422` | Unprocessable entity β request is well-formed but fails business validation | Check the `code` field for the specific Clara error code |
| `429` | Rate limit exceeded | Back off and retry with exponential backoff (see [Rate Limits](#rate-limits)) |
| `500` | Internal server error | Retry once after a short delay; if persistent, contact support |
| `511` | Network authentication required | Your mTLS certificate is missing or not being sent β check your client cert configuration |
### Response body examples by status code
**400 β Bad request (invalid parameter)**
```json theme={null}
{
"code": "VALIDATION_ERROR",
"message": "Invalid date format: startDate must be YYYY-MM-DD",
"timestamp": "2024-03-15T10:30:00Z"
}
```
**401 β Unauthorized (expired token)**
```json theme={null}
{
"code": "UNAUTHORIZED",
"message": "Unauthorized",
"timestamp": "2024-03-15T10:30:00Z"
}
```
**403 β Forbidden (insufficient role)**
```json theme={null}
{
"code": "FORBIDDEN",
"message": "Access denied: insufficient permissions for this resource",
"timestamp": "2024-03-15T10:30:00Z"
}
```
**404 β Not found**
```json theme={null}
{
"code": "NOT_FOUND",
"message": "Card with UUID '1614c41b-8eb4-4573-9262-8aff011224c5' not found",
"timestamp": "2024-03-15T10:30:00Z"
}
```
**422 β Business validation failure**
```json theme={null}
{
"code": "B013",
"message": "Threshold exceeds company limit",
"timestamp": "2024-03-15T10:30:00Z"
}
```
**500 β Internal server error**
```json theme={null}
{
"code": "B033",
"message": "Core service failure",
"timestamp": "2024-03-15T10:30:00Z"
}
```
***
## Auth Errors (401 / 403)
### 401 β Token expired
Tokens have a finite lifetime (`expires_in` seconds). When one expires, every request returns `401`.
```json theme={null}
{ "message": "Unauthorized" }
```
**Fix:** Request a new token from `/oauth/token` and retry. In production, refresh proactively before expiry rather than waiting for a `401`.
### 401 β Missing certificate
If the mTLS handshake fails because no client certificate is presented:
```json theme={null}
{ "message": "Unauthorized" }
```
**Fix:** Ensure `--cert` and `--key` are included in every request. See [Troubleshooting](/troubleshooting) for certificate debugging steps.
### 403 β Insufficient role
A valid token from a user role that doesn't have access to the endpoint.
**Fix:** Confirm the API user has the `COMPANY_OWNER` or required role. Role requirements vary by endpoint.
***
## Business Error Codes
Clara API returns business-specific error codes for validation failures. These appear in the `code` or `message` field of the response body.
### Cards
| Code | Message | Cause | Fix |
| ------ | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `B013` | Threshold exceeds company limit | The card `threshold` exceeds the company's available credit line | Set a lower threshold or contact your Clara account team to review credit limits |
| `B022` | User is not activated | The target user hasn't completed email verification or 2FA setup, or the user has been deleted | Verify the user is active in the Clara platform before issuing a card |
| `B033` | Core service failure | Internal processing failure | Retry after a short delay; if persistent, contact [integration support](#support-contacts) |
| β | This user already has a card in the creation queue. Try again in 2 minutes | Concurrent card creation for the same user is not allowed | Wait for the in-progress creation to complete or timeout (\~2 min) before retrying |
### Users
| Scenario | Status | Cause |
| --------------------- | ------ | --------------------------------------------------------------------------------------- |
| Tax ID format invalid | `400` | Tax ID must match country format: MX = 11 or 13 chars, BR = 11 digits, CO = 7β10 digits |
| Duplicate email | `400` | A user with that email already exists in the company |
### Transactions / Filtering
| Scenario | Status | Cause |
| ----------------------- | ------ | ------------------------------------------------------------------------- |
| Invalid date format | `400` | Dates must be `YYYY-MM-DD`. Use ISO 8601 β no slashes or other separators |
| `startDate` > `endDate` | `400` | Date range is invalid β start must be β€ end |
### Digital Account (Brazil)
| Scenario | Status | Cause |
| ----------------------------- | ------ | --------------------------------------------------- |
| Invalid `transactionTypeName` | `400` | Must be one of: `PIX`, `TED`, `BILL`, `TRANSACTION` |
| Invalid date format | `400` | Must be `YYYY-MM-DD` |
| `startDate` > `endDate` | `400` | Start date must be β€ end date |
***
## Rate Limits
Requests are rate-limited per client certificate across all endpoints. Limits are applied separately to read (`GET`) and write (`POST`, `PATCH`, `DELETE`) operations β write endpoints have lower limits.
When you exceed the limit, the API returns `429 Too Many Requests`:
```json theme={null}
{ "message": "Too Many Requests" }
```
**Retry strategy:** Use exponential backoff with jitter. A safe starting point:
```python theme={null}
import time, random
def request_with_retry(fn, max_retries=4):
for attempt in range(max_retries):
response = fn()
if response.status_code != 429:
return response
wait = (2 ** attempt) + random.uniform(0, 1)
time.sleep(wait)
raise Exception("Rate limit exceeded after retries")
```
For sustained high-volume use cases, contact your Clara integration team to discuss limit increases.
***
## Retry Guidance
| Status | Retry? | Notes |
| ------ | ------------------- | ----------------------------------------------- |
| `400` | No | Fix the request first |
| `401` | Yes β after refresh | Refresh token, then retry once |
| `403` | No | Permission issue β retrying won't help |
| `404` | No | Resource doesn't exist |
| `429` | Yes β with backoff | Wait before retrying |
| `500` | Yes β once | Retry after 2β5 seconds; escalate if persistent |
| `511` | No | Certificate configuration issue |
***
## Support Contacts
If you encounter persistent errors not covered here:
| Country | Integration Support |
| -------- | ----------------------------------------------------------------------------- |
| Mexico | [integration.support.mx@clara.team](mailto:integration.support.mx@clara.team) |
| Brazil | [integration.support.br@clara.team](mailto:integration.support.br@clara.team) |
| Colombia | [integration.support.co@clara.team](mailto:integration.support.co@clara.team) |
# Provision Cards for Employees
Source: https://developers.clara.team/guides/provision-cards
Look up or create a user, issue a virtual card with a spending limit, apply restrictions, and clean up when they leave.
This guide covers the full employee card lifecycle: onboarding a new cardholder, issuing a virtual card, configuring optional spending restrictions, and safely offboarding when an employee departs.
## Prerequisites
* A valid Bearer token and mTLS client certificate. See [Authentication](/authentication).
* The employee's name, email, and role.
***
## Step 1: Look up the user
Before creating a card, check whether the user already exists in Clara. Query by email to avoid duplicates.
```bash theme={null}
curl --request GET \
"https://public-api.mx.clara.com/api/v3/users?email=ana.garcia@acme.com" \
--header "Authorization: Bearer " \
--cert client.crt \
--key client.key
```
Response:
```json theme={null}
{
"totalElements": 1,
"content": [
{
"uuid": "a0c82a20-ac09-4cfd-b429-d0623585911e",
"fullName": "Ana GarcΓa",
"email": "ana.garcia@acme.com",
"role": "EMPLOYEE",
"status": "ACTIVE"
}
]
}
```
If `totalElements` is `0`, the user doesn't exist yet β create them first via the [Users API](/v3/users), then proceed with the `uuid` returned.
***
## Step 2: Issue a virtual card
Create a virtual card assigned to the user. Set a `threshold` (spending limit) and a `periodicity` that resets it automatically.
```bash theme={null}
curl --request POST \
"https://public-api.mx.clara.com/api/v3/cards" \
--header "Authorization: Bearer " \
--header "Content-Type: application/json" \
--cert client.crt \
--key client.key \
--data '{
"type": "VIRTUAL",
"alias": "Ana GarcΓa β Travel",
"userUuid": "a0c82a20-ac09-4cfd-b429-d0623585911e",
"threshold": 5000,
"periodicity": "MONTHLY"
}'
```
Response:
```json theme={null}
{
"uuid": "5d1e2f83-1c90-4c34-9400-bfef9ac85c6e",
"alias": "Ana GarcΓa β Travel",
"status": { "code": "ACTIVE", "description": "Active" },
"maskedPan": "514509******5946",
"threshold": 5000,
"periodicity": { "type": "MONTHLY" },
"type": { "format": "VIRTUAL" },
"user": {
"uuid": "a0c82a20-ac09-4cfd-b429-d0623585911e",
"name": "Ana GarcΓa"
}
}
```
Save the card `uuid` β you'll need it for configuration and status checks.
| Field | Notes |
| -------------- | ------------------------------------------------------------------ |
| `type` | `VIRTUAL` or `PHYSICAL` |
| `alias` | A human-readable label shown in the Clara dashboard |
| `threshold` | Amount in your company's currency (MXN, BRL, or COP) |
| `periodicity` | `MONTHLY`, `WEEKLY`, or `DAILY` β determines when the limit resets |
| `businessType` | Optional: `BUSINESS` or `WORLD_ELITE` |
***
## Step 3: Apply spending restrictions (optional)
Use the Card Configurations API to add time, day-of-week, or merchant category restrictions. All fields are optional and can be combined.
```bash theme={null}
curl --request POST \
"https://public-api.mx.clara.com/api/v2/cards/5d1e2f83-1c90-4c34-9400-bfef9ac85c6e/configurations" \
--header "Authorization: Bearer " \
--header "Content-Type: application/json" \
--cert client.crt \
--key client.key \
--data '{
"weekdays": {
"values": ["SATURDAY", "SUNDAY"],
"allowedDaysOfUse": false
},
"merchants": {
"values": ["TRANSPORTATION", "CAR_RENTALS", "TRAVEL_AND_LODGING", "FOOD"],
"allowedMerchants": true
}
}'
```
This example restricts usage to weekdays only and allows spending solely at transportation, car rental, hotel, and food merchants.
Common configurations:
| Restriction | How |
| ----------------------------------- | ------------------------------------------------------------------- |
| Block weekends | `weekdays.values: ["SATURDAY","SUNDAY"]`, `allowedDaysOfUse: false` |
| Restrict to specific MCC categories | `merchants.values: [...]`, `allowedMerchants: true` |
| Time window (e.g., 9amβ6pm) | `period.startTime: "09:00"`, `endTime: "18:00"` |
| Auto-delete after a trip | `period.endDate: "YYYY-MM-DD"`, `enableAutoDeletion: true` |
See [Card Configurations](/v2/card-configurations) for the full list of merchant categories and options.
***
## Step 4: Confirm the card is active
Verify the card is ready before distributing it to the employee.
```bash theme={null}
curl --request GET \
"https://public-api.mx.clara.com/api/v3/cards/5d1e2f83-1c90-4c34-9400-bfef9ac85c6e" \
--header "Authorization: Bearer " \
--cert client.crt \
--key client.key
```
Confirm `status.code` is `"ACTIVE"` before sharing the card details with the cardholder.
***
## Adjust the spending limit
To raise or lower the threshold at any time:
```bash theme={null}
curl --request PATCH \
"https://public-api.mx.clara.com/api/v3/cards/5d1e2f83-1c90-4c34-9400-bfef9ac85c6e/threshold" \
--header "Authorization: Bearer " \
--header "Content-Type: application/json" \
--cert client.crt \
--key client.key \
--data '{ "threshold": 8000 }'
```
***
## Offboarding
When an employee leaves, first lock the card to immediately block usage, then delete it once you've confirmed there are no pending transactions.
**Lock the card** (immediately blocks all charges):
```bash theme={null}
curl --request PATCH \
"https://public-api.mx.clara.com/api/v3/cards/5d1e2f83-1c90-4c34-9400-bfef9ac85c6e/lock" \
--header "Authorization: Bearer " \
--header "Content-Type: application/json" \
--cert client.crt \
--key client.key \
--data '{ "lockCode": 16 }'
```
**Delete the card** (permanent, cannot be recovered):
```bash theme={null}
curl --request DELETE \
"https://public-api.mx.clara.com/api/v3/cards/5d1e2f83-1c90-4c34-9400-bfef9ac85c6e" \
--header "Authorization: Bearer " \
--cert client.crt \
--key client.key
```
Deleted cards cannot be recovered. Lock first, wait 24β48 hours to confirm no settlements are pending, then delete.
***
## Related
* [Cards API reference](/v3/cards)
* [Users API reference](/v3/users)
* [Card Configurations reference](/v2/card-configurations)
# Reconcile Transactions
Source: https://developers.clara.team/guides/reconcile-transactions
Pull all transactions for a billing period, match them to the billing statement, categorize with labels, and export to your accounting system.
This guide walks through the full monthly reconciliation flow: fetching every transaction in a billing period, pulling the matching billing statement for totals verification, tagging transactions with accounting labels, and downloading supporting documents.
## Prerequisites
* A valid Bearer token and mTLS client certificate. See [Authentication](/authentication).
* The billing period you want to reconcile (start and end dates in `YYYY-MM-DD` format).
***
## Step 1: Fetch all transactions for the period
Use `operationDateRangeStart` and `operationDateRangeEnd` to scope the request to a specific billing period. Transactions are paginated β page through all results before moving on.
```bash theme={null}
curl --request GET \
"https://public-api.mx.clara.com/api/v3/transactions?operationDateRangeStart=2025-04-01&operationDateRangeEnd=2025-04-30&page=0&size=100" \
--header "Authorization: Bearer " \
--cert client.crt \
--key client.key
```
Response:
```json theme={null}
{
"content": [
{
"uuid": "4ea5a94a-2c3c-4601-b623-c30260c21dbc",
"type": "PURCHASE",
"transactionLabel": "AEROMEXICO",
"status": { "code": "OP", "description": "AUTHORIZED" },
"amountValue": { "value": 3200.00, "currency": "MXN" },
"merchant": { "name": "Aeromexico", "category": "TRAVEL" },
"card": { "lastFourDigits": "3421" },
"user": { "name": "Ana GarcΓa", "uuid": "f3a9cb88-894b-4420-aed3-6178cd41721d" },
"billingStatement": { "uuid": "e4a50134-447f-4c34-b6b6-78cdb43d3fd5" },
"hasAttachments": { "value": true },
"hasInvoice": { "value": false }
}
],
"totalElements": 247,
"totalPages": 3,
"size": 100,
"number": 0
}
```
### Pagination loop
Continue requesting until `number` equals `totalPages - 1`, or until a page returns fewer items than `size`.
```
page=0 β 100 results
page=1 β 100 results
page=2 β 47 results β last page
```
Available filters:
| Filter | Description |
| ----------------------------------------------------- | -------------------------------------------------------------------------------- |
| `operationDateRangeStart` / `operationDateRangeEnd` | Transaction date range (recommended for reconciliation) |
| `accountingDateRangeStart` / `accountingDateRangeEnd` | Accounting date range (use if your system books on accounting date) |
| `lastUpdateDateRangeStart` / `lastUpdateDateRangeEnd` | Catch transactions updated after initial export |
| `status` | `NOTIFICATION`, `PRE_AUTHORIZED`, `AUTHORIZED`, `REJECTED`, `SYSTEM_TRANSACTION` |
| `userUuid` | Limit to one cardholder |
| `cardUuid` | Limit to one card |
Pre-authorizations (`PRE_AUTHORIZED`) may settle as `AUTHORIZED` up to 2 business days later. For a complete reconciliation, either wait for settlement or run an incremental sync using `lastUpdateDateRangeStart`.
***
## Step 2: Fetch the billing statement
Get the list of billing statements and find the one whose date range matches your period.
```bash theme={null}
curl --request GET \
"https://public-api.mx.clara.com/api/v3/billing-statements" \
--header "Authorization: Bearer " \
--cert client.crt \
--key client.key
```
Response:
```json theme={null}
[
{
"uuid": "e4a50134-447f-4c34-b6b6-78cdb43d3fd5",
"statementStartDate": "2025-04-01",
"statementEndDate": "2025-04-30",
"currency": "MXN",
"totalAmount": 184250.00,
"status": "CLOSED",
"generatedAt": "2025-05-01T10:00:00Z"
}
]
```
Fetch the full statement with its embedded transactions to verify your totals:
```bash theme={null}
curl --request GET \
"https://public-api.mx.clara.com/api/v3/billing-statements/e4a50134-447f-4c34-b6b6-78cdb43d3fd5" \
--header "Authorization: Bearer " \
--cert client.crt \
--key client.key
```
Cross-reference: the sum of `amountValue` across all `AUTHORIZED` transactions in your export should equal the statement's `totalAmount`.
***
## Step 3: Tag transactions with accounting labels
Labels let you attach GL codes, cost centers, or project IDs to transactions before exporting. Bind them in bulk for efficiency.
```bash theme={null}
curl --request POST \
"https://public-api.mx.clara.com/api/v3/transactions/labels/bulk" \
--header "Authorization: Bearer " \
--header "Content-Type: application/json" \
--cert client.crt \
--key client.key \
--data '{
"transactions": [
{
"uuid": "4ea5a94a-2c3c-4601-b623-c30260c21dbc",
"labelsUuid": ["label-uuid-travel-001", "label-uuid-cost-center-sales"]
},
{
"uuid": "b1c2d3e4-5678-90ab-cdef-1234567890ab",
"labelsUuid": ["label-uuid-software-002"]
}
]
}'
```
To list available labels, see [Labels API](/v2/labels).
***
## Step 4: Download supporting documents
For any transaction with `hasAttachments.value: true`, download the attached receipts.
```bash theme={null}
curl --request GET \
"https://public-api.mx.clara.com/api/v3/transactions/4ea5a94a-2c3c-4601-b623-c30260c21dbc/documents" \
--header "Authorization: Bearer " \
--cert client.crt \
--key client.key
```
Response includes pre-signed S3 URLs valid for 12 hours:
```json theme={null}
{
"uuid": "4ea5a94a-2c3c-4601-b623-c30260c21dbc",
"attachments": [
{
"uuid": "18589896-d30e-4cca-a4e6-716ba323b937",
"fileName": "receipt.jpg",
"format": "jpeg",
"download": {
"url": "https://...",
"urlExpiration": "2025-04-30T19:00:00Z"
}
}
]
}
```
For Mexico: transactions with `hasInvoice.value: true` also have a CFDI XML available at `GET /api/v3/transactions/{uuid}/invoices`.
***
## Export format
Here is a flat row structure suitable for most accounting systems (SAP, NetSuite, QuickBooks):
```json theme={null}
{
"transaction_uuid": "4ea5a94a-2c3c-4601-b623-c30260c21dbc",
"date": "2025-04-15",
"amount": 3200.00,
"currency": "MXN",
"type": "PURCHASE",
"status": "AUTHORIZED",
"merchant_name": "Aeromexico",
"merchant_category": "TRAVEL",
"cardholder_name": "Ana GarcΓa",
"cardholder_uuid": "f3a9cb88-894b-4420-aed3-6178cd41721d",
"card_last_four": "3421",
"billing_statement_uuid": "e4a50134-447f-4c34-b6b6-78cdb43d3fd5",
"labels": ["TRAVEL", "COST_CENTER_SALES"],
"has_receipt": true
}
```
***
## Related
* [Transactions API reference](/v3/transactions)
* [Billing Statements API reference](/v3/billing-statements)
* [Labels API reference](/v2/labels)
# Generate a VCN for a Purchase
Source: https://developers.clara.team/guides/vcn-purchase
Create a Virtual Card Number locked to a supplier and amount, use it to pay, and reconcile the resulting transaction.
Virtual Card Numbers (VCNs) are single-use or limited-use card numbers generated for a specific supplier and spending limit. They're ideal for B2B payments where you want spending controls without issuing a reusable corporate card.
This guide walks through creating a VCN, sharing it with a supplier, verifying the resulting transaction, and canceling unused VCNs.
## Prerequisites
* VCN feature enabled on your account. Contact your Clara integration team if you don't see it.
* A valid Bearer token and mTLS client certificate. See [Authentication](/authentication).
***
## Step 1: Retrieve your company configuration
Before creating a VCN, fetch the RCNs (real card numbers), suppliers, and templates available to your company. The IDs returned here are required in the create request.
```bash theme={null}
curl --request GET \
"https://public-api.mx.clara.com/api/v1/vcn?companyDetail=ALL" \
--header "Authorization: Bearer " \
--cert client.crt \
--key client.key
```
Response:
```json theme={null}
{
"rcns": [
{ "id": 38105, "alias": "Clara Card Black" }
],
"suppliers": [
{ "id": 47401, "name": "Proveedor Ejemplo S.A." }
],
"templates": [
{
"id": 50631,
"name": "Clara Hotels",
"description": "Restricted to hotel MCCs",
"type": "PC",
"purchaseTypes": [
{ "mcc": "3501", "description": "HOLIDAY INNS" }
]
}
]
}
```
Note the `rcns[].id`, `suppliers[].id`, and `templates[].id` you'll use in the next step.
***
## Step 2: Create the VCN
Create a VCN locked to a specific supplier, amount, and validity window.
```bash theme={null}
curl --request POST \
"https://public-api.mx.clara.com/api/v1/vcn/card" \
--header "Authorization: Bearer " \
--header "Content-Type: application/json" \
--cert client.crt \
--key client.key \
--data '{
"rcnId": 38105,
"supplierId": 47401,
"templateId": 50631,
"amount": 12500.00,
"validFrom": "2025-06-01",
"validTo": "2025-06-30",
"reference": "PO-2025-00842",
"customFields": [
{ "name": "Purchase Type", "value": "Hotel Stay" }
]
}'
```
Response:
```json theme={null}
{
"vcnId": 99201,
"cardNumber": "5432109876543210",
"cvv": "927",
"expirationDate": "06/25",
"amount": 12500.00,
"validFrom": "2025-06-01",
"validTo": "2025-06-30",
"status": "ACTIVE",
"reference": "PO-2025-00842"
}
```
The `cardNumber`, `cvv`, and `expirationDate` are the credentials you'll share with the supplier to complete the payment.
| Field | Description |
| ----------------------- | --------------------------------------------------------- |
| `rcnId` | The parent card number this VCN draws from |
| `supplierId` | Restricts the VCN to charges from this supplier only |
| `templateId` | Applies MCC and rule restrictions defined in the template |
| `amount` | Maximum amount the VCN can be charged |
| `validFrom` / `validTo` | The window during which the VCN is active |
| `reference` | Your internal reference (PO number, project code, etc.) |
VCN card details are only returned once at creation time. Store `cardNumber`, `cvv`, and `expirationDate` securely β they are not retrievable again via the API.
***
## Step 3: Share with the supplier
Provide the supplier with the card details to process payment:
* **Card number:** `5432109876543210`
* **CVV:** `927`
* **Expiration:** `06/25`
* **Billing amount:** `$12,500.00 MXN`
The VCN is locked to the configured supplier and will be declined anywhere else.
***
## Step 4: Verify the transaction
After the supplier charges the card, confirm the transaction settled by querying your transactions filtered by the card:
```bash theme={null}
curl --request GET \
"https://public-api.mx.clara.com/api/v3/transactions?operationDateRangeStart=2025-06-01&operationDateRangeEnd=2025-06-30&page=0&size=20" \
--header "Authorization: Bearer " \
--cert client.crt \
--key client.key
```
Match by `transactionLabel` (merchant name) and `amountValue` to confirm the charge. A settled VCN transaction will have `status.code: "OP"` (AUTHORIZED).
***
## Step 5: Cancel an unused VCN
If the purchase doesn't go through or the VCN was created in error, cancel it to prevent future charges.
```bash theme={null}
curl --request POST \
"https://public-api.mx.clara.com/api/v1/vcn/card/99201/cancel" \
--header "Authorization: Bearer " \
--cert client.crt \
--key client.key
```
Canceling a VCN releases the reserved amount back to the parent RCN balance.
***
## Update a VCN
To extend the validity window or adjust the amount before the VCN is charged:
```bash theme={null}
curl --request PUT \
"https://public-api.mx.clara.com/api/v1/vcn/card/99201" \
--header "Authorization: Bearer " \
--header "Content-Type: application/json" \
--cert client.crt \
--key client.key \
--data '{
"amount": 14000.00,
"validTo": "2025-07-15"
}'
```
Once a VCN has been fully charged, it cannot be updated.
***
## Related
* [VCN Introduction](/vcn/introduction)
* [VCN Lifecycle reference](/vcn/lifecycle)
* [Transactions API reference](/v3/transactions)
# Clara API
Source: https://developers.clara.team/introduction
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 ` 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 `` with your market's base URL and `` with a valid Bearer token.
```bash theme={null}
curl --request GET "/api/v3/transactions?page=0&size=10" \
--header "Authorization: Bearer " \
--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
Issue physical and virtual cards, set spending limits, lock/unlock, and configure merchant and time restrictions.
List, filter, and export transactions with full merchant, user, label, and accounting data.
Create, update, and deactivate users. Manage roles, cost centers, and manager assignments.
Retrieve CFDI fiscal invoices and extracted documents linked to transactions. Mexico only.
Access monthly billing statements with embedded transaction detail for automated reconciliation.
Query and manage employee reimbursement records by date, status, or requester.
Retrieve PIX, TED, and bill payment transactions for Brazil digital accounts.
Generate and manage Virtual Card Numbers for controlled B2B purchasing with spending rules.
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](/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.
# Clara MCP
Source: https://developers.clara.team/mcp/introduction
Connect your AI assistant directly to Clara β query transactions, manage cards, and take actions in natural language.
Clara MCP is in **Beta**. Core features are fully functional. Some tools are still being refined and may change.
## What is Clara MCP?
Clara MCP lets you connect your preferred AI assistant β Claude, ChatGPT, Gemini, or any MCP-compatible tool β directly to your Clara account.
Instead of logging into Clara to check something, you ask your AI assistant in natural language:
> "What were my company's top spending categories last month?"\
> "Lock the card assigned to Luis PΓ©rez right now."\
> "Show me all transactions over \$5,000 from the last 30 days."
Your AI assistant connects to Clara in real time and responds β no copy-pasting, no tab switching.
**MCP (Model Context Protocol)** is an open standard that allows AI tools to connect securely to external services. Clara's MCP server runs on Clara's own infrastructure β nothing executes on your machine, and Clara doesn't persist your data outside its own systems. Note that the AI tool you connect (Claude, ChatGPT, Gemini, etc.) does receive and process the data returned by each tool call in order to respond to you, subject to that provider's own data handling terms.
***
## Available Tools (Beta)
| Prompt | What happens |
| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------- |
| "List all my corporate cards" | Returns all active cards: cardholder name, last 4 digits, status, and spending limits |
| "Show my transactions this month" | Returns card transactions, filterable by card, date range, and more |
| "Lock \[card name or number]" | Immediately locks a specific card |
| "Unlock \[card name or number]" | Immediately unlocks a specific card |
| "Attach this invoice to the Aeromexico transaction from last week" | Uploads a document and attaches it to the matching transaction |
| "What companies do I have access to?" | Lists the companies you can operate in |
| "Switch to \[company name]" | Changes the active company for the rest of the session |
More tools coming soon β expenses, reimbursements, limits, approvals, and more.
***
## Who Can Use It
| Role | Access |
| -------------- | ------------------------------------------------------------- |
| **Admin** | Full access: list cards, view transactions, lock/unlock cards |
| **Bookkeeper** | Full access to the same tools |
| Other roles | Not supported in this version |
Clara MCP is available on all plans at no additional cost during Beta.
***
## How to Connect
Clara MCP now uses **OAuth** β there's no token to generate or manage. When you connect your AI tool, you'll be prompted to log in with your Clara account (the same credentials you use on the platform: email/password, Google, Microsoft, or passkey, depending on what your account supports).
If you're an Admin or Bookkeeper, you can connect directly β see [MCP Quickstart](/mcp/quickstart) for setup steps by tool.
**Switching from the previous token-based setup?** Static tokens are no longer valid with the current MCP server. You'll need to reconnect your AI tool using the OAuth login flow β see the migration steps for your tool in the [Quickstart](/mcp/quickstart).
If you have trouble connecting:
| Team | Contact |
| -------------------- | ----------------------------------------------------------------------------- |
| Customer Happiness | In-platform chat or [contacto@clara.com](mailto:contacto@clara.com) |
| Solution Engineering | [integration.support.mx@clara.team](mailto:integration.support.mx@clara.team) |
***
## Security
| Protection | How it works |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| OAuth login | Your AI tool authenticates through Clara's login flow β no static token or password is shared with or stored by the AI tool. |
| Session-based access | Your MCP access is tied to your Clara session. There's no separate secret that can be leaked from a config file. |
| Revoke access | There's no self-service revocation yet β contact Clara support to revoke access for a connected AI tool; it's cut off immediately across all tools. |
| Encrypted connection | All communication between your AI tool and Clara uses HTTPS. |
| No data persisted by Clara | Clara's MCP server runs on Clara's infrastructure and doesn't persist your data. The AI tool you connect does process returned data to generate its response, per that provider's own data terms. |
***
## Known Limitations (Beta)
| Issue | Status | Expected |
| ------------------------------------------------------------------------------------- | --------------- | -------- |
| Lock/unlock card: response may appear as plain text instead of a confirmation message | Fix in progress | Q3 2026 |
| Transaction count summary may show 0 for some accounts | Fix in progress | Q3 2026 |
These issues do not affect the underlying operations β cards lock/unlock correctly even if the confirmation message looks different.
***
## FAQ
**Is Clara MCP the same as the Clara AI Financial Analyst (Agente Clara)?**\
No. Agente Clara is the AI assistant built into the Clara platform. Clara MCP connects external AI tools (like Claude Desktop on your computer, ChatGPT, or Gemini) to your Clara data. Think of MCP as a bridge between the AI tools you already use and your Clara account.
**Does my token work across multiple AI tools simultaneously?**\
Yes. Your token is personal and can be used in multiple AI tools at the same time. If you revoke it, it stops working in all tools at once.
**Why is it in Beta?**\
Clara MCP is fully functional, but the toolset is still expanding significantly. The available tools will grow in the coming weeks.
**What happens if I had Clara MCP connected with the previous method (token)?**\
Previous static tokens are no longer valid with the current MCP server. You'll need to reconnect your AI tool using the OAuth login flow β see the migration steps for your tool in the [Quickstart](/mcp/quickstart).
**How do I revoke access for a connected AI tool?**\
There isn't a self-service screen to view or revoke individual AI sessions yet. Contact Customer Happiness or the Solution Engineering team β they can revoke access for all connected AI tools immediately.
**What if I think my account was compromised?**\
Change your Clara password as a precaution, and contact Customer Happiness or the Solution Engineering team right away β they can revoke access for all connected AI tools on their end.
**Do I need to log in separately for each AI tool?**\
Yes. Each tool you connect will ask you to log in with your Clara account independently, but they all use the same user and permissions.
# MCP Quickstart
Source: https://developers.clara.team/mcp/quickstart
Connect Claude Desktop, Claude Web, Claude Code, or any MCP-compatible tool to Clara in minutes.
## Before You Start
You need an active Clara account with the **Admin** or **Bookkeeper** role. No token or API key required β you'll authenticate directly with your Clara account (the same login you use on the platform) during setup.
***
## Server URLs by Country
Each Clara market has its own MCP server URL. Use the one that matches your Clara account:
| Country | MCP Server URL |
| -------- | --------------------------- |
| Mexico | `https://mx.clara.team/mcp` |
| Brazil | `https://br.clara.team/mcp` |
| Colombia | `https://co.clara.team/mcp` |
All servers use the same **OAuth login flow** β no custom headers or static tokens required.
***
## Option A β Claude Web / Claude Desktop (Recommended)
The setup process is identical for Claude Web and Claude Desktop.
### New Users
On Team/Enterprise Claude accounts, your organization may restrict custom connector setup to Administrators only.
1. Go to **Settings β Connectors**.
2. In the top-right corner, click **Add β Add custom connector**.
3. Enter a name (e.g. "Clara MX") and the MCP server URL for your country.
4. Click **Add**, then **Connect** β you'll be redirected to the Clara login screen.
5. Complete the login with your Clara account.
Once connected, Claude will list `clara-mcp` among its available tools.
### Existing Users / Migration
If you had Clara MCP configured with the previous token-based setup:
**Claude Desktop** β instead of `supergateway`, use `mcp-remote`, which supports the OAuth flow:
```json theme={null}
{
"mcpServers": {
"clara-mcp": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://mx.clara.team/mcp"
]
}
}
}
```
```json theme={null}
{
"mcpServers": {
"clara-mcp": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://br.clara.team/mcp"
]
}
}
}
```
```json theme={null}
{
"mcpServers": {
"clara-mcp": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://co.clara.team/mcp"
]
}
}
}
```
Restart Claude Desktop completely (**File β Quit**, not just close the window). On reopening, a login window will open automatically β complete it with your Clara account.
This config file no longer stores any credentials β there's no token to protect. Authentication happens through the login window, not the config file.
**Claude Web** β remove your previous connector configuration and follow the **New Users** steps above.
### Test It
Ask Claude something like:
* "List my Clara cards"
* "Show my last 10 transactions"
* "Lock the card ending in 3540"
Claude will connect to Clara in real time and respond.
***
## Option B β Claude Code (CLI)
### New Users
1. In a terminal (outside Claude Code), run:
```bash theme={null}
claude mcp add --transport http clara-mx https://mx.clara.team/mcp
```
```bash theme={null}
claude mcp add --transport http clara-br https://br.clara.team/mcp
```
```bash theme={null}
claude mcp add --transport http clara-co https://co.clara.team/mcp
```
2. Open Claude Code and run `/mcp` to select the Clara MCP server.
3. Select **Authenticate** β you'll be redirected to the OAuth login flow. Complete it with your Clara account.
### Existing Users / Migration
The previous token header is no longer recognized by the new MCP server. Follow the **New Users** steps above to reconnect β you'll need to log in again.
***
## Option C β ChatGPT
### Enable Custom Connectors
1. Go to **Profile β Settings β Security & Login**.
2. Turn on **Developer Mode**.
### Add Clara MCP
1. Go to **Plugins** and click the **+** button in the top-right corner.
2. Enter:
* **Name:** "Clara MX" (or "Clara CO", "Clara BR") β this is just a label.
* **Connection:** the MCP server URL for your country.
* **Authentication:** OAuth.
3. Click **Create**. A modal will appear β click **Log in with Clara MX**, which redirects you to the OAuth login flow.
4. Complete the login with your Clara account.
***
## Option D β Other MCP-Compatible Tools (Gemini, etc.)
Clara MCP uses the standard MCP protocol with OAuth authentication, so it works with any compatible tool that supports remote MCP connectors:
1. Find the "Connectors" or "Integrations" section in your tool.
2. Add a new custom connector.
3. Enter the MCP server URL for your country.
4. Complete the OAuth login flow when prompted.
If you run into issues with a specific tool, contact support.
***
## Managing Multiple Companies
If you have access to more than one company in Clara, connecting logs you into the last company you used on web/mobile. To switch companies within the same conversation, just ask your assistant:
* "What companies do I have access to?"
* "Switch to \[company name]"
***
## Verify Your Connection
Once configured in any tool, test by asking:
> "List my Clara cards"
If you see a list of cards from your company account, you're connected correctly.
***
## Troubleshooting
**Asked to log in again**
* Your session expired β this is normal, just re-authenticate.
**"No tools found" or Clara MCP doesn't appear**
* Make sure you fully restarted the AI tool after connecting (quit and reopen, not just refresh).
* Confirm that `npx` is available in your terminal (Claude Desktop config-file setup only).
**Had Clara MCP connected before and it stopped working**
* The previous static-token method is no longer valid. Follow the migration steps for your tool above to reconnect via OAuth.
**"Connection refused" or server unreachable**
* Check your internet connection.
* The Clara MCP server may be temporarily unavailable β try again in a few minutes.
**Lock/unlock returns a simple "Ok" message**
* This is a known Beta limitation. The operation executed correctly even if the response looks plain. The card was locked/unlocked successfully.
**Transaction count shows 0**
* Known Beta issue with the summary counter. Actual transactions are returned correctly in the list.
***
## Access & Security
* There's no separate token to generate, store, or lose β your MCP access is tied to your Clara login session.
* There's no self-service revocation yet β to revoke access for a connected AI tool, request it via Customer Happiness (in-platform chat or [contacto@clara.com](mailto:contacto@clara.com)) or the Solution Engineering team. Access is cut off immediately across all connected tools.
# MCP Tools Reference
Source: https://developers.clara.team/mcp/tools
Technical reference for the tools exposed by Clara MCP β parameters, behavior, and example outputs.
Clara MCP is in Beta. The toolset will expand significantly in the coming weeks to cover expenses, reimbursements, limits, and approvals.
## Authentication
All tools run within an authenticated session established via OAuth login when you connect your AI tool β see [Quickstart](/mcp/quickstart). There's no API key or custom header to configure.
The session is scoped to a single company at a time β the last company you used on web/mobile, or whichever you've switched to with `switch_company`. Tools return data for that active company only.
Supported roles: **Admin**, **Bookkeeper**. Other roles are not supported in this version.
***
## list\_cards
Returns all corporate cards for the company.
**No input parameters required.**
### Example Output
```json theme={null}
[
{
"cardholderName": "Ana GarcΓa",
"lastFourDigits": "3540",
"status": "ACTIVE",
"spendingLimit": 10000.00,
"currency": "MXN"
},
{
"cardholderName": "Luis PΓ©rez",
"lastFourDigits": "7821",
"status": "LOCKED",
"spendingLimit": 5000.00,
"currency": "MXN"
}
]
```
### Example Prompts
* "List all my corporate cards"
* "Which cards are currently locked?"
* "List all cards with a spending limit above \$10,000"
* "Show me the card assigned to Ana GarcΓa"
***
## list\_transactions
Returns card transactions for the company, with optional filters.
### Filters (Optional)
| Filter | Type | Format | Example |
| ---------- | ---------------- | ------------------------------------------------------------------------------------ | -------------------------------------------- |
| Card | string | Cardholder name or last 4 digits of card number | "transactions on card 3540" |
| Date range | string (date) | ISO 8601 (`YYYY-MM-DD`) or relative ("last 30 days", "this month") | "transactions from 2026-04-01 to 2026-04-30" |
| Amount | number (decimal) | Currency units, not cents. Comparison operators supported (over, under, between) | "transactions over 5000" |
| Category | string (enum) | MCC category name: `TRAVEL`, `FOOD`, `SOFTWARE_AND_HARDWARE`, `TRANSPORTATION`, etc. | "travel expenses last 90 days" |
Filters can be combined freely in natural language β the AI assistant resolves them before calling the tool.
**Edge cases:**
* If no date range is specified, results default to the current billing period.
* If no results match the filters, the tool returns an empty `transactions` array β not an error.
* `totalCount` reflects the number of transactions returned, not the total in the account.
### Example Output
```json theme={null}
{
"transactions": [
{
"id": "txn_abc123",
"date": "2026-05-15T14:32:00Z",
"amount": 1250.00,
"currency": "MXN",
"merchant": "Aeromexico",
"category": "TRAVEL",
"cardLastFour": "3540",
"cardholderName": "Ana GarcΓa",
"status": "APPROVED"
}
],
"totalCount": 42
}
```
### Example Prompts
* "Show my transactions this month"
* "What were the top 5 vendors this quarter by total spend?"
* "Show all transactions labeled as travel expenses in the last 90 days"
* "What were our company's top spending categories last month?"
* "Show me the last 10 transactions on the card assigned to Ana GarcΓa"
***
## lock\_card
Immediately locks a specific card. The cardholder cannot make purchases while the card is locked.
### Input
The card can be identified by cardholder name or last 4 digits. The AI assistant resolves the card before calling the tool.
### Behavior
* The lock takes effect immediately.
* In Beta, the confirmation response may appear as plain text ("Ok") rather than a structured message. The operation completes correctly regardless.
* The card can be unlocked at any time using `unlock_card`.
### Example Prompts
* "Lock the card ending in 3540 immediately"
* "Lock Luis PΓ©rez's card"
* "Block the card assigned to the marketing team"
***
## unlock\_card
Immediately unlocks a previously locked card.
### Input
The card can be identified by cardholder name or last 4 digits.
### Behavior
* The unlock takes effect immediately.
* Same Beta display limitation as `lock_card` β the operation completes correctly.
### Example Prompts
* "Unlock the card ending in 7821"
* "Unblock Ana GarcΓa's card"
***
## upload-transaction-document
Attaches a document (e.g. an invoice or receipt) to a specific Clara transaction.
### Input
| Field | Description | Example |
| ----------------- | --------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
| Transaction | The transaction to attach the document to. The AI assistant resolves this to the transaction before calling the tool. | "the Aeromexico charge from last week" |
| File | The document to upload, provided by the user in the conversation. | `factura.pdf` (PDF) |
| Document category | The type of document being attached. | `INVOICE` |
### Behavior
* Before uploading, the assistant confirms the document matches the intended transaction (e.g. by amount, vendor, or date) to avoid attaching the wrong file.
* The file is submitted along with its original file name and MIME type.
* If no transaction match can be confirmed, the assistant asks for clarification instead of uploading blindly.
### Example Prompts
* "Attach this invoice to the Aeromexico transaction from last week"
* "Upload this receipt to my last Uber charge"
* "Add this PDF as supporting documentation for transaction \[ID]"
***
## list\_companies
Returns the companies the authenticated user can access, and marks which one is currently active.
**No input parameters required.**
### Behavior
* If you only have access to one company, this returns a single entry.
* The company marked active is the one your session is currently scoped to β all other tools operate on this company until you switch.
### Example Prompts
* "What companies do I have access to?"
* "Which company am I currently connected to?"
***
## switch\_company
Changes the active company for the rest of the session. All subsequent tool calls operate on the newly selected company.
### Input
The company can be identified by name. The AI assistant resolves it against the list from `list_companies` before calling the tool.
### Behavior
* The switch applies immediately and persists for the rest of the session β until you switch again or start a new session.
* If you don't have access to the requested company, the tool returns an error rather than switching.
### Example Prompts
* "Switch to \[company name]"
* "Connect me to my other company instead"
***
## Coming Soon
The following capabilities are planned for upcoming Beta releases:
* Expense management and categorization
* Reimbursement requests and status
* Spending limit adjustments
* Approval workflows
* Budget overview by department or cost center
# Sandbox
Source: https://developers.clara.team/sandbox
Test your integration against Clara's sandbox environment before going to production.
Clara provides a sandbox environment for testing your integration end-to-end without affecting real data or triggering real financial operations.
## Sandbox Base URLs
The sandbox uses the same base domain as production, with `/api-test/` instead of `/api/` in the path:
| Market | Sandbox Base URL |
| -------- | ------------------------------------------- |
| Mexico | `https://public-api.mx.clara.com/api-test/` |
| Brazil | `https://public-api.br.clara.com/api-test/` |
| Colombia | `https://public-api.co.clara.com/api-test/` |
### Example
```bash theme={null}
# Production
GET https://public-api.mx.clara.com/api/v3/transactions
# Sandbox
GET https://public-api.mx.clara.com/api-test/v3/transactions
```
## Authentication in Sandbox
Authentication works identically to production β you still need a valid mTLS client certificate and a Bearer token obtained from the OAuth endpoint. Sandbox and production share the same auth flow.
```bash theme={null}
curl --request GET \
"https://public-api.mx.clara.com/api-test/v3/transactions?page=0&size=10" \
--header "Authorization: Bearer " \
--cert client.crt \
--key client.key
```
## Getting Sandbox Credentials
Sandbox credentials are separate from production credentials. Contact your Clara integration team to request access:
| Country | Contact |
| -------- | ----------------------------------------------------------------------------- |
| Mexico | [integration.support.mx@clara.team](mailto:integration.support.mx@clara.team) |
| Brazil | [integration.support.br@clara.team](mailto:integration.support.br@clara.team) |
| Colombia | [integration.support.co@clara.team](mailto:integration.support.co@clara.team) |
## What You Can Test
The sandbox supports the same endpoints as production. You can test:
* Card creation, configuration, lock/unlock, and deletion
* Transaction retrieval with filters and pagination
* User management
* Billing statement retrieval
* VCN lifecycle (create, update, cancel)
## Differences from Production
| Behavior | Production | Sandbox |
| -------------------- | -------------------------- | --------------------------------- |
| Financial operations | Real | Simulated β no real money moves |
| Card issuance | Physical cards are shipped | No physical fulfillment |
| Data | Your company's live data | Isolated test data |
| Webhooks | Live events | May have delays or be unavailable |
Sandbox data is periodically reset. Do not build long-running dependencies on sandbox UUIDs or state β treat each test session as ephemeral.
# Troubleshooting Guide
Source: https://developers.clara.team/troubleshooting
# Clara API β Troubleshooting Guide
This guide is intended to help you configure and troubleshoot your integration with the Clara API. It covers the initial setup, mutual TLS (mTLS) requirements, common errors and their solutions, multi-entity usage, and network diagnostics.
***
## Table of Contents
1. [Getting Started with Postman](#1-getting-started-with-postman)
2. [Understanding mTLS](#2-understanding-mtls)
3. [Common Errors and Solutions](#3-common-errors-and-solutions)
4. [Network Diagnostics](#5-network-diagnostics)
***
## 1. Getting Started with Postman
Follow these steps to configure Postman and make your first authenticated request to the Clara API.
### Step 1 β Import the API Specification
Download the latest Clara API JSON specification file. This file contains all available endpoints and is required for the Postman configuration.
Open Postman β **Import** β select the JSON file β all endpoints will be available in your collection.
***
### Step 2 β Configure Certificates
The Clara API requires mTLS on most endpoints. You must configure your client certificates in Postman before making requests.
Go to **Postman β Settings β Certificates** and add the following:
| Field | Value |
| ---------------------- | --------------------------------------- |
| **Host** | `public-api..clara.com` |
| **Port** | `443` |
| **Client Certificate** | Your client public certificate (`.crt`) |
| **Client Key** | Your client private key (`.key`) |
> **Country codes:** `mx` = Mexico, `co` = Colombia, `br` = Brazil
>
> Example host: `public-api.mx.clara.com`
***
### Step 3 β Authenticate with OAuth 2.0
The Clara API uses OAuth 2.0. To obtain an access token:
1. In Postman, open any endpoint from the collection.
2. Go to the **Authorization** tab and select **OAuth 2.0**.
3. Under **Configure New Token**, fill in:
* **Access Token URL:** `https://public-api..clara.com/oauth/token`
* **Client ID:** provided by Clara
* **Client Secret:** provided by Clara
4. Click **Get New Access Token** and then **Use Token**.
The resulting JWT will be sent as a `Bearer` token in the `Authorization` header on all subsequent requests.
***
### Step 4 β Make Your First Request
With certificates and token in place, you can now call any endpoint. A successful response confirms your setup is correct.
**Expected result:** HTTP `200 OK` with the requested data in the response body.
***
## 2. Understanding mTLS
### What is mTLS and why does Clara use it?
Standard HTTPS (TLS) only requires the **server** to present a certificate to the client. Mutual TLS (mTLS) goes further β it requires **both** the server and the client to present valid certificates during the handshake. This provides a strong, certificate-based identity verification for every connection, ensuring that only authorized clients can access the API.
For a deeper explanation, see [Cloudflare's guide on mTLS](https://www.cloudflare.com/learning/access-management/what-is-mutual-tls/).
***
### Connection Scenarios
**Case 1 β No client certificate (incorrect)**
The client sends a request without a certificate. The server rejects the connection with `HTTP 511`.
```bash theme={null}
# This will fail with HTTP 511 on mTLS-protected endpoints
curl -v https://public-api.mx.clara.com/api/v3/transactions \
-H "Authorization: Bearer "
```
**Case 2 β With client certificate (correct)**
The client presents a valid Clara-issued certificate. The connection is accepted.
```bash theme={null}
# Correct configuration
curl -v https://public-api.mx.clara.com/api/v3/transactions \
--cert /path/to/public-key.crt \
--key /path/to/private-key.key \
-H "Authorization: Bearer "
```
***
### Endpoints that do NOT require mTLS
The following endpoints are accessible without client certificates and can be used to verify basic connectivity:
* **Health check:** `GET https://public-api..clara.com/v2/health`
* **Token generation:** `POST https://public-api..clara.com/oauth/token`
Use the health check endpoint to confirm network connectivity and TLS configuration before troubleshooting certificate issues.
***
## 3. Common Errors and Solutions
### HTTP 511 β Network Authentication Required
**Cause:** No client certificate is being sent.
**Solution:** Configure your HTTP client to present the Clara-issued client certificate on every request. Simply importing the certificate into your system's keystore is **not sufficient** β the HTTP client itself must be explicitly configured to use the certificate.
***
### HTTP 406 β Not Acceptable
**Cause:** A client certificate is being sent, but it was not issued by Clara.
**Solution:** Verify that you are using the exact certificate provided by Clara. Certificates from other issuers will be rejected.
***
### Java β PKIX Path Building Failed
If you are using a Java-based client and see the following error:
```
javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException:
PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException:
unable to find valid certification path to requested target
```
**Cause:** The truststore used by your HTTP client does not contain Clara's CA certificate. Note that this error comes from your client, not from the Clara server.
**Steps to resolve:**
1. **Verify the server certificate chain** by running this command from your environment:
```bash theme={null}
openssl s_client -connect public-api.mx.clara.com:443 \
-servername public-api.mx.clara.com -showcerts ` with your region (`mx`, `co`, or `br`).
***
### Windows (PowerShell / CMD)
```powershell theme={null}
# 1. Ping (20 packets)
ping public-api..clara.com -n 20 > ping.txt
# 2. Traceroute
tracert public-api..clara.com > traceroute.txt
# 3. TCP port test
Test-NetConnection -ComputerName public-api..clara.com -Port 443 > tcp_test.txt
# 4. Verbose curl (HTTPS debug)
curl -v https://public-api..clara.com/v2/health > curl.txt 2>&1
# 5. TLS version tests
curl -v --tls-max 1.2 https://public-api..clara.com/v2/health > curl_tls12.txt 2>&1
curl -v --tls-max 1.3 https://public-api..clara.com/v2/health > curl_tls13.txt 2>&1
# 6. DNS resolution
nslookup public-api..clara.com > dns.txt
# 7. OpenSSL TLS handshake (if available)
openssl s_client -connect public-api..clara.com:443 -servername public-api..clara.com -brief > sclient.txt 2>&1
```
***
### Linux / macOS
```bash theme={null}
# 1. Ping (20 packets)
ping -c 20 public-api..clara.com > ping.txt
# 2. Traceroute
traceroute public-api..clara.com > traceroute.txt
# 3. MTR (optional, more detailed)
mtr -rwzbc 100 public-api..clara.com > mtr.txt
# 4. Verbose curl (HTTPS debug)
curl -v https://public-api..clara.com/v2/health > curl.txt 2>&1
# 5. TLS version tests
curl -v --tls-max 1.2 https://public-api..clara.com/v2/health > curl_tls12.txt 2>&1
curl -v --tls-max 1.3 https://public-api..clara.com/v2/health > curl_tls13.txt 2>&1
# 6. DNS resolution
dig public-api..clara.com > dns.txt
# or
nslookup public-api..clara.com > dns.txt
# 7. OpenSSL TLS handshake
openssl s_client -connect public-api..clara.com:443 \
-servername public-api..clara.com -brief > sclient.txt 2>&1
# 8. TCP port test
nc -vz public-api..clara.com 443 > tcp_test.txt 2>&1
# 9. MTU test (optional)
ping -c 4 -M do -s 1400 public-api..clara.com > mtu.txt 2>&1
```
***
> If you still experience issues after following this guide, please contact Clara support and attach the diagnostic output files.
# VCN API: Introduction
Source: https://developers.clara.team/vcn/introduction
Virtual Card Numbers (VCNs) for controlled B2B purchasing β how they work, key concepts, and authentication.
Clara's VCN API enables companies to generate Virtual Card Numbers (VCNs) for controlled purchases, recurring subscriptions, and digital transactions. All charges made to a VCN are automatically debited from its associated Real Card Number (RCN).
## Key Concepts
| Concept | Description |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| **RCN (Real Card Number)** | The actual funding card linked to your company. Required to generate VCNs. |
| **VCN (Virtual Card Number)** | A virtual card generated from an RCN. Has its own PAN, CVV, and expiry. Intended for a specific purchase or supplier. |
| **Template** | Defines the rules and parameters for a VCN β spending limits, expiration, allowed merchant categories, currency controls, and custom fields. |
| **Supplier** | The vendor or merchant associated with a purchase. |
| **Purchase** | A VCN creation request tied to an RCN, template, and supplier. Identified by `purchaseId`. |
## How VCNs Work
1. **Configure**: An RCN and one or more templates are set up during the VCN onboarding process.
2. **Retrieve**: Call `GET /api/v1/vcn` to get available RCNs, templates, and suppliers for your company.
3. **Create**: Call `POST /api/v1/vcn/submit` with a template, RCN, and supplier to generate a VCN.
4. **Use**: The VCN (PAN + CVV + expiry) is used for the purchase. Charges flow back to the RCN.
5. **Update or Cancel**: Adjust limits with `POST /api/v1/vcn/{purchaseId}/update` or void with `POST /api/v1/vcn/cancel`.
6. **Reconcile**: Generate and retrieve reports via `POST/GET /api/v1/vcn/report`.
## Authentication and Security
The VCN API uses the same dual-layer authentication as all Clara APIs.
| Component | Protocol | Purpose |
| --------------------- | ------------- | ----------------------------------------------------------------------------------- |
| **Mutual TLS (mTLS)** | TLS handshake | Verifies the identity of both the client and the API gateway at the transport layer |
| **OAuth 2.0 + JWT** | Authorization | Client authenticates with the Auth Server and receives a JWT Bearer token |
**Token Request:**
```bash theme={null}
curl --location --request POST 'https://public-api.mx.clara.com/oauth/token' \
--header 'Authorization: Basic base64(CLIENT_ID:CLIENT_SECRET)'
```
## Endpoint Overview
| Method | Endpoint | Description |
| ------ | --------------------------------- | ------------------------------------------------- |
| `GET` | `/api/v1/vcn` | Retrieve available RCNs, templates, and suppliers |
| `POST` | `/api/v1/vcn/submit` | Generate a new VCN for a controlled purchase |
| `POST` | `/api/v1/vcn/{purchaseId}/update` | Update VCN parameters (limit, supplier) |
| `POST` | `/api/v1/vcn/cancel` | Cancel/void one or more VCNs |
| `POST` | `/api/v1/vcn/report` | Trigger a reconciliation report |
| `GET` | `/api/v1/vcn/report` | Poll for report results |
| `GET` | `/api/v1/vcn/{purchaseId}` | Retrieve purchase details by ID |
## Sandbox
A sandbox environment is available for testing:
* `GET /api-test/v1/vcn/{path}` β Sandbox read operations
* `POST /api-test/v1/vcn/{path}` β Sandbox write operations
Contact your Clara integration support team for sandbox credentials.
# VCN Lifecycle Walkthrough
Source: https://developers.clara.team/vcn/lifecycle
Step-by-step guide to creating, using, updating, canceling, and reconciling VCNs β with full request and response examples.
## Overview
A VCN goes through a predictable lifecycle: retrieve company configuration β create the VCN β optionally update it β cancel if unused β reconcile at month end. Each step maps to a specific endpoint.
***
## Step 1: Retrieve Company Configuration
Before creating a VCN, fetch the available RCNs, templates, and suppliers for your company. The IDs returned here are required in subsequent requests.
**Endpoint:** `GET /api/v1/vcn`
### Query Parameters
| Parameter | Type | Values |
| --------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `companyDetail` | string | `ALL` β returns rcns, suppliers, and templates
`RCN` β returns only real card numbers
`TEMPLATE` β returns only templates
`SUPPLIER` β returns only suppliers |
### Example Request
```bash theme={null}
GET /api/v1/vcn?companyDetail=ALL
```
### Example Response (`CompanyResponseVO`)
```json theme={null}
{
"rcns": [
{
"id": 38105,
"alias": "Clara Card Black"
}
],
"suppliers": [
{
"id": 47401,
"name": "Clara Supplier"
}
],
"templates": [
{
"id": 50631,
"name": "Clara Hotels",
"description": "Group for hotels",
"type": "PC",
"icmpEnabled": false,
"purchaseTypes": [
{
"mcc": "3501",
"description": "HOLIDAY INNS"
}
],
"rules": [
{
"name": null,
"type": null,
"controls": [
{ "code": "VA", "description": "Validity" },
{ "code": "VL", "description": "Velocity" }
]
}
],
"customFields": [
{
"name": "Purchase Type",
"maxLength": 69,
"displayType": "Text",
"dataType": "Alphanumeric",
"required": "Y"
}
]
}
]
}
```
***
## Step 2: Create a Virtual Card
Generate a new VCN for a controlled purchase. The VCN (PAN + AVV + expiry) is returned immediately and is ready for use.
**Endpoint:** `POST /api/v1/vcn/submit`
### Request Body (`VCNRequestVO`)
| Field | Type | Required | Notes |
| -------------- | ------- | ----------- | -------------------------------------------------------------------- |
| `rcnId` | integer | Yes | Real Card Number ID β query from `GET /api/v1/vcn` |
| `templateId` | integer | Yes | Template ID β query from `GET /api/v1/vcn` |
| `supplierId` | integer | Yes | Supplier ID β query from `GET /api/v1/vcn` |
| `description` | string | Yes | Description of the purchase |
| `validFor` | integer | No | VCN validity in months |
| `customFields` | list | Conditional | Required if the template has required custom fields |
| `rule` | object | No | Spending controls for this VCN (see [Control Types](#control-types)) |
### Control Types
Controls inside `rule` must match the controls configured in the template. Sending an unsupported control returns `400 Invalid rule control {}`.
| Code | Control |
| ---- | ------------------------- |
| `AR` | Amount range control |
| `CU` | Curfew control |
| `GE` | Geography control |
| `MI` | Merchant ID control |
| `TD` | Time of day control |
| `TL` | Transaction limit control |
| `VA` | Validity period control |
| `VG` | Aging velocity control |
| `VL` | Velocity control |
### Example Request Body
```json theme={null}
{
"rcnId": 13800,
"validFor": 12,
"description": "My Purchase Request",
"templateId": 21680,
"supplierId": 14100,
"customFields": [
{
"name": "Invoice Number",
"value": "1231456"
}
],
"rule": {
"name": "My rule",
"type": "A",
"velocityControl": [
{
"maxTrans": 1,
"cumulativeLimit": 500.10,
"period": "C",
"currencyType": "B",
"currencyCode": "840"
}
],
"agingVelocityControl": {
"authorizationHoldDays": 10,
"cumulativeLimit": 1,
"timeZone": "Europe/London",
"negate": false,
"availableBalance": 651.10,
"currencyType": "B",
"currencyCode": "840"
},
"validityPeriodControl": {
"from": "20150504",
"to": "20150531",
"timeZone": "Europe/Luxembourg",
"strictPreAuthCheck": false,
"negate": false
},
"transactionLimitControl": {
"amount": 1000.55,
"negate": false
},
"timeOfDayControl": {
"days": [
{
"day": "Tue",
"fromTime": "0800",
"toTime": "1300"
}
],
"negate": true,
"timeZone": "Europe/Luxembourg"
},
"merchantIdControl": {
"negate": false
},
"geographyControl": {
"countryCode": ["AFG", "USA"],
"negate": true
},
"curfewControl": {
"fromTime": "0830",
"toTime": "1800",
"timeZone": "Europe/Luxembourg",
"negate": false,
"daysOfWeek": ["MON", "WED"]
},
"amountRangeControl": [
{
"minAmount": 300,
"maxAmount": 500,
"strictPreAuthCheck": false,
"negate": false,
"currencyType": "B",
"currencyCode": "840"
}
]
}
}
```
### Example Response (`VCNResponseVO`)
```json theme={null}
{
"id": 12345678,
"status": "ACTIVE",
"vcn": {
"id": 0,
"pan": "546920XXXXXX1234",
"avv": "664",
"status": "ACTIVE",
"expiry": "12/28"
},
"merchants": {
"merchantId": "1234",
"acquirerId": 0
}
}
```
Save the `id` (this is the `purchaseId`) β it is required for update, cancel, and lookup operations.
***
## Step 3: Update a Virtual Card
Adjust VCN parameters such as the spending limit or supplier. The entire `VCNRequestVO` must be sent, including all unchanged fields.
**Endpoint:** `POST /api/v1/vcn/{purchaseId}/update`
### Path Parameter
| Parameter | Type | Description |
| ------------ | ------- | ---------------------------------- |
| `purchaseId` | integer | ID returned in the submit response |
The request body and response follow the same structure as [Step 2](#step-2-create-a-virtual-card). All fields must be included even if not changing.
***
## Step 4: Cancel a VCN
Void one or more purchases that were created in error or are no longer needed. Supports batch cancellation.
**Endpoint:** `POST /api/v1/vcn/cancel`
### Example Request Body (`CancelPurchaseRequestVO`)
```json theme={null}
{
"purchasesIds": [123456, 798465, 321546]
}
```
### Example Response (`CancelPurchaseResponseVO`)
```json theme={null}
{
"purchases": [
{
"id": 564565,
"cancelled": true,
"errorMessage": "Error when cancelling"
}
]
}
```
Each purchase in the response includes a `cancelled` boolean and an `errorMessage` if the cancellation failed.
***
## Step 5: Reconciliation Reports (Polling Flow)
Reconciliation is a two-step polling flow: trigger the report, then poll for results.
### 5A. Create Report (Trigger)
**Endpoint:** `POST /api/v1/vcn/report`
| Field | Type | Notes |
| ----------------- | ------ | ----------------------------------------------------------------------- |
| `fromDate` | string | Start date β format `YYYYMMDD` |
| `toDate` | string | End date β format `YYYYMMDD` |
| `fromTime` | string | Start time β format `HHMM` (optional) |
| `toTime` | string | End time β format `HHMM` (optional) |
| `timeZone` | string | IANA time zone (e.g., `Europe/Luxembourg`) |
| `reportType` | string | Enum: `Authorization` \| `Clearing` \| `ClearingExceptions` |
| `transactionType` | string | Mastercard transaction type enum. Not required for `ClearingExceptions` |
| `pan` | string | Filter to a specific VCN PAN (optional) |
#### Example Request Body
```json theme={null}
{
"fromDate": "20220822",
"toDate": "20220822",
"fromTime": "1415",
"toTime": "1515",
"timeZone": "Europe/Luxembourg",
"transactionType": "ALL",
"pan": "5582351302749637",
"reportType": "Authorization"
}
```
#### Example Response (`ReportResponseVO`)
```json theme={null}
{
"reportId": 1055,
"systemMessage": "Create VCN authorizations report has been submitted"
}
```
Save the `reportId` to poll for results.
***
### 5B. Get Report Data (Poll)
Poll until `status` is `Completed`. The `from`/`to` range controls pagination β the difference must not exceed 100.
**Endpoint:** `GET /api/v1/vcn/report`
| Parameter | Type | Description |
| ---------- | ---------- | --------------------------------------- |
| `reportId` | BigInteger | ID from the create response |
| `from` | BigInteger | Start index for pagination |
| `to` | BigInteger | End index (max diff of 100 from `from`) |
#### Example Request
```
GET /api/v1/vcn/report?reportId=12345&from=0&to=50
```
#### Example Response (`ReportVO`)
The `transactions` array is populated for `Authorization` and `Clearing` reports. The `accountSummary` array is populated for `ClearingExceptions` reports.
```json theme={null}
{
"hasMore": false,
"from": 0,
"to": 99,
"status": "Completed",
"transactions": [
{
"purchaseRequestId": 100,
"purchaseRequestStatus": "Approved",
"realCardAlias": "20230510",
"realCardNumber": "XXXX XXXX XXXX 3847",
"virtualCardNumber": "XXXX XXXX XXXX 1132",
"vcnExpiry": "2505",
"requestorName": "AnitaCPA2",
"billingAmount": 11.00,
"billingCurrencyCode": "GBP",
"billingCurrencyCodeDescription": "POUND STERLING",
"merchantAmount": 11.00,
"merchantCurrencyCode": "USD",
"merchantCurrencyCodeDescription": "U.S. DOLLAR",
"clearingType": "Debit",
"txnExchangeRate": "1",
"txnDateTime": "0510",
"txnDateTimeWithTime": "1028T094103.000Z",
"settlementDate": "20150610",
"txnType": "FirstPresentment",
"txnSubType": "Regular",
"txnEnvironment": "ECOM",
"issuerResponse": "Approved or completed successfully",
"avsResponseCode": "1300",
"inControlResponse": "Approval",
"approvalCode": "111111",
"mcc": "3000",
"mccDescription": "UNITED AIRLINES",
"merchantId": "111111999674",
"merchantTerminalId": "98123456",
"merchantName": "PaulsPikes",
"additionalMerchantName": "Smith",
"merchantStreetAddress": "STREET",
"merchantCity": "CITY",
"merchantState": "MO",
"merchantPostalCode": "462354",
"merchantCountryCode": "008",
"merchantCountry": "UNITED STATES",
"acquirerICA": "111111",
"processorICA": "322222",
"terminalId": "98123456",
"settled": "Settled",
"incontrolIssuerId": "2",
"companyName": "AnitaCompany1",
"companyNumber": "146781",
"acquirerReferenceData": "003822995070071000114810",
"messageType": "1240",
"functionCode": "200",
"messageReasonCode": "1401",
"settlementAmount": 100.50,
"settlementCurrencyCode": "826",
"settlementCurrencyDescription": "POUND STERLING",
"icmpUserFirstName": "first",
"icmpUserLastName": "last",
"icmpUserEmail": "first.last@domain.com",
"icmpUserPhoneCountryCode": "11",
"icmpUserMobileNumber": "111111111",
"tokenPan": "XXXX XXXX XXXX 1234"
}
],
"accountSummary": [
{
"cpnPan": "5582351753081639",
"currencyCode": "840",
"cpnType": "MA",
"lastAuthDate": "20230510T072239.00Z",
"settledUsage": 1,
"settledAmount": 10,
"lastSettledDate": "20230510T072239.00Z",
"preAuthUsage": 1,
"createdDate": "20230510",
"updatedDate": "20230510",
"createdBy": "AnitaCPA2",
"issuerId": "3245623",
"cpnState": "Approved",
"authAmount": 10,
"authUsage": 1,
"corporateId": "9764",
"purchaseId": 5274604,
"cumulativeLimit": 100,
"periodType": "C",
"company": "ICCP Company",
"supplier": "ICCP Supplier",
"spendVLimit": 80,
"cdf1Label": "Purchase Type",
"cdf1Value": "P0000167671Airlines",
"icmpUserFirstName": "first",
"icmpUserLastName": "last",
"icmpUserEmail": "first.last@domain.com",
"tokenPan": "XXXX XXXX XXXX 1234"
}
]
}
```
***
## Retrieve Purchase by ID
Fetch the full details of a specific VCN purchase, including the VCN itself and all applied rules.
**Endpoint:** `GET /api/v1/vcn/{purchaseId}`
| Parameter | Type | Description |
| ------------ | ---------- | ------------------ |
| `purchaseId` | BigInteger | ID of the purchase |
### Example Response (`PurchaseResponseVO`)
```json theme={null}
{
"id": 165464,
"status": "Approved",
"merchantId": 5465464,
"acquirerId": 5441324,
"rcnId": 123123,
"supplierId": 32134,
"templateId": 132134,
"validFor": 12,
"description": "My Purchase Request",
"customFields": [
{
"name": "Invoice Number",
"value": "1231456"
}
],
"vcn": {
"id": 4651231,
"pan": "5412753456999975",
"expiry": "2601",
"avv": "664",
"status": "S"
},
"rule": {
"name": "My rule",
"type": "A",
"velocityControl": [
{
"maxTrans": 1,
"cumulativeLimit": 500.10,
"period": "C",
"currencyType": "B",
"currencyCode": "840"
}
]
}
}
```
# Changelog
Source: https://developers.clara.team/versioning
History of API changes and field updates.
### 24 Mar 2026 Cards Configuration V2 service - time adjustment
The Cards Configuration V2 service has been updated to handle default time values when inserting or updating a Period configuration.
Previously, if `startTime` or `endTime` were not provided in the request, the service defaulted to the current time at the moment of the operation. This behavior was incorrect for period-based configurations.
**New behavior:**\
Whenever a Period configuration is created or updated, if `startTime` or `endTime` are `null` or empty, the service will now apply the following defaults:
* `startTime` β `00:00`
* `endTime` β `23:59`
**Action required:**\
No changes are required on the consumer side. However, if `startTime` and `endTime` are treated as mandatory fields in your integration, ensure they are explicitly sent as `00:00` and `23:59` respectively for full-day period cases, rather than relying on empty or null values.
π Affected Endpoints:
* POST /api/v2/cards//configurations
* PATCH /api/v2/cards//configurations
```json RequestBody theme={null}
{
"period":{
"startDate": "2026-03-19",
"endDate": "2026-05-21",
"startTime": null,
"endTime": null,
"enableAutoDeletion": false
},
"atmCashLimit": 0.0,
"weekdays": null,
"merchants": null
}
```
***
### 9 Feb 2026 Enable Configuration and Threshold Updates for Locked, Frozen, and Restricted Cards
π Affected Endpoints:
* POST /api/v2/cards//configurations
* PATCH /api/v2/cards//configurations
* DELETE /api/v2/cards//configurations
* POST /api/v3/cards//configurations
* PATCH /api/v3/cards//configurations
* DELETE /api/v3/cards//configurations
* PATCH /api/v2/cards/
* PATCH api/v3/cards/threshold
***
### 12 Jan 2026 Adding Accounting Fields in Transaction V3 services
We've exposed the custom fields property through the API Transactions Service v3, enabling deeper integration and more flexible accounting workflows.
π Affected Endpoints:
* GET /api/v3/transactions
* GET /api/v3/transactions/
* GET /api/v3/billing-statements/current
* GET /api/v3/billing-statements/
```json new Accounting fields theme={null}
{
"content":[{
"uuid": "1614c41b-8eb4-4573-9262-8aff011224c5",
"type": null,
"transactionLabel": "DHL EXPRESS CE",
"labels": [],
"status": null,
"comment": null,
"billingStatement": {
"uuid": null,
"periodStartDate": null,
"periodEndDate": null,
"links": []
},
"accountingFields": [
{
"customFieldUuid": "439671cd-6117-420b-a9e4-f39e994c1cee",
"customFieldName": "Expense Category",
"value": "MAND",
"label": "MANTTO. DE EDIFICIO"
},
{
"customFieldUuid": "439671cd-6117-420b-a9e4-f39e994c1cff",
"customFieldName": "Center Cost",
"value": "COMP",
"label": "COMPRAS"
}
],
"audit":{...},
//...
}]
}
```
This update provides visibility of accounting-related custom fields in transaction and billing statement detail.
***
### 08 Jul 2025 Improved Tax ID Validation for User Management
Weβve introduced enhanced validation rules for user Tax Identifiers based on the userβs country, ensuring data integrity and compliance.
**π Affected Endpoints:**
* [`Create User`](/v3/users)
* [`Update User`](/v3/users)
**π Validation Rules by Country:**
* **MX (Mexico)**: Tax ID must be **11 or 13** digits
* **CO (Colombia)**: Tax ID must be **7, 8, 9, or 10** digits
* **BR (Brazil)**: Tax ID must be **11** digits
Requests that do not comply with these rules will now return a validation error.
This update improves consistency in user data and prepares the system for future compliance checks and integrations.
***
### New 03 Jul 2025`GET Reimbursements` Endpoint
Weβve implemented a new service to retrieve reimbursement records, improving visibility and integration with your internal tools.
**π New Endpoints docs:**
* [`How to use it`](/v3/reimbursements)
* [`Find reimbursements`](/v3/reimbursements)
**π Highlights:**
* Programmatically retrieve reimbursement data by user, status, or time range.
* Supports filtering, sorting, and pagination for scalable integration.
* Enables real-time access to reimbursement information for finance automation and reporting.
This release enhances control and transparency around reimbursement workflows.
***
## 30 Jun 2025 β `Field Update to transactions-v3`
We've updated the `transactions-v3` data model to add the field `hasExtractedDocuments`, this field has two parts one is value that will have true or false and the other one is links that is redirect to the endpoint `extracted-documents`. This change enhances consistency across services and aligns with the broader data model strategy.
### Affected Endpoints:
* [Find all transactions with filters](/v3/transactions)
* [Get a Transaction by UUID](/v3/transactions)
***
## 25 Jun 2025 β `Audit API`
Weβve introduced a new **Audit API** to provide enhanced visibility into API activity and improve observability across the platform.
### New Endpoints
* [Get current month logs](/v1/logs)
* [Get logs by year/month](/v1/logs)
* [Get logs by year/month/day](/v1/logs)
### Highlights:
* Filtered logs only (by date: current month, a specific month and year, or a precise day) - no unfiltered access
* Logs include metadata, such as request URI, method, token, status, chargeability
* Improves monitoring, auditing, and billing visibility
This update is part of our commitment to building transparent and secure systems that empower teams to trace and audit platform activity with precision.
***
## 13 Jun 2025 β `New Receipt Scanner Service`
Weβve introduced a new **Receipt Scanner** service to enhance document processing and data extraction capabilities across the platform.
### New Endpoint:
* [Find documents by transaction UUID](/v3/extracted-documents)
### Highlights:
* Enables retrieval of documents automatically extracted from invoices, receipts, mexican\_fiscal\_invoices and other documents based on the associated transaction UUID.
* Supports tighter integration between scanned receipt, invoices data and transaction records.
* Lays the groundwork for future automation and smart reconciliation features.
This update is part of our ongoing efforts to streamline expense management and improve document intelligence throughout Claraβs ecosystem
***
## 26 May 2025 β `Field Update to cards-v3`
We've updated the `cards-v3` data model to replace the deprecated `claraStatus` field with a new standardized `status` field. This change enhances consistency across services and aligns with the broader data model strategy.
### Affected Endpoints:
* [Find all cards](/v3/cards)
* [Find card by UUID](/v3/cards)
β
\*\*Update: Replace \*\*`claraStatus` with `status` in the API responses for the above endpoints.
β οΈ \*\*Action Required: \*\*Update your integrations accordingly
***
## 15 Jun 2024 β New Fields
### Affected Endpoints:
* Transactions:
* `billingStatement`: Billing statement dates - start, end, and dueDate
* `authorizationNumber`: Number of authorization from a transaction
***
## 06 May 2024 β `New Fields and Endpoints`
### Affected Endpoints:
* \*\*Cards: \*\*Limit adjustment, lock/unlock card (PATCH)
* **Transactions:** Added `authorizationNumber` β It refers to the approval number from MasterCard that is also on the Transactions report in the Clara Platform
***
## 15 Apr 2024 β `Write Mode Launch`
We're introducing **WRITE MODE** functionality for Cards, Labels, and Groups!
With the addition of Write Mode, you now have the ability to not only retrieve data but also create and manage cards, labels, and groups directly through our API. This expansion provides you with greater flexibility and control over your data, enabling you to tailor your applications to better suit your needs.
### Affected Endpoints:
* \*\*Cards: \*\*Create cards with custom rules
* **Groups:** Create/manage groups
* \*\*Labels: \*\*Create labels to classify transactions
***
## 26 Mar 2024 β` User Field Update`
### Affected Endpoints:
* \*\*Users: \*\*Changed userFullName format β We inverted the *First Last Name* and *Second Last Name* `(Only MX and CO)`
***
## 26 Feb 2024 β `Filter Updates`
### Affected Endpoints:
* Transactions: Added `sort` β Sort the results by specific fields and directions. (accountingDate | operationDate),(ASC | DESC)
***
## 21 Feb 2024 β `More Field Updates`
### Affected Endpoints:
* Transactions:
* `maskedPan`: First 6 digits and last 4 digits of the card)
* `cardLastDigits`: Masked Pan Last Digits of the card associated with the transactions)
***
## 19 Feb 2024 β `Attachments and Filters`
### Affected Endpoints:
* Transactions:
* Attachments: Information about the files attached to the transaction
* fileName
* type: TRANSACTIONS\_RECEIPT/TRANSACTIONS\_INVOICE
* hasReceipt: Boolean
* hasInvoice: Boolean
* userErpId: ERP id of the transaction user from the Team panel in Clara's Platform
* username: Username of the transaction user
***
## 08 Feb 2024 β Field Modifications
### Affected Endpoints:
* Transactions:
* `statusCode` β `status`
* `comments` β `comment`
* Removed: `tax` (because it didn't refer to the purchase taxes but rather to transaction values), `expirationDate` (Was a static value. We are creating a new field to bring this expiration value for each transaction)