---
updatedAt: 2026-02-20T15:12:47.000Z
agentTools:
  projectIndex: https://developer.candis.io/llms.txt
---

# Candis Reimbursement Items Data API

The  [Reimbursement Items](https://developer.candis.io/reference/listReimbursementItems) endpoint allows you to retrieve reimbursement items from your organization with flexible filtering and pagination options. This guide covers both practical usage and the detailed response structure.

<br />

# List Reimbursement Items - API Guide & Response Structure

The `GET /v1/organizations/{organizationId}/reimbursement-items` endpoint allows you to retrieve reimbursement items from your organization with flexible filtering and pagination options. This guide covers both practical usage and the detailed response structure.

## API Usage

### Basic Usage

**Endpoint:** `GET /v1/organizations/{organizationId}/reimbursement-items`

**Authentication:** Bearer token required

### Common Use Cases

#### 1. Get Recent Exported Items (Default)

```curl
curl -X GET \
  "https://api.candis.io/v1/organizations/alpha-organization/reimbursement-items" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

This returns the first 50 exported reimbursement items (default behavior).

#### 2. Filter by Status and Date Range

```curl
curl -X GET \
  "https://api.candis.io/v1/organizations/alpha-organization/reimbursement-items?status=APPROVED&reimbursementItemDateFrom=2024-01-01T00:00:00Z&reimbursementItemDateTo=2024-01-31T23:59:59Z" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

#### 3. Get Specific Reimbursement Types

```curl
curl -X GET \
  "https://api.candis.io/v1/organizations/alpha-organization/reimbursement-items?types=MILEAGE,HOSPITALITY_EXPENSE&limit=100" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

#### 4. Pagination with Sorting

```curl
curl -X GET \
  "https://api.candis.io/v1/organizations/alpha-organization/reimbursement-items?offset=50&limit=25&sortField=UPDATED_AT&sortDirection=DESC" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### Query Parameters

| Parameter                   | Type   | Description                                      | Example                                          |
| --------------------------- | ------ | ------------------------------------------------ | ------------------------------------------------ |
| `offset`                    | number | Skip this many items (default: 0)                | `offset=50`                                      |
| `limit`                     | number | Maximum items to return (default: 50)            | `limit=100`                                      |
| `status`                    | string | Filter by status: `APPROVED`, `EXPORTED`         | `status=APPROVED`                                |
| `types`                     | string | Filter by types (comma-separated)                | `types=MILEAGE,PER_DIEM`                         |
| `sortField`                 | string | Sort by: `REIMBURSEMENT_ITEM_DATE`, `UPDATED_AT` | `sortField=UPDATED_AT`                           |
| `sortDirection`             | string | Sort direction: `ASC`, `DESC`                    | `sortDirection=DESC`                             |
| `reimbursementItemDateFrom` | string | Filter from this date                            | `reimbursementItemDateFrom=2024-01-01T00:00:00Z` |
| `reimbursementItemDateTo`   | string | Filter until this date                           | `reimbursementItemDateTo=2024-01-31T23:59:59Z`   |
| `updatedAtFrom`             | string | Filter by update date from                       | `updatedAtFrom=2024-01-01T00:00:00Z`             |
| `updatedAtTo`               | string | Filter by update date until                      | `updatedAtTo=2024-01-31T23:59:59Z`               |

***

## Response Overview

The main response object (`ReimbursementItemsResponseDto`) contains two key components:

```json
{
  "reimbursementItems": [...],
  "pagination": {...}
}
```

## Pagination Object

The `pagination` object provides information about the current page and total records:

| Field        | Type   | Description                         |
| ------------ | ------ | ----------------------------------- |
| `pageCount`  | number | Total number of pages available     |
| `pageSize`   | number | Number of items in the current page |
| `totalCount` | number | Total count of reimbursement items  |

**Example:**

```json
{
  "pageCount": 10,
  "pageSize": 50,
  "totalCount": 500
}
```

Read more about <Anchor label="How to Use Pagination" target="_blank" href="https://developer.candis.io/update/docs/how-to-use-pagination">How to Use Pagination</Anchor>

## Reimbursement Items Array

The `reimbursementItems` array contains different types of reimbursement items, each with specific properties based on their type. All items share common base properties but include type-specific fields.

### Common Properties

All reimbursement item types include these base properties:

| Field               | Type   | Description                             |
| ------------------- | ------ | --------------------------------------- |
| `id`                | string | Unique identifier                       |
| `status`            | string | Current status (`APPROVED`, `EXPORTED`) |
| `createdAt`         | string | Creation timestamp                      |
| `updatedAt`         | string | Last update timestamp                   |
| `title`             | string | Title of the reimbursement item         |
| `totalAmount`       | object | Total amount with currency conversion   |
| `reimbursementCase` | object | Associated reimbursement case           |
| `contact`           | object | Contact information                     |
| `bookings`          | array  | Booking details                         |
| `invoiceNumber`     | string | Invoice number                          |
| `expenseDate`       | string | Expense date                            |
| `type`              | string | Type discriminator                      |

### Amount Structure

The `totalAmount` and other monetary fields use this structure:

```json
{
  "amount": 10000,
  "currency": "EUR",
  "precision": 2,
  "baseAmount": 10000,
  "baseCurrency": "EUR",
  "basePrecision": 2,
  "exchangeRate": 1.0,
  "exchangeRateDate": "2024-01-01T12:00:00Z"
}
```

### Contact Information

Each reimbursement item includes contact details:

```json
{
  "name": "John Doe",
  "accountsPayableNumber": "K1349234",
  "paymentInfo": {
    "iban": "DE12345678901234567890",
    "swiftCode": "BIC123456789",
    "accountHolder": "John Doe"
  }
}
```

### Booking Details

The `bookings` array contains financial posting information:

```json
{
  "amount": 27.84,
  "baseAmount": 27.84,
  "generalLedgerAccount": {
    "accountCode": "1100",
    "name": "Travel Expenses"
  },
  "costCenter": {
    "code": "CC-123"
  },
  "bookingKey": {
    "taxCode": "19",
    "description": "Standard VAT"
  },
  "note": "Business travel expense"
}
```

<br />

## Reimbursement Item Types

### 1. General Expense (`GENERAL_EXPENSE`)

The simplest reimbursement type with only the common properties.

**Example:**

```json
{
  "type": "GENERAL_EXPENSE",
  "title": "Office Supplies",
  "totalAmount": {
    "amount": 50,
    "currency": "EUR"
  },
  "expenseDate": "2024-01-01T12:00:00Z"
}
```

### 2. Hospitality Expense (`HOSPITALITY_EXPENSE`)

Includes additional fields for hospitality-related expenses:

| Additional Field | Type   | Description             |
| ---------------- | ------ | ----------------------- |
| `location`       | string | Location of the event   |
| `internalGuests` | array  | List of internal guests |
| `externalGuests` | array  | List of external guests |
| `tipAmount`      | object | Tip amount (optional)   |
| `receiptAmount`  | object | Receipt amount          |

**Example:**

```json
{
  "type": "HOSPITALITY_EXPENSE",
  "location": "Berlin",
  "internalGuests": ["John Doe", "Jane Smith"],
  "externalGuests": ["Client A", "Client B"],
  "receiptAmount": {
    "amount": 12,
    "currency": "EUR"
  }
}
```

### 3. Per Diem (`PER_DIEM`)

For daily allowance expenses with detailed segment and day information:

| Additional Field | Type  | Description                          |
| ---------------- | ----- | ------------------------------------ |
| `segments`       | array | Travel segments with locations       |
| `days`           | array | Daily breakdown with rates and meals |

**Segment Structure:**

```json
{
  "startAt": "2024-01-01T08:00:00Z",
  "endAt": "2024-01-01T18:00:00Z",
  "location": {
    "region": {"en": "Europe", "de": "Europa"},
    "countryIsoCode": "DE",
    "country": {"en": "Germany", "de": "Deutschland"}
  }
}
```

**Day Structure:**

```json
{
  "date": "2024-01-01T00:00:00Z",
  "numberOfMinutes": 480,
  "dayRate": {"amount": 24, "currency": "EUR"},
  "reimbursableRate": {"amount": 18, "currency": "EUR"},
  "providedBreakfast": true,
  "providedLunch": false,
  "providedDinner": true
}
```

### 4. Mileage (`MILEAGE`)

For vehicle-related travel expenses:

| Additional Field         | Type    | Description               |
| ------------------------ | ------- | ------------------------- |
| `locations`              | array   | Travel locations          |
| `applicableRate`         | object  | Rate per kilometer        |
| `distanceOverride`       | object  | Manual distance override  |
| `vehicleType`            | string  | `CAR` or `MOTORBIKE`      |
| `calculatedDistanceInKm` | number  | Calculated distance       |
| `isRoundTrip`            | boolean | Whether it's a round trip |

**Example:**

```json
{
  "type": "MILEAGE",
  "locations": [
    {"en": "Berlin", "de": "Berlin"},
    {"en": "Munich", "de": "München"}
  ],
  "vehicleType": "CAR",
  "calculatedDistanceInKm": 585,
  "isRoundTrip": false,
  "applicableRate": {
    "amount": 0.3,
    "currency": "EUR"
  }
}
```

<br />

```json
{
  "amount": 27.84,
  "baseAmount": 27.84,
  "generalLedgerAccount": {
    "accountCode": "1100",
    "name": "Travel Expenses"
  },
  "costCenter": {
    "code": "CC-123"
  },
  "bookingKey": {
    "taxCode": "19",
    "description": "Standard VAT"
  },
  "note": "Business travel expense"
}
```

## Best Practices

1. **Type Checking**: Always check the `type` field to determine which additional properties are available
2. **Currency Handling**: Use the `precision` field to properly format monetary amounts
3. **Pagination**: Implement proper pagination handling using the pagination object
4. **Status Filtering**: Filter by status to get only the items you need (`APPROVED`, `EXPORTED`)
5. **Date Filtering**: Use date range filters for better performance when processing large datasets
6. **Rate Limiting**: Implement appropriate delays between API calls to respect rate limits

This structure ensures you can handle all types of reimbursement items returned by the API effectively.