This reference lists the fields of the API endpoints expensecategory (expense category, GET only) and expense (expense). How to use them is covered in Create expenses & documents via the API. Fields marked with * are mandatory when creating an expense.
Expense category – expensecategory
GET only, purely informational. You use this endpoint to find the right expense category and its ID.
| Field | Data type | Description |
|---|---|---|
name | string | name of the expense category |
internalName | string | internal name of the expense category |
description | string | description |
active | boolean | usable yes/no |
type | enum | document type |
currency | number | currency ID |
defaultPaymentMethod | enum | default payment method |
defaultVehicle | enum | default vehicle |
Expense – expense (all fields)
A complete overview of all the fields an expense can carry. Which of them are mandatory per document type is listed further below.
| Field | Data type | Description |
|---|---|---|
date | string | document date in ISO format (YYYY-MM-DD). Default: current day |
number | string | document number (automatically generated) |
voucherNumber | string | number of the original document |
description | string | description |
type | enum | document type (travel costs, commission, etc.); determined by the expense category |
expenseCategory | number | ID of the expense category |
coworker | number | employee ID |
project | number | project ID |
customer | number | customer ID |
financeRecordID | number | invoice ID |
quantity | number | quantity (for calculations with the base price) |
voucherCurrencyFactor | number | currency factor of the document (automatically generated) |
voucherVat | number | VAT of the document |
voucherCurrency | number | currency ID |
voucherNetto | number | net (document currency) |
voucherGross | number | gross (document currency) |
voucherPrivateShare | number | employee’s private share; deducted from the reimbursement amount (document currency) |
relevantNetto | number | net amount (tenant currency) |
externalBillable | enum | billable to the organisation |
externalNetto | number | amount billable to the organisation (tenant currency) |
projectBillable | enum | billable to the project |
projectNetto | number | amount billable to the project (tenant currency) |
coworkerBillable | enum | billable to the employee |
coworkerNetto | number | amount billable to the employee (tenant currency) |
coworkerNettoTaxfree | number | tax-free amount billable to the employee (tenant currency) |
startLocation | string | start location |
finishLocation | string | destination |
distance | number | distance in kilometres |
overtime | number | overtime in minutes |
vehicle | enum | vehicle type (private / company) |
paymentMethod | enum | payment method (private / company) |
containsBreakfast | boolean | includes breakfast |
containsLunch | boolean | includes lunch |
containsDinner | boolean | includes dinner |
travelExpense | number | trip ID |
time | enum | time for additional subsistence expenses |
isTaxMandatory | boolean | mandatory taxation |
costcenterOverride | number | cost centre ID |
costunitOverride | number | cost object ID |
costtypeOverride | number | cost category ID |
costunitAuto | number | cost object ID (from the expense category) |
costtypeAuto | number | cost category ID (from the expense category) |
costcenterAuto | number | cost centre ID (from the expense category) |
Mandatory fields per document type
Common to all document types are expenseCategory* and coworker* as mandatory. In addition, the following apply per type:
Commission
Mandatory: expenseCategory*, coworker*, voucherNetto*. Optional, among others: project, customer, financeRecordID, voucherCurrency, relevantNetto, the billable fields, travelExpense and the cost-centre/cost-object/cost-category overrides.
Overtime payout (Overtime)
Mandatory: expenseCategory*, coworker*, coworkerNetto*, overtime*. Note: at least one of the values coworkerNetto or overtime must be given.
Mileage (Mileage)
Mandatory: expenseCategory*, coworker*, distance*, vehicle*. Optional, among others: voucherNumber, voucherNetto, startLocation, finishLocation, the billable fields and the cost-centre overrides.
Material
Mandatory: expenseCategory*, coworker*, quantity*. quantity is used for the calculation with the base price.
Expense voucher
Mandatory: expenseCategory*, coworker*, quantity*, voucherNetto*, voucherGross*, paymentMethod*. Note: if both voucherNetto and voucherGross are empty, the base price of the expense category is used; if none is defined, an error is returned. If only voucherGross is given, voucherNetto is calculated.
Additional subsistence expenses (Meal)
Mandatory: expenseCategory*, coworker*, containsBreakfast*, containsLunch*, containsDinner*, time*. Optional, among others: isTaxMandatory, the billable fields and the cost-centre overrides.
Supplement
Mandatory: expenseCategory*, coworker*, voucherNetto*. Optional, among others: project, customer, the billable fields, travelExpense and the cost-centre overrides.
Expense invoice
Mandatory: expenseCategory*, coworker*, financeRecordID*, paymentMethod*. Optional, among others: voucherPrivateShare, the billable fields and the cost-centre overrides.
Enum values
Some fields expect fixed enumeration values. Documented ones include:
| Field | Example value | Meaning |
|---|---|---|
externalBillable, projectBillable, coworkerBillable | YES_MANUAL | billable, amount set manually (fallback: value of the expense category) |
vehicle | PRIVATE | private vehicle (alternatively company vehicle) |
paymentMethod | PRIVATE | paid privately (alternatively company) |
time (meals) | RATE_24H | flat rate for 24 hours |
The valid values of an enum are provided by the API itself via the associated enum resource (for example /api/enum/contactfieldtype); you can browse them in the API explorer.
Example requests per document type
A POST /api/expense with the mandatory fields in each case (IDs are illustrative):
// Commission
{ "date": "2025-03-01", "description": "Commission", "expenseCategory": 176370223, "coworker": 54967, "voucherNetto": 100, "coworkerBillable": "YES_MANUAL" }
// Overtime payout
{ "date": "2025-03-07", "expenseCategory": 174025224, "coworker": 54967, "overtime": 60, "coworkerBillable": "YES_MANUAL" }
// Mileage
{ "date": "2025-03-03", "expenseCategory": 11582821, "coworker": 54967, "distance": 100, "vehicle": "PRIVATE" }
// Material
{ "date": "2025-03-07", "expenseCategory": 15478132, "coworker": 54967, "quantity": 100, "coworkerBillable": "YES_MANUAL" }
// Expense voucher
{ "date": "2025-03-07", "expenseCategory": 12199867, "coworker": 54967, "quantity": 2, "voucherNetto": 200, "paymentMethod": "PRIVATE" }
// Additional subsistence expenses
{ "date": "2025-03-10", "expenseCategory": 69707469, "coworker": 54967, "containsBreakfast": true, "containsLunch": true, "time": "RATE_24H" }
// Supplement
{ "date": "2025-03-14", "expenseCategory": 185792490, "coworker": 54967, "voucherNetto": 100, "coworkerBillable": "YES_MANUAL" }
// Expense invoice
{ "date": "2025-03-13", "expenseCategory": 185767407, "coworker": 54967, "financeRecordID": 185797405, "paymentMethod": "PRIVATE" }Notes
- Automatically generated fields (for example
number,voucherCurrencyFactor) do not need to be passed. - Amounts not marked as mandatory are calculated by the system – a manual override can be overwritten again when the record is later edited in the system.
- The billable fields use the value of the expense category as a fallback; you have to set differing values manually.
Related topics
- Create expenses & documents via the API API How-to
- API address structure (URLs) API Concept
- Topic: Costs & travel expenses Costs & travel expenses