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