ConnectCloud Developers

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:

{
  "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::
    • 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:

{
  "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"}'

View as Markdown · Interactive reference · OpenAPI