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)

NameTypeDescriptionExample
pageintegerZero-based page index (0..N). Default: 00
sizeintegerThe size of the page to be returned. Default: 2020
requestCreationDateStartstringStart date for request creation (yyyy-MM-dd)2023-01-01
requestCreationDateEndstringEnd date for request creation (yyyy-MM-dd)2023-12-31
expenseDateStartstringStart date for expense (yyyy-MM-dd)2023-01-01
expenseDateEndstringEnd date for expense (yyyy-MM-dd)2023-12-31
finalApprovalDateStartstringStart date for final approval (yyyy-MM-dd)2023-01-01
finalApprovalDateEndstringEnd date for final approval (yyyy-MM-dd)2023-12-31
paymentDateStartstringStart date for payment (yyyy-MM-dd)2023-01-01
paymentDateEndstringEnd date for payment (yyyy-MM-dd)2023-12-31
lastUpdateDateStartstringStart date for last update (yyyy-MM-dd)2023-01-01
lastUpdateDateEndstringEnd date for last update (yyyy-MM-dd)2023-12-31
categoryCodesstring[]Category codes (digits only), comma-separated23,25
requesterUuidsuuid[]UUIDs of requesters (comma-separated list)a0c82a20-ac09-4cfd-b429-d0623585911e, b1d93b31-bd10-5dfe-c530-e0734696022f
statusesenum[]Reimbursement statuses: PENDING, APPROVED, etc.PENDING, APPROVED
requesterNamestringName of the requesterJohn Doe
uuidsuuid[]UUIDs of reimbursements (comma-separated list)a0c82a20-ac09-4cfd-b429-d0623585911e, b1d93b31-bd10-5dfe-c530-e0734696022f

โœ… Successful Response

StatusMeaning
200OK - List of reimbursements returned

โŒ Error Responses

StatusMeaning
400Bad Request
401Unauthorized
403Forbidden

๐Ÿ“˜ 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

  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.