💸 Reimbursements API: How to Use It

💸 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

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

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

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.