๐ธ 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
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
{
"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": "[email protected]"
}
}
]
}
๐ 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
- Creation: A reimbursement request is submitted. Initial status:
PENDING
. - Approval: The request may be
APPROVED
orREJECTED
based on validations. - Cancellation: A
PENDING
request can be cancelled, moving toCANCELLED
. - Financial Routing: Once approved, it moves to
SENT_TO_PAY
. - Payment: Transitions to
PAYMENT_IN_PROGRESS
as disbursement begins. - 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.