Reimbursements API

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": "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

Creation: A reimbursement request is submitted. Initial status: PENDING.
Approval: The request may be APPROVED or REJECTED based on validations.
Cancellation: A PENDING request can be cancelled, moving to CANCELLED.
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.

Endpoint Reference

`GET /api/v3/reimbursements`

List reimbursements (v3) Parameters:

Parameter	In	Type	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)

​How to Find Reimbursements via Clara API

​Authentication Requirements

​Endpoint

​Query Parameters (Optional)

​Successful Response

​Error Responses

​Example cURL Request

​Example Response Object

​Lifecycle Statuses (ValidationStatus — Reimbursements)

​Lifecycle Flow (Reimbursements)

​Summary

​Endpoint Reference

​GET /api/v3/reimbursements

​GET /api/v3/reimbursements/{uuid}