---
title: "Add a task to a record. `title` and `relatedRecord.id` are required, and `relatedRecord.id` must resolve to a change order; `taskGroupId` must resolve to an active change order task group and `assignedToUserId` to a user. `sequence` omitted appends the task after the last step, and a value places it at that step, alongside any task already there. Creating the task already complete stamps `completedUtc` and `completedBy`."
method: POST
path: "/api/tasks"
tags: ["Task"]
---

# Add a task to a record. \`title\` and \`relatedRecord.id\` are required, and \`relatedRecord.id\` must resolve to a change order; \`taskGroupId\` must resolve to an active change order task group and \`assignedToUserId\` to a user. \`sequence\` omitted appends the task after the last step, and a value places it at that step, alongside any task already there. Creating the task already complete stamps \`completedUtc\` and \`completedBy\`.

`POST /api/tasks`

## Request body

- TaskSaveDto — The writable state of a task. Create and update both take the whole object: update is a full replacement, so an omitted field is cleared.
  - `relatedRecord` TaskRelatedRecordDto — The record a task hangs off. Every task currently hangs off a change order.
    - `id` string, nullable — The id of the record, as returned by Change Order List
    - `number` integer, nullable — The record's sequential number. Read-only
    - `customer` CommonReferenceDto — Represents a reference to a document in a DB collection
      - `id` string, nullable — Unique Id associated to the referenced object
      - `name` string, nullable — Descriptive name associated to the object
  - `title` string, required — What the task is. Required
  - `description` string, nullable — A longer description of the task
  - `notes` string, nullable — Free-text notes on the task
  - `dueDateUtc` string, date-time, nullable — When the task is due (UTC)
  - `assignedToUserId` string, nullable — The user to assign the task to. Must resolve to a user
  - `taskGroupId` string, nullable — The group to file the task under. Must resolve to an active change order task group
  - `complete` boolean — Whether the task is complete. Setting it true completes the task and stamps completedUtc and completedBy; setting it false re-opens the task and clears both
  - `sequence` integer, nullable — The step the task should sit at. A value of 1 or more places it at that step, alongside any task already there. Null or a value below 1 appends it after the last step on a create and leaves it where it is on an update

## Response `200`

The created task

- TaskDto — One task, with enough of the record it hangs off to identify it.
  - `id` string, nullable — The id of the task
  - `relatedRecord` TaskRelatedRecordDto — The record a task hangs off. Every task currently hangs off a change order.
    - `id` string, nullable — The id of the record, as returned by Change Order List
    - `number` integer, nullable — The record's sequential number. Read-only
    - `customer` CommonReferenceDto — Represents a reference to a document in a DB collection
      - `id` string, nullable — Unique Id associated to the referenced object
      - `name` string, nullable — Descriptive name associated to the object
  - `title` string, nullable — What the task is
  - `description` string, nullable — A longer description of the task
  - `notes` string, nullable — Free-text notes on the task
  - `sequence` integer — The step the task sits at within its record's task list. Tasks sharing a step are parallel work, so a step is not unique within a record
  - `taskGroup` CommonReferenceDto — Represents a reference to a document in a DB collection
    - `id` string, nullable — Unique Id associated to the referenced object
    - `name` string, nullable — Descriptive name associated to the object
  - `assignedTo` CommonReferenceDto — Represents a reference to a document in a DB collection
    - `id` string, nullable — Unique Id associated to the referenced object
    - `name` string, nullable — Descriptive name associated to the object
  - `dueDateUtc` string, date-time, nullable — When the task is due (UTC), or null when it carries no date
  - `complete` boolean — Whether the task is complete
  - `completedUtc` string, date-time, nullable — When the task was completed (UTC). Server-stamped when the task is first marked complete and cleared when it is re-opened. Read-only
  - `completedBy` CommonReferenceDto — Represents a reference to a document in a DB collection
    - `id` string, nullable — Unique Id associated to the referenced object
    - `name` string, nullable — Descriptive name associated to the object
  - `attachmentCount` integer — How many attachments the task carries
  - `lastNotification` TaskNotificationDto — The message that went out for a task step: who was told, over which channel, and when.
    - `userId` string, nullable — The id of the user who was told
    - `userName` string, nullable — The name of the user who was told
    - `channel` 'none' | 'email' | 'slack' | 'teams' | 'gChat' — How a task notification was delivered.
    - `sentUtc` string, date-time — When the message was handed to the sender (UTC). Delivery itself is not tracked

## Other responses

- `400` — Validation issues with input

## Changes

- **2026-09-26** `e584a13d530a` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/fulcrumpro/apis/fulcrum-publicapi/changes/api/tasks/post.md)

---

[API](https://skmtc.dev/fulcrumpro/apis/fulcrum-publicapi.md) · [All operations](https://skmtc.dev/fulcrumpro/apis/fulcrum-publicapi/llms.txt) · [OpenAPI document](https://skmtc.dev/fulcrumpro/apis/fulcrum-publicapi/revisions/e584a13d530a?raw)