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

# Transactions API

> Retrieve all transactions or find by UUID.

## 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 |

## 1⃣ 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"
  }
]
```

## 2⃣ 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) | |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.