Guides
llms.txtMCP
Start typing to searchā€¦

Candis Reimbursement Items Data API

šŸš§

Beta

This API is a beta feature and is subject to possible changes. The API response and functionality will be updated in the future.

The 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.


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

ParameterTypeDescriptionExample
offsetnumberSkip this many items (default: 0)offset=50
limitnumberMaximum items to return (default: 50)limit=100
statusstringFilter by status: APPROVED, EXPORTEDstatus=APPROVED
typesstringFilter by types (comma-separated)types=MILEAGE,PER_DIEM
sortFieldstringSort by: REIMBURSEMENT_ITEM_DATE, UPDATED_ATsortField=UPDATED_AT
sortDirectionstringSort direction: ASC, DESCsortDirection=DESC
reimbursementItemDateFromstringFilter from this datereimbursementItemDateFrom=2024-01-01T00:00:00Z
reimbursementItemDateTostringFilter until this datereimbursementItemDateTo=2024-01-31T23:59:59Z
updatedAtFromstringFilter by update date fromupdatedAtFrom=2024-01-01T00:00:00Z
updatedAtTostringFilter by update date untilupdatedAtTo=2024-01-31T23:59:59Z

Response Overview

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

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

Pagination Object

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

FieldTypeDescription
pageCountnumberTotal number of pages available
pageSizenumberNumber of items in the current page
totalCountnumberTotal count of reimbursement items

Example:

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

Read more about How to Use Pagination

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:

FieldTypeDescription
idstringUnique identifier
statusstringCurrent status (APPROVED, EXPORTED)
createdAtstringCreation timestamp
updatedAtstringLast update timestamp
titlestringTitle of the reimbursement item
totalAmountobjectTotal amount with currency conversion
reimbursementCaseobjectAssociated reimbursement case
contactobjectContact information
bookingsarrayBooking details
invoiceNumberstringInvoice number
expenseDatestringExpense date
typestringType discriminator

Amount Structure

The totalAmount and other monetary fields use this structure:

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

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

Booking Details

The bookings array contains financial posting information:

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

Reimbursement Item Types

1. General Expense (GENERAL_EXPENSE)

The simplest reimbursement type with only the common properties.

Example:

{
  "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 FieldTypeDescription
locationstringLocation of the event
internalGuestsarrayList of internal guests
externalGuestsarrayList of external guests
tipAmountobjectTip amount (optional)
receiptAmountobjectReceipt amount

Example:

{
  "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 FieldTypeDescription
segmentsarrayTravel segments with locations
daysarrayDaily breakdown with rates and meals

Segment Structure:

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

{
  "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 FieldTypeDescription
locationsarrayTravel locations
applicableRateobjectRate per kilometer
distanceOverrideobjectManual distance override
vehicleTypestringCAR or MOTORBIKE
calculatedDistanceInKmnumberCalculated distance
isRoundTripbooleanWhether it's a round trip

Example:

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

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

Updated 5 days ago