Bill a unit's approved work in a period (hr:work:billing)
POST /api/hr/v1/work-batches
Module: HR · operationId: createWorkBatch · Tag: Work billing · Auth: access token (Authorization: Bearer <accessToken>)
Bills the approved entries of a project (scope: project, projectRef; the customer is that of the project's
work, customerId picks one when it bills several), a contract outside projects (contract, customerId,
contractId) or a customer outside projects and contracts (customer, customerId) whose work date lies in
from–to. Hourly entries are priced with the rate table (project, contract, customer, default; a rate for the
entry's kind before one for all kinds; the newest validFrom on or before the work date), flat-rate entries
with an article at the article's sales price in masterdata (one line, quantity 1). With dryRun=true the answer
is the preview and nothing is stored. Otherwise the entries are put into the batch with their rate
(billedRate) and the invoice draft goes to trade at once (reference hr:work-batch:<id>); when trade does not
take it the batch stays requested with lastError and is sent again automatically. Refused (400, field
from, hourlyRate or article): no approved billable work, entries without rate, flat-rate articles without
price or gone, a sum of 0 or less. Without trade 503 trade_unavailable.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
dryRun |
query | boolean | Answer the preview only (default false) |
Request body
application/json (required)
from(string (date), required): First work day of the period (YYYY-MM-DD), inclusivescope(string, required): Billing unit: contract (customerId, contractId), customer (customerId) or project (projectRef) (one ofproject,contract,customer)to(string (date), required): Inclusive; at most a year afterfromcontractId(string): The contract of a contract batchcustomerId(string): The customer (masterdata address id); for a project only when its work bills severalprojectRef(string): The project of a project batch
Example:
{
"customerId": "1b3d5f7b-9d1f-4b3d-8f5b-9d1f3b5d7f50",
"from": "2026-10-01",
"scope": "customer",
"to": "2026-10-31"
}
Responses
- 200 The preview (dryRun) (
application/json) - 201 The batch with what it bills (
application/json) - 400 Error (
application/json) - 403 Error (
application/json) - 409 Error (
application/json) - 503 Error (
application/json)
Fields of the 201 answer:
batch(WorkBatch): One hourly invoice of a billing unit – a draft in trade until a person releases it there.billableMinutes(integer): Hourly minutes (flat-rate entries are not counted)contractId(string): Trade contract of contract batchescreatedAt(string (date-time)): When the batch was createdcustomerId(string): Customer (masterdata address id) of contract and customer batchesentryCount(integer): Number of entries in the batchgrossTotal(number, nullable): Gross total of trade's invoiceid(string (uuid)): Id of the batchinvoiceNumber(string): Given by trade on releaseinvoicedOn(string (date), nullable): Date of the invoice (YYYY-MM-DD) once releasedlabel(string): Names the unit on the invoice and in listslastError(string): Why the last send failed (German)netAmount(number): Net amount HR computednetTotal(number, nullable): Net total of trade's invoiceperiodFrom(string (date)): First work day of the period (YYYY-MM-DD)periodTo(string (date)): Last work day of the period (YYYY-MM-DD)projectRef(string): Reference of the project (project batches)requestedAt(string (date-time)): When the batch was requestedrequestedBy(string): Who requested it (e-mail)scope(string): Billing unit of the batch (one ofproject,contract,customer)sendAttempts(integer): Attempts to send the draft to tradestate(string): requested → drafted (trade holds the draft) → invoiced; discarded: the draft was deleted, the entries are free again (one ofrequested,drafted,invoiced,discarded)tradeTransactionId(string): Id of trade's documentupdatedAt(string (date-time)): When the batch was last changedversion(integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)
billableMinutes(integer): Billable minutes of the batchflatWithoutArticle(integer): Approved flat-rate entries without article (never billed)lines(array of object): The entries with their rate and net amountentry(WorkEntry): A booked piece of work of an employee.approvedAt(string (date-time), nullable): When the entry was approvedapprovedBy(string): Who approved the entry (e-mail; the platform team acting in the tenant: „Plattformbetrieb (MBCOM) · “)article(WorkArticleRef | null): Masterdata article a flat-rate entry is billed asbatchId(string (uuid), nullable): Billing batch the entry is billed inbillableMinutes(integer): Minutes billedbilledRate(number, nullable): Hourly rate (or article price) the entry was billed atbilling(string): Key of a billing typecontract(WorkContractRef | null): Trade contract that decides billingcorrectionOf(string (uuid), nullable): The approved or billed entry this one corrects; its minutes are the difference (may be negative)createdAt(string (date-time)): When the work entry was createdcreatedBy(string): Who booked the entry (e-mail)customer(WorkCustomerRef | null): Customer the work is billed todescription(string): What was donedurationSeconds(integer): The exact length in seconds (the stopwatch's seconds, elseminutes× 60)employeeId(string (uuid)): Id of the employeeemployeeName(string): Display name of the employee – only inlistApprovableWorkEntriesendedAt(string (date-time), nullable):nullfor the running stopwatch and for an entry without a spanid(string (uuid)): Id of the work entrykind(string): Key of a work kind (getWorkEntrySettings)km(number): Kilometres travelled (kinds that allow travel)minutes(integer): The length in minutes that sums and billing use (a correction's difference, may be negative; 0 for a stopwatch run that rounded to nothing)origin(string): The call or appointment the time comes from:comms:interaction:<id>orcomms:calendar:<id>; omitted for other work. Booked at most once per tenant (409 already_booked)project(WorkProjectRef | null): Project the work counts forrunning(boolean): The running stopwatch entry (start, no end)source(string): How the entry was booked (one ofmanual,stopwatch,interaction,calendar,correction)startedAt(string (date-time), nullable):nullfor an entry booked as a length onlystate(string): suggested → confirmed → approved → billed (one ofsuggested,confirmed,approved,billed)subject(string): What was worked on:desk:item:<id>,forge:item:<id>,crm:activity:<id>, a projectdesk:project:<id>/forge:project:<id>; empty for work on the customer only or internal worksubjectLabel(string): The subject's name at booking time (the origin's without a subject)travelMinutes(integer): Travel time in minutes (kinds that allow travel)updatedAt(string (date-time)): When the work entry was last changedversion(integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)workDate(string (date)): The day the work counts for (the person's choice; with a start its day in the tenant's time zone)
flat(boolean): Billed as the entry's article (quantity 1)net(number): Net amount of the linerate(number, nullable): Hourly rate or article price;nullnone
missingPrice(integer): Flat-rate entries whose article is gonemissingRate(integer): Entries without hourly ratenetAmount(number): Net amount of the batchnoPrice(integer): Flat-rate entries whose article has no sales price
Example 201 answer:
{
"billableMinutes": 270,
"flatWithoutArticle": 0,
"lines": [
{
"entry": {
"billableMinutes": 90,
"billing": "hourly",
"customer": {
"id": "1b3d5f7b-9d1f-4b3d-8f5b-9d1f3b5d7f50",
"name": "Kanzlei Hofmann \u0026 Partner"
},
"description": "Neuer Arbeitsplatz Büroleitung eingerichtet",
"employeeId": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
"id": "3d5f7b9d-1f3b-4d5f-8b9d-1f3b5d7f9b65",
"kind": "onsite",
"minutes": 90,
"source": "manual",
"state": "approved",
"subject": "desk:item:9f1b3d5f-7b9d-4f1b-8d5f-7b9d1f3b5d66",
"subjectLabel": "#198 Arbeitsplatz Herr Pichler",
"version": 2,
"workDate": "2026-10-14"
},
"flat": false,
"net": 142.5,
"rate": 95
},
{
"entry": {
"billableMinutes": 180,
"billing": "hourly",
"customer": {
"id": "1b3d5f7b-9d1f-4b3d-8f5b-9d1f3b5d7f50",
"name": "Kanzlei Hofmann \u0026 Partner"
},
"description": "Datensicherung umgestellt und Rücksicherung getestet",
"employeeId": "c7e9a1b3-5d7f-4b2c-8e4a-6f8b0d2c4e06",
"id": "1b3d5f7b-9d1f-4b3d-9f5b-9d1f3b5d7f67",
"kind": "remote",
"minutes": 180,
"source": "manual",
"state": "approved",
"subject": "desk:item:3f5b7d9f-1b3d-4f5b-9d9f-1b3d5f7b9d68",
"subjectLabel": "#205 Backup-Umstellung",
"version": 2,
"workDate": "2026-10-22"
},
"flat": false,
"net": 285,
"rate": 95
}
],
"missingPrice": 0,
"missingRate": 0,
"netAmount": 427.5,
"noPrice": 0
}
Example request
curl -X POST 'https://api.mbcom.cloud/api/hr/v1/work-batches' \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
--data '{"customerId":"1b3d5f7b-9d1f-4b3d-8f5b-9d1f3b5d7f50","from":"2026-10-01","scope":"customer","to":"2026-10-31"}'