---
title: "Update a task"
method: PATCH
path: "/tasks/{id}"
tags: ["Tasks"]
---

# Update a task

`PATCH /tasks/{id}`

## Request

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

Rename a task, change its status, assignee, due date, description, or the record it's about, set its field values, or set or remove the caller's reminder for it. Omitted properties are left unchanged. Anyone who can see a task can set their own reminder on it.

## Path parameters

- `id` string, required: The task ID.

## Request body

- object
  - `title` string: Task title.
  - `status` 'todo' | 'in_progress' | 'done' | 'cancelled': Where the task stands: todo, in_progress, done, or cancelled. done and cancelled close it.
  - `assigneeId` string, nullable: The ID of an active user in the organization to assign it to, or null to unassign it.
  - `dueDate` string, date, nullable: The day the task is due, as YYYY-MM-DD.
  - `description` string, nullable: Details, up to 2,000 characters.
  - `linkedRecord` object, nullable: A project, account, or contact, as { type, id }.
    - `type` 'project' | 'account' | 'contact', required: The kind of record: project, account, or contact.
    - `id` string, required: The record's ID.
  - `reminder` object, nullable: Your reminder for the task, as { remindAt }. Replaces your current one, and null removes it.
    - `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 `200`

OK

- 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.
- `404`: Not found. NOT_FOUND.
- `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)