---
title: "Create a new Task"
method: POST
path: "/v2/task"
tags: ["Tasks"]
---

# Create a new Task

`POST /v2/task`

## Request

- Base URL: `https://api.workiz.com/crm/api`
- URL: `https://api.workiz.com/crm/api/v2/task`
- Auth: none declared. Required headers: `Authorization`
- TypeScript: <https://skmtc.dev/workiz/apis/developer-api/docs/v2/task/post.ts> (a function with typed inputs; its response is checked against the schema)

> **Beta:** Breaking changes may occur without notice.

Creates a new Task and returns the created Task object. Requires the Tasks add-on.

## Headers

- `Authorization` string, required

## Request body

- CreateTaskV2Dto
  - `title` string, required: The title of the task.
  - `description` string: The description of the task.
  - `start` string, required: The time & date when the task starts. Must be before the end date.
  - `end` string, required: The time & date when the task ends. Must be after the start date.
  - `isAllDay` boolean: Whether the task is an all-day task.
  - `tags` string[]: > **Beta:** This property is subject to change. Array of tag IDs to assign to the task (prefix `TAG-`). Only task tags can be assigned.
  - `techIds` string[]: Array of tech IDs assigned to the task (prefix `USR-`).
  - `parentId` string: The ID of the parent job or lead (prefix `JOB-` or `LD-`).

## Response `201`

The created Task.

- ResponseCreateTaskV2Dto
  - `id` string: The ID of the task (prefix `TSK-`).
  - `status` 'Done' | 'Open': The status of the task.
  - `title` string: The title of the task.
  - `description` string: The description of the task.
  - `start` string: The time & date when the task starts.
  - `end` string: The time & date when the task ends.
  - `isAllDay` boolean: Whether the task is an all-day task.
  - `tags` ResponseGenericTagV2Dto[]: > **Beta:** This property is subject to change. The tags assigned to the task.
    - `id` string: The ID of the tag (prefix `TAG-`).
    - `name` string: The name of the tag.
  - `techIds` string[]: Array of tech IDs assigned to the task (prefix `USR-`).
  - `parentType` 'job' | 'lead': The parent type of the task.
  - `parentId` string: The ID of the parent job or lead (prefix `JOB-` or `LD-`).
  - `isDeleted` boolean: Whether the task is deleted.
  - `updatedAt` string: The date and time the task was updated.
  - `createdAt` string: The date and time the task was created.
  - `progress` number: The task completion percentage.
  - `total` number: The total number of tasks on the parent record.

## Other responses

- `400`: Invalid input.
- `401`: Missing or invalid authentication token.
- `403`: The API key does not have permission to access this resource. The Tasks add-on is not active on this account.
- `404`: Tech or parent record not found.
- `429`: Rate limit exceeded.

## Changes

- **2026-11-12** `fb557783146c`: 2 warning, 1 info
  - removed the optional property `tags/items/color` from the response with the `201` status
  - removed the optional property `tags/items/type` from the response with the `201` status
  - response property `message` list-of-types was narrowed by removing types `array` from media type `application/json` of response `403`
- **2026-11-10** `bb1c25c92b05`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/workiz/apis/developer-api/changes/v2/task/post.md)

---

[API](https://skmtc.dev/workiz/apis/developer-api.md) - [All operations](https://skmtc.dev/workiz/apis/developer-api/llms.txt) - [OpenAPI document](https://skmtc.dev/workiz/apis/developer-api/revisions/fb557783146c?raw)