Create a project of a template's type with the template's tasks (desk:write)
POST /api/desk/v1/projects/from-template
Module: Desk · operationId: createProjectFromTemplate · Tag: Projects · Auth: access token (Authorization: Bearer <accessToken>)
The project gets the template's project type and field values (the request's values win). Task dates count
from startOn (else the project's start, else today); the project's start and end default to the plan's.
Tasks are created in the project type's task space with the actor's rights, so creation rules, history and
live updates run as for any ticket; everything is one transaction. dryRun=true stores nothing and answers
the plan after checking every task like a real create.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
dryRun |
query | boolean |
Request body
application/json (required)
project(Project, required)spaceId(string, required): Home space of the project (id or key on input, always the id in responses); must be an active space of the tenant. Required when a project is created; an update without it keeps the stored spacetitle(string, required): Title of the project (max length 200)archived(boolean): Archived: the project is kept for existing data but no longer offered in pickersbudgetAmount(number, nullable): Budget as a net amount (EUR)budgetMinutes(integer, nullable): Time budget; the warning uses itbudgetState(string, read-only): Absent without a time budget or while the spent time is unknown (one ofok,warning,exceeded)createdAt(string (date-time), read-only): When the project was createdcreatedBy(string, read-only): Login (e-mail) of who created the projectcustomFields(object): Values of the type's layout fields, keyed by field key ("cf." optional on input)customer(Ref | null): Masterdata customer of the projectdescription(string): Description of the projectendOn(string (date), nullable): Planned endflatRateArticle(object, nullable): No longer used: flat-rate articles are chosen on HR's work entries (ADR 0040); ignored on write and no longer returnedhourlyRate(number, nullable): No longer used: hourly rates of projects are HR's work rates with the project reference (ADR 0040); ignored on write and no longer returnedid(string, read-only): Id of the projectitemsByPhase(object, read-only): In lists only: the project's tickets by phase (new, active, waiting, done), counted like the project summary (merged tickets left out)number(integer, read-only): Project number, unique in the tenantphase(string, read-only): Phase of the status (one ofnew,active,waiting,done)plannedMinutes(integer, nullable): Planned effort in minutesresponsibleName(string): Name of the person responsibleresponsibleRef(string): Login (e-mail) of the person responsiblespentMinutes(integer, nullable, read-only): Work HR booked with the project as reference (desk:project:<id>, worked minus breaks, ADR 0040); null when HR does not answerstartOn(string (date), nullable): Planned startstatus(string): A status of the type's workflow (default its initial status; changes follow its transitions); without type planned, active, on_hold, done or cancelledticketDisplay(string): How the project's tickets show in the ticket lists and boards:ticketsas ordinary tickets,projectsonly on the projects page,hiddennot in the lists (unless assigned to the viewer). An update without it keeps the stored value (one oftickets,projects,hidden; default"tickets")typeId(string, nullable): Project type (id or key on input); null: the built-in statuses and no custom fieldsupdatedAt(string (date-time), read-only): When the project was last changedupdatedBy(string, read-only): Login (e-mail) of who last changed the projectversion(integer): Version of the project; send it back on change (409 version_conflict when it is outdated)warnPercent(integer): Budget warning from this share (default 80) (max 100)
templateId(string, required): Id or keystartOn(string (date)): Day the template's offsets count from
Example:
{
"project": {
"budgetAmount": 22400,
"budgetMinutes": 9600,
"customFields": {
"auftragsnummer": "A-2026-0412"
},
"customer": {
"id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c21",
"name": "Donau Maschinenbau AG"
},
"responsibleRef": "emma.maier@muster-it.example",
"spaceId": "PRJ",
"title": "ERP-Einführung Donau Maschinenbau"
},
"startOn": "2026-11-02",
"templateId": "9f6a7b8c-0d1e-4f2a-9b4c-6d7e8f9a0b01"
}
Responses
- 200 The plan (dryRun) (
application/json) - 201 Created (
application/json) - 400 Unknown or archived template, invalid project, or a task that cannot be created (the error names the template task)
- 422 A task misses required fields of its type (missing_fields), or the project's
spaceIdis missing, unknown or archived
Fields of the 201 answer:
dryRun(boolean): Only the plan: nothing was createdpayments(array of ProjectPayment): The payment plan the template created (not in a dry run)amount(number): Net amount or percentage (amountKind)amountKind(string): fixed: amount is net EUR; percent: a share of the project's budgetAmount (one offixed,percent)attempt(integer, read-only): Documents made so far; the trade reference is desk:project-payment::document(object, read-only): The invoice handed to trade (once requested)dueOn(string (date), nullable): Due on this dategrossTotal(number, nullable, read-only): Gross total of the invoiceid(string, read-only): Id of the paymentinvoiceNumber(string, read-only): Given by trade on releaseinvoicedOn(string (date), nullable, read-only): Invoice datelastError(string, read-only): Why the last send to trade failedmilestoneId(string, nullable): Due when this milestone of the project is reachednet(number, nullable, read-only): The net amount today (null: a percentage without budget amount)netTotal(number, nullable, read-only): Net total of the invoiceposition(integer): Position in the payment planprojectId(string, read-only): Project of the paymentrequestedAt(string (date-time), nullable, read-only): When the invoice draft was handed to traderequestedBy(string, read-only): The person, or system (automatic draft)role(string): interim payment or the final payment (one ofinterim,final)sendAttempts(integer, read-only): Attempts to hand the draft to tradestate(string, read-only): State of the payment (one ofplanned,due,requested,drafted,invoiced,skipped)taxRate(number): VAT rate in percent (max 100)title(string): Title of the payment (invoice line) (max length 200)tradeTransactionId(string, read-only): Invoice transaction in tradeversion(integer): Version of the payment; send it back on change
project(Project)spaceId(string, required): Home space of the project (id or key on input, always the id in responses); must be an active space of the tenant. Required when a project is created; an update without it keeps the stored spacetitle(string, required): Title of the project (max length 200)archived(boolean): Archived: the project is kept for existing data but no longer offered in pickersbudgetAmount(number, nullable): Budget as a net amount (EUR)budgetMinutes(integer, nullable): Time budget; the warning uses itbudgetState(string, read-only): Absent without a time budget or while the spent time is unknown (one ofok,warning,exceeded)createdAt(string (date-time), read-only): When the project was createdcreatedBy(string, read-only): Login (e-mail) of who created the projectcustomFields(object): Values of the type's layout fields, keyed by field key ("cf." optional on input)customer(Ref | null): Masterdata customer of the projectdescription(string): Description of the projectendOn(string (date), nullable): Planned endflatRateArticle(object, nullable): No longer used: flat-rate articles are chosen on HR's work entries (ADR 0040); ignored on write and no longer returnedhourlyRate(number, nullable): No longer used: hourly rates of projects are HR's work rates with the project reference (ADR 0040); ignored on write and no longer returnedid(string, read-only): Id of the projectitemsByPhase(object, read-only): In lists only: the project's tickets by phase (new, active, waiting, done), counted like the project summary (merged tickets left out)number(integer, read-only): Project number, unique in the tenantphase(string, read-only): Phase of the status (one ofnew,active,waiting,done)plannedMinutes(integer, nullable): Planned effort in minutesresponsibleName(string): Name of the person responsibleresponsibleRef(string): Login (e-mail) of the person responsiblespentMinutes(integer, nullable, read-only): Work HR booked with the project as reference (desk:project:<id>, worked minus breaks, ADR 0040); null when HR does not answerstartOn(string (date), nullable): Planned startstatus(string): A status of the type's workflow (default its initial status; changes follow its transitions); without type planned, active, on_hold, done or cancelledticketDisplay(string): How the project's tickets show in the ticket lists and boards:ticketsas ordinary tickets,projectsonly on the projects page,hiddennot in the lists (unless assigned to the viewer). An update without it keeps the stored value (one oftickets,projects,hidden; default"tickets")typeId(string, nullable): Project type (id or key on input); null: the built-in statuses and no custom fieldsupdatedAt(string (date-time), read-only): When the project was last changedupdatedBy(string, read-only): Login (e-mail) of who last changed the projectversion(integer): Version of the project; send it back on change (409 version_conflict when it is outdated)warnPercent(integer): Budget warning from this share (default 80) (max 100)
tasks(array of object): Template tasks placed on the calendar
Example 201 answer:
{
"dryRun": false,
"payments": [
{
"amount": 30,
"amountKind": "percent",
"attempt": 0,
"dueOn": null,
"id": "7d4e5f6a-8b9c-4d0e-9f2a-4b5c6d7e8f01",
"milestoneId": "6c3d4e5f-7a8b-4c9d-8e1f-3a4b5c6d7e02",
"net": 6720,
"position": 0,
"projectId": "5b2c3d4e-6f7a-4b8c-9d0e-2f3a4b5c6d01",
"role": "interim",
"state": "planned",
"taxRate": 19,
"title": "Abschlag nach Konfiguration",
"version": 1
}
],
"project": {
"budgetAmount": 22400,
"budgetMinutes": 9600,
"createdAt": "2026-11-02T07:30:00Z",
"customFields": {
"auftragsnummer": "A-2026-0412"
},
"customer": {
"id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c21",
"name": "Donau Maschinenbau AG"
},
"endOn": "2026-11-22",
"id": "5b2c3d4e-6f7a-4b8c-9d0e-2f3a4b5c6d01",
"number": 1,
"phase": "new",
"responsibleName": "Emma Maier",
"responsibleRef": "emma.maier@muster-it.example",
"spaceId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7d00",
"startOn": "2026-11-02",
"status": "geplant",
"title": "ERP-Einführung Donau Maschinenbau",
"typeId": "6e3f4a5b-7c8d-4e9f-8a1b-3c4d5e6f7a01",
"updatedAt": "2026-11-02T07:30:00Z",
"version": 1
},
"tasks": [
{
"dueOn": "2026-11-04",
"durationDays": 3,
"itemId": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5d01",
"itemNumber": 48,
"key": "installation",
"offsetDays": 0,
"startOn": "2026-11-02",
"title": "Grundinstallation"
},
{
"dueOn": "2026-11-03",
"durationDays": 2,
"itemId": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5d02",
"itemNumber": 49,
"key": "server",
"milestoneKey": "basis",
"offsetDays": 0,
"parentKey": "installation",
"startOn": "2026-11-02",
"title": "Server und Datenbank einrichten"
}
]
}
Example request
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/projects/from-template' \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
--data '{"project":{"budgetAmount":22400,"budgetMinutes":9600,"customFields":{"auftragsnummer":"A-2026-0412"},"customer":{"id":"3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c21","name":"Donau Maschinenbau AG"},"responsibleRef":"emma.maier@muster-it.example","spaceId":"PRJ","title":"ERP-Einführung Donau Maschinenbau"},"startOn":"2026-11-02","templateId":"9f6a7b8c-0d1e-4f2a-9b4c-6d7e8f9a0b01"}'