---
title: "Create a task"
method: POST
path: "/tasks"
tags: ["Tasks"]
---

# Create a task

`POST /tasks`

## Request

- Base URL: `https://api.parley.so/v1`
- URL: `https://api.parley.so/v1/tasks`
- Auth: HTTP bearer

Create a task, optionally about one project, account, or contact, with a status (todo unless given), assignee, due date, and description. Pass reminder to have Parley remind the caller about it.

## Request body

- object
  - `title` string, required: Task title.
  - `status` 'todo' | 'in_progress' | 'done' | 'cancelled': Defaults to todo.
  - `assigneeId` string: The ID of an active user in the organization to assign it to.
  - `dueDate` string, date: The day the task is due, as YYYY-MM-DD.
  - `description` string: Details, up to 2,000 characters.
  - `linkedRecord` object: The project, account, or contact the task is about, as { type, id }. A project must be one you can edit.
    - `type` 'project' | 'account' | 'contact', required: The kind of record: project, account, or contact.
    - `id` string, required: The record's ID.
  - `reminder` object: Your reminder for the task, as { remindAt }.
    - `remindAt` string, date-time, required: When Parley should remind you, through your notification settings. An ISO 8601 date-time in the future.
  - `fields` object: Custom field values to set on the task, keyed by field name or ID. A value replaces the current one, null clears it, and fields you don't mention are left alone. Each value must match its field's type: a string for text, long_text, email, url, single_select (one of the field's options), and user (the id of an active user in the organization); a number; true or false; an ISO 8601 date-time or YYYY-MM-DD date; a list of strings for collection ([] clears it); or { streetAddress, cityTown, state, country } for address. At most 50 fields. Status, assignee, due date, and description are properties of the task, not fields.

## Response `201`

Created.

- Task
  - `id` string, required: The task ID.
  - `title` string, required: Task title.
  - `status` 'todo' | 'in_progress' | 'done' | 'cancelled', nullable, required: Where the task stands: todo, in_progress, done, or cancelled. done and cancelled close it.
  - `assignee` UserRef, required: A reference to a person in the organization.
    - `id` string, required: The user's ID.
    - `name` string, nullable, required: The user's full name, or null when it is unknown, as for someone who has left the organization.
    - `email` string, nullable, required: The user's email address, or null when it is unknown.
  - `dueDate` string, date, nullable, required: The day the task is due, as YYYY-MM-DD.
  - `description` string, nullable, required: Details, or null.
  - `linkedRecord` RecordRef, required: A reference to a project, account, or contact.
    - `type` 'project' | 'account' | 'contact', required: The kind of record: project, account, or contact.
    - `id` string, required: Its ID.
    - `name` string, required: The record's name. A contact's is its first and last name, or an email address when it has no name.
  - `reminder` object, nullable, required: Your reminder for the task, or null. Reminders are personal: each person sees only their own.
    - `remindAt` string, date-time, required: When Parley reminds you, through your notification settings.
    - `sentAt` string, date-time, nullable, required: When the reminder was sent, or null until then.
  - `createdAt` string, date-time, required: When the task was created.
  - `updatedAt` string, date-time, required: When the task was last renamed or linked to a different record. Changes to its status, assignee, due date, description, field values, and reminders do not change it.
  - `fields` object, required: Custom field values, keyed by field name, with a key for every field defined for tasks (null when unset). The value's shape follows the field's type. Status, assignee, due date, and description are properties of the task, not fields.

## Other responses

- `400`: The request was invalid. VALIDATION_FAILED, INVALID_REFERENCE, INVALID_FIELD_VALUES.
- `401`: Missing or invalid credentials. UNAUTHORIZED.
- `403`: You don't have permission. FORBIDDEN.
- `429`: Too many requests, or a usage limit was reached. TOO_MANY_REQUESTS.

---

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