> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pazy.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Reimbursement List API
> Retrieve a paginated list of reimbursements with filters by date, state, user, amount, and item type
## Authentication
All requests require an API key in the request headers.
**Headers:**
```
Authorization: Api-Key YOUR_API_KEY
```
## Request
### Query Parameters
| Parameter | Type | Required | Description |
| --------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `sortBy` | string | No | Field to sort results by. Allowed values: `reimbursement_no`, `sequence_no`, `reimbursement_date`, `date_created`, `total_amount`. |
| `sortOrder` | string | No | Sort direction. Allowed values: `asc` (ascending), `desc` (descending). |
| `sortNullOrder` | string | No | Where to place results with null values in the sorted field. Allowed values: `first`, `last`. |
| `limit` | integer | No | Number of records to return. Min 1, Max 100, Default 30. |
| `cursor` | string | No | Cursor for pagination. Use the `nextCursor` value returned by the previous response. |
| `dateType` | string | No | Type of date to filter by. Default `reimbursement_date`. Possible values: `reimbursement_date`, `payment_date`, `date_created`, `approved_date`. |
| `startDate` | string | No | Start date for filtering (ISO 8601 UTC format: `YYYY-MM-DDTHH:mm:ssZ`). |
| `endDate` | string | No | End date for filtering (ISO 8601 UTC format: `YYYY-MM-DDTHH:mm:ssZ`). |
| `state` | array | No | Reimbursement states to filter by. Allowed values: `DRAFTED`, `APPROVAL_PENDING`, `APPROVED`, `PAID`, `ARCHIVED`. |
| `reimbursementNumber` | string | No | Filter by reimbursement number. |
| `reimbursementDate` | string | No | Filter by a specific reimbursement date (`YYYY-MM-DD` format). |
| `userId` | string | No | Filter by the id of the user the reimbursement belongs to. |
| `tagId` | integer | No | Filter reimbursements containing this organization tag id. |
| `amount` | number | No | Filter reimbursements with amount greater than or equal to this value. |
| `itemsType` | string | No | Filter by the type of items in the reimbursement. Possible values: `ALL_EXPENSE`, `ALL_MILEAGE`, `MIXED`. |
## Code Examples
```bash cURL theme={null}
curl -X GET "https://api.pazy.io/v1.0/reimbursements?limit=30&state=APPROVED" \
-H "Authorization: Api-Key YOUR_API_KEY"
```
```javascript JavaScript (Fetch API) theme={null}
const params = new URLSearchParams({ limit: '30', state: 'APPROVED' });
const response = await fetch(`https://api.pazy.io/v1.0/reimbursements?${params}`, {
method: 'GET',
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
});
const result = await response.json();
```
```python Python (requests) theme={null}
import requests
url = "https://api.pazy.io/v1.0/reimbursements"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
params = { "limit": 30, "state": "APPROVED" }
response = requests.get(url, headers=headers, params=params)
result = response.json()
```
## Success Response
**HTTP Status:** `200 OK`
**Response Fields:**
| Field | Type | Description |
| ------------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------ |
| `ok` | boolean | Indicates whether the request was successful |
| `data` | object | Contains the reimbursement list response data |
| `data.reimbursements` | array | List of reimbursements |
| `data.reimbursements[].id` | string | Unique identifier (slug) for the reimbursement |
| `data.reimbursements[].reimbursementNumber` | string | Reimbursement number |
| `data.reimbursements[].sequenceNumber` | string | System-generated sequence number with organization prefix |
| `data.reimbursements[].description` | string | Description of the reimbursement |
| `data.reimbursements[].reimbursementDate` | string | Reimbursement date (ISO 8601 format) |
| `data.reimbursements[].dateCreated` | string | Date the reimbursement was created in the system (ISO 8601 format) |
| `data.reimbursements[].amount` | number or string | Total amount of the reimbursement |
| `data.reimbursements[].currency` | string | Currency code (e.g., `INR`) |
| `data.reimbursements[].remarks` | string | Notes / remarks on the reimbursement |
| `data.reimbursements[].state` | string | Current state of the reimbursement. Possible values: `DRAFTED`, `APPROVAL_PENDING`, `APPROVED`, `PAID`, `ARCHIVED` |
| `data.reimbursements[].source` | string | Source of the reimbursement. Manual entries are returned as `WEB`; other possible values include `EMAIL`, `SLACK` |
| `data.reimbursements[].user` | object | The user the reimbursement belongs to |
| `data.reimbursements[].user.id` | string | Unique slug identifier of the user |
| `data.reimbursements[].user.name` | string | Full name of the user |
| `data.context` | object | Pagination metadata |
| `data.context.count` | number | Total number of reimbursements matching the filters |
| `data.context.hasMore` | boolean | Indicates whether there are more reimbursements to fetch |
| `data.context.nextCursor` | string or null | Cursor to fetch the next page. `null` when there are no more results |
### Reimbursement State Values
| Value | Description |
| ------------------ | --------------------------------- |
| `DRAFTED` | Reimbursement is in draft state |
| `APPROVAL_PENDING` | Reimbursement is pending approval |
| `APPROVED` | Reimbursement has been approved |
| `PAID` | Reimbursement has been paid |
| `ARCHIVED` | Reimbursement has been archived |
### Response Example
```json theme={null}
{
"ok": true,
"data": {
"reimbursements": [
{
"id": "reimbursement_identifier",
"reimbursementNumber": "REIM-2026-001",
"sequenceNumber": "PZY/2026-27/REIM/0001",
"description": "January travel reimbursement",
"reimbursementDate": "2026-01-31",
"dateCreated": "2026-01-31T10:30:00Z",
"amount": 5200.00,
"currency": "INR",
"remarks": "Approved",
"state": "APPROVED",
"source": "WEB",
"user": {
"id": "user_identifier",
"name": "John Doe"
}
}
],
"context": {
"count": 42,
"hasMore": true,
"nextCursor": "30"
}
}
}
```
## Error Responses
Authentication and permission failures are returned in the standard structured format shown below. Business-logic errors (such as access being denied) are returned with an HTTP `200 OK` status and a string `error` message: `{ "ok": false, "error": "" }`.
### Access Denied
**HTTP Status:** `200 OK`
```json theme={null}
{
"ok": false,
"error": "Access denied: You can only view vendors you own"
}
```
### Validation Error
**HTTP Status:** `400 Bad Request`
```json theme={null}
{
"ok": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Validation failed: /query/state: must be equal to one of the allowed values"
}
}
```
### Authentication Errors
**HTTP Status:** `401 Unauthorized`
```json theme={null}
{
"ok": false,
"error": {
"code": "MISSING_CREDENTIALS",
"message": "Missing Credentials"
}
}
```
```json theme={null}
{
"ok": false,
"error": {
"code": "INVALID_API_KEY",
"message": "Invalid API Key"
}
}
```
### Permission Errors
**HTTP Status:** `403 Forbidden`
```json theme={null}
{
"ok": false,
"error": {
"code": "INSUFFICIENT_PERMISSIONS",
"message": "Permission check failed - PERMISSION_CHECK_FAILED"
}
}
```
## Best Practices
* Use `cursor` and `limit` together to paginate; pass the `nextCursor` from the response as the `cursor` value for the next call
* `startDate` and `endDate` are interpreted against the column specified by `dateType` — change `dateType` to filter by payment, created, or approval date instead of the reimbursement date
* Use the `id` from the response as the input to the [Reimbursement Details API](/apis/reimbursement-details) for full reimbursement information
* Always check the `ok` flag in the response body in addition to the HTTP status code, since business-logic errors are returned with an HTTP `200 OK` status
* Access is limited to users with reimbursement read permission and an admin or bookkeeper role