Submit, recall, approve, reject, release or transfer a report
POST /api/hr/v1/travel-reports/{id}/{action}
Module: HR · operationId: runTravelReportAction · Tag: Travel expenses · Auth: access token (Authorization: Bearer <accessToken>)
submit(owner,draft/rejected→submitted): recomputes the totals and freezes them – approval,totalsand the transfer use them, whatever the rates say later;422 infectedwhile a receipt the malware scan flagged is attached,422 scan_failedwhile one could not be checked.recall(owner,submitted→draft).approve/reject(submitted): the responsible managers andhr:travel:approve; a reason (note) is required to reject. Accounting (hr:travel:manage) may also rejectapprovedreports.release(approved→released) andtransfer(released→transferred):hr:travel:manage. The transfer creates a trade document (transactionType, defaultTRAVEL_EXPENSE) for the employee's masterdata address (400on fieldaddressIdwhile it does not exist yet), one line per allowance and expense (the frozen totals; net unit price with 4 decimals, so net × VAT rate is the reimbursed amount). Trade derives the document from the referencehr-travel:<id>, so a repeated transfer never creates a second one. A failure answers502 transfer_failed, is kept intransferErrorand can be retried.
Nobody approves, releases or transfers their own report (403); not allowed in the current
status: 409 invalid_state.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id |
path | string (uuid) | yes | |
action |
path | string | yes | (one of submit, recall, approve, reject, release, transfer) |
Request body
application/json (required)
version(integer, required): Version of the report the action is based onnote(string): Reason of a rejection (max length 2000)
Example:
{
"note": "Bitte den Parkbeleg nachreichen, dann gebe ich die Abrechnung frei.",
"version": 2
}
Responses
- 200 Done (
application/json) - 400 Error (
application/json) - 403 Error (
application/json) - 404 Error (
application/json) - 409 Error (
application/json) - 422 Error (
application/json) - 502 Error (
application/json) - 503 Error (
application/json)
Fields of the 200 answer:
approvedAt(string (date-time)): When it was approvedapprovedBy(string): Who approved (e-mail; the platform team acting in the tenant: „Plattformbetrieb (MBCOM) · “)country(string): ISO 3166-1 alpha-2 code of the destination; selects the allowance ratescreatedAt(string (date-time)): When the report was createdcreatedBy(string): Who created the report (e-mail)days(array of TravelDay): What was provided per day (meals, lodging lump sum)breakfast(boolean): Breakfast provided (cuts the allowance by breakfastPercent of the full-day rate)date(string (date)): Day of the trip (YYYY-MM-DD)dinner(boolean): Dinner was provided (reduces the meal allowance)lodgingLumpSum(boolean): The night after this day without a hotel receipt (lodging lump sum)lunch(boolean): Lunch was provided (reduces the meal allowance)
decisionNote(string): Reason of the last rejectiondestination(string): Destination of the tripemployeeId(string): Id of the employeeemployeeName(string): Display name of the employee (in lists)endAt(string): Local return time (YYYY-MM-DDTHH:MM)id(string): Id of the reportitems(array of TravelItem): Expenses (single reads)date(string (date), required): Date of the expense (YYYY-MM-DD)kind(string, required): Kind of expense; mileage items carry km and are priced with the tenant rate (one ofmileage,transport,lodging,other)amountCents(integer): Gross amount in cents; computed for mileage (km × rate)description(string): What was paid for (max length 200)id(string, read-only): Id of the expensekm(number): Kilometres of a mileage itemmerchant(string): Issuer of the receipt (max length 200)receiptId(string): A receipt of the same reportvatCents(integer): VAT contained in the amount, always computed from amountCents and vatRate (a sent value is ignored; record a receipt with several rates as one item per rate)vatRate(number): VAT rate in percent
note(string): Note of the employeeovernight(boolean): The trip includes overnight stayspurpose(string): Purpose of the tripreceipts(array of TravelReceipt): Receipt files (single reads)contentType(string): Media type of the filecreatedAt(string (date-time)): When the receipt was uploadedcreatedBy(string): Who uploaded the receipt (e-mail)documentId(string): DMS document (owner module hr)fileName(string): File nameid(string): Id of the receiptscanStatus(string): Malware scan of the DMS (one ofPENDING,CLEAN,INFECTED,SKIPPED,FAILED)sizeBytes(integer): Size in bytes
rejectedAt(string (date-time)): When it was rejected lastrejectedBy(string): Who rejected it last (e-mail; the platform team acting in the tenant: „Plattformbetrieb (MBCOM) · “)releasedAt(string (date-time)): When it was releasedreleasedBy(string): Who released it for payment (e-mail; the platform team acting in the tenant: „Plattformbetrieb (MBCOM) · “)startAt(string): Local departure time (YYYY-MM-DDTHH:MM)status(string): State of the report (one ofdraft,submitted,approved,rejected,released,transferred)submittedAt(string (date-time)): When the report was submittedtotalCents(integer): Reimbursement in centstotals(object): Drafts and rejected reports: computed with the current rates; fromsubmittedon: frozen at submit.tradeDocumentNo(string): Number of the trade documenttradeTransactionId(string): Id of the trade document created for the reporttransferError(string): The last failed transfer (empty after a success)transferredAt(string (date-time)): When it was transferred to tradeupdatedAt(string (date-time)): When the report was last changedversion(integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)
Example 200 answer:
{
"approvedAt": "2026-11-07T08:15:00Z",
"approvedBy": "tobias.hartl@muster-it.example",
"country": "DE",
"createdAt": "2026-11-06T07:40:00Z",
"createdBy": "jonas.bauer@muster-it.example",
"days": [
{
"breakfast": true,
"date": "2026-11-05"
}
],
"destination": "Alpenhotel Seeblick, Schönau am Königssee",
"employeeId": "f2a4c6e8-0b2d-4f4a-8c6e-8a0c2e4b6d1c",
"employeeName": "Jonas Bauer",
"endAt": "2026-11-05T18:30",
"id": "0d2f4b6d-8f0b-4d2f-8b6d-8f0b2d4f6b46",
"items": [
{
"amountCents": 11400,
"date": "2026-11-04",
"description": "Regensburg – Schönau am Königssee und zurück",
"id": "2f4b6d8f-0b2d-4f4b-9d8f-0b2d4f6b8d47",
"kind": "mileage",
"km": 380,
"vatCents": 0,
"vatRate": 0
},
{
"amountCents": 9800,
"date": "2026-11-05",
"description": "Übernachtung mit Frühstück",
"id": "4b6d8f0b-2d4f-4b6d-8f0b-2d4f6b8d0f48",
"kind": "lodging",
"merchant": "Alpenhotel Seeblick",
"receiptId": "6f8b0d2f-4b6d-4f8b-8d2f-4b6d8f0b2d44",
"vatCents": 641,
"vatRate": 7
}
],
"note": "Hotelrechnung als PDF angehängt.",
"overnight": true,
"purpose": "WLAN-Ausleuchtung und Access-Point-Montage",
"receipts": [
{
"contentType": "application/pdf",
"createdAt": "2026-11-06T07:48:00Z",
"createdBy": "jonas.bauer@muster-it.example",
"documentId": "8b0d2f4b-6d8f-4b0d-9f4b-6d8f0b2d4f45",
"fileName": "rechnung-alpenhotel-seeblick.pdf",
"id": "6f8b0d2f-4b6d-4f8b-8d2f-4b6d8f0b2d44",
"scanStatus": "CLEAN",
"sizeBytes": 184320
}
],
"startAt": "2026-11-04T06:45",
"status": "approved",
"submittedAt": "2026-11-06T07:52:00Z",
"totalCents": 23440,
"totals": {
"days": [
{
"allowanceCents": 1400,
"country": "DE",
"date": "2026-11-04",
"deductionCents": 0,
"hours": 17.25,
"kind": "partial",
"lodgingCents": 0,
"rateCents": 1400
},
{
"allowanceCents": 840,
"country": "DE",
"date": "2026-11-05",
"deductionCents": 560,
"hours": 18.5,
"kind": "partial",
"lodgingCents": 0,
"rateCents": 1400
}
],
"expensesCents": 9800,
"lodgingLumpSumCents": 0,
"mealAllowanceCents": 2240,
"mileageCents": 11400,
"totalCents": 23440,
"warnings": []
},
"updatedAt": "2026-11-07T08:15:00Z",
"version": 3
}
Example request
curl -X POST 'https://api.mbcom.cloud/api/hr/v1/travel-reports/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/submit' \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
--data '{"note":"Bitte den Parkbeleg nachreichen, dann gebe ich die Abrechnung frei.","version":2}'