## 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 space
  - `title` (string, required): Title of the project (max length 200)
  - `archived` (boolean): Archived: the project is kept for existing data but no longer offered in pickers
  - `budgetAmount` (number, nullable): Budget as a net amount (EUR)
  - `budgetMinutes` (integer, nullable): Time budget; the warning uses it
  - `budgetState` (string, read-only): Absent without a time budget or while the spent time is unknown (one of `ok`, `warning`, `exceeded`)
  - `createdAt` (string (date-time), read-only): When the project was created
  - `createdBy` (string, read-only): Login (e-mail) of who created the project
  - `customFields` (object): Values of the type's layout fields, keyed by field key ("cf." optional on input)
  - `customer` (Ref | null): Masterdata customer of the project
  - `description` (string): Description of the project
  - `endOn` (string (date), nullable): Planned end
  - `flatRateArticle` (object, nullable): No longer used: flat-rate articles are chosen on HR's work entries (ADR 0040); ignored on write and no longer returned
  - `hourlyRate` (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 returned
  - `id` (string, read-only): Id of the project
  - `itemsByPhase` (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 tenant
  - `phase` (string, read-only): Phase of the status (one of `new`, `active`, `waiting`, `done`)
  - `plannedMinutes` (integer, nullable): Planned effort in minutes
  - `responsibleName` (string): Name of the person responsible
  - `responsibleRef` (string): Login (e-mail) of the person responsible
  - `spentMinutes` (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 answer
  - `startOn` (string (date), nullable): Planned start
  - `status` (string): A status of the type's workflow (default its initial status; changes follow its transitions); without type planned, active, on_hold, done or cancelled
  - `ticketDisplay` (string): How the project's tickets show in the ticket lists and boards: `tickets` as ordinary tickets, `projects` only on the projects page, `hidden` not in the lists (unless assigned to the viewer). An update without it keeps the stored value (one of `tickets`, `projects`, `hidden`; default `"tickets"`)
  - `typeId` (string, nullable): Project type (id or key on input); null: the built-in statuses and no custom fields
  - `updatedAt` (string (date-time), read-only): When the project was last changed
  - `updatedBy` (string, read-only): Login (e-mail) of who last changed the project
  - `version` (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 key
- `startOn` (string (date)): Day the template's offsets count from

Example:

```json
{
  "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 `spaceId` is missing, unknown or archived

Fields of the 201 answer:

- `dryRun` (boolean): Only the plan: nothing was created
- `payments` (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 of `fixed`, `percent`)
  - `attempt` (integer, read-only): Documents made so far; the trade reference is desk:project-payment:<id>:<attempt>
  - `document` (object, read-only): The invoice handed to trade (once requested)
  - `dueOn` (string (date), nullable): Due on this date
  - `grossTotal` (number, nullable, read-only): Gross total of the invoice
  - `id` (string, read-only): Id of the payment
  - `invoiceNumber` (string, read-only): Given by trade on release
  - `invoicedOn` (string (date), nullable, read-only): Invoice date
  - `lastError` (string, read-only): Why the last send to trade failed
  - `milestoneId` (string, nullable): Due when this milestone of the project is reached
  - `net` (number, nullable, read-only): The net amount today (null: a percentage without budget amount)
  - `netTotal` (number, nullable, read-only): Net total of the invoice
  - `position` (integer): Position in the payment plan
  - `projectId` (string, read-only): Project of the payment
  - `requestedAt` (string (date-time), nullable, read-only): When the invoice draft was handed to trade
  - `requestedBy` (string, read-only): The person, or system (automatic draft)
  - `role` (string): interim payment or the final payment (one of `interim`, `final`)
  - `sendAttempts` (integer, read-only): Attempts to hand the draft to trade
  - `state` (string, read-only): State of the payment (one of `planned`, `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 trade
  - `version` (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 space
  - `title` (string, required): Title of the project (max length 200)
  - `archived` (boolean): Archived: the project is kept for existing data but no longer offered in pickers
  - `budgetAmount` (number, nullable): Budget as a net amount (EUR)
  - `budgetMinutes` (integer, nullable): Time budget; the warning uses it
  - `budgetState` (string, read-only): Absent without a time budget or while the spent time is unknown (one of `ok`, `warning`, `exceeded`)
  - `createdAt` (string (date-time), read-only): When the project was created
  - `createdBy` (string, read-only): Login (e-mail) of who created the project
  - `customFields` (object): Values of the type's layout fields, keyed by field key ("cf." optional on input)
  - `customer` (Ref | null): Masterdata customer of the project
  - `description` (string): Description of the project
  - `endOn` (string (date), nullable): Planned end
  - `flatRateArticle` (object, nullable): No longer used: flat-rate articles are chosen on HR's work entries (ADR 0040); ignored on write and no longer returned
  - `hourlyRate` (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 returned
  - `id` (string, read-only): Id of the project
  - `itemsByPhase` (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 tenant
  - `phase` (string, read-only): Phase of the status (one of `new`, `active`, `waiting`, `done`)
  - `plannedMinutes` (integer, nullable): Planned effort in minutes
  - `responsibleName` (string): Name of the person responsible
  - `responsibleRef` (string): Login (e-mail) of the person responsible
  - `spentMinutes` (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 answer
  - `startOn` (string (date), nullable): Planned start
  - `status` (string): A status of the type's workflow (default its initial status; changes follow its transitions); without type planned, active, on_hold, done or cancelled
  - `ticketDisplay` (string): How the project's tickets show in the ticket lists and boards: `tickets` as ordinary tickets, `projects` only on the projects page, `hidden` not in the lists (unless assigned to the viewer). An update without it keeps the stored value (one of `tickets`, `projects`, `hidden`; default `"tickets"`)
  - `typeId` (string, nullable): Project type (id or key on input); null: the built-in statuses and no custom fields
  - `updatedAt` (string (date-time), read-only): When the project was last changed
  - `updatedBy` (string, read-only): Login (e-mail) of who last changed the project
  - `version` (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:

```json
{
  "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

```bash
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"}'
```
