Tasks

The task model

A task carries a short title, an optional description, a status and priority, some dates, an owner, and links to the records it is about. Only title is required. The fields you will set are below; the rest of a task's fields are filled in by the product (for example by the AI assistants) and are read-only through the API.

Fields you can set

title string · required	Short summary of the task. The only required field.
description string	Longer detail about what needs doing.
status enum	One of Open, Pending, Done, Recommended. Defaults to Open.
priority enum	One of High, Medium, Low. Defaults to High.
due_at datetime	When the task is due (ISO 8601, e.g. 2026-10-20T17:00:00Z). Defaults to a date set by the product if you omit it.
reminder_at datetime	When to remind the owner.
completed_at datetime	When the task was finished. Must be now or in the past. Not set automatically on this API - see Complete a task.
owner_id user id	The user responsible for the task ("Assign To"). Omit it and the task is assigned to you. Changing it later is a reassignment, not an edit - see Reassign a task.
contact_ids, company_ids, deal_ids id arrays	The records the task is about. Set these inside properties. At least one is required (see below).
meeting_id id	A single meeting the task is for.

Standard record operations

Because a task is a record, you create, read, update, delete, and list tasks with the same object routes as a contact, company, or deal - only the object type in the path changes to task. The request and response shapes are the ones documented under Records.

Action	Request
Create a task	POST /api/v1/objects/task/records · Create a record
Retrieve a task	GET /api/v1/objects/task/records/{id} · Retrieve a record
Edit a task	PATCH /api/v1/objects/task/records/{id} · Edit a task
Delete a task	DELETE /api/v1/objects/task/records/{id} · Delete a task
List tasks	GET /api/v1/objects/task/records · List records

Four of these have a rule that applies only to tasks, so they are worked through below. Creating a task has to link it to a record. Editing and completing leave the task's links and owner as they are. Deleting removes it for good. All four follow the access rule in the note below. Retrieve and list behave exactly as they do for any record.

Create a task

This is the standard record create (see Create a record), applied to the task type with the task rules above. Pass title plus at least one linked record in properties. Omit owner_id to assign the task to yourself. The records you link appear under the task's associations, not in properties - retrieve the task with ?associations=contact to read them back.

Request body

properties object · required

The task's fields. Must include title and at least one of contact_ids, company_ids, or deal_ids.

Returns

201 Created with the new task, including its id and the task_source / task_type the server stamped.

Errors

400 VALIDATION_FAILED

No linked record ("A task needs at least one contact, company or deal."), linked records on different companies, or an owner_id that can't take a task ("That person cannot take a task").

curl 'https://api.dreamteamcrm.ai/api/v1/objects/task/records' \
  -X POST \
  -H 'Authorization: Bearer <YOUR_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "properties": {
      "title": "Follow up with Ada about the renewal",
      "description": "Send the updated quote and confirm the renewal date.",
      "priority": "High",
      "due_at": "2026-10-20T17:00:00Z",
      "contact_ids": [1015634]
    }
  }'

{
  "id": 1044516,
  "type": "task",
  "properties": {
    "task_source": "USER",
    "owner_id": 1000052,
    "description": "Send the updated quote and confirm the renewal date.",
    "due_at": "2026-10-20T17:00:00Z",
    "title": "Follow up with Ada about the renewal",
    "priority": "High",
    "task_type": "USER_TASK",
    "status": "Open"
  },
  "created_at": "2026-10-15T09:58:49.930855783Z",
  "updated_at": "2026-10-15T09:58:49.930855783Z",
  "created_by": 1000052
}

{
  "code": "VALIDATION_FAILED",
  "message": "The records on a task must share one company: deal 1032672 belongs to company [1031396] and contact 1026842 belongs to company [1005738]",
  "errors": [],
  "path": "/api/v1/objects/task/records",
  "timestamp": "2026-10-15T10:02:09.236556190"
}

Edit a task

Send only the fields you want to change. Anything you leave out keeps the value it already had, and sending a field as null clears it. Set the Content-Type header to application/merge-patch+json. This is the standard record update (see Update a record) applied to a task. The example below moves the due date and lowers the priority.

Request body

properties object · required

The task fields to change. Editable fields include title, description, priority (High, Medium, Low), due_at, reminder_at, and status.

Returns

200 OK with the full task, reflecting the changed fields.

curl 'https://api.dreamteamcrm.ai/api/v1/objects/task/records/1044516' \
  -X PATCH \
  -H 'Authorization: Bearer <YOUR_TOKEN>' \
  -H 'Content-Type: application/merge-patch+json' \
  -d '{
    "properties": {
      "title": "Follow up with Ada about the renewal (revised)",
      "due_at": "2026-10-22T17:00:00Z",
      "priority": "Medium"
    }
  }'

{
  "id": 1044516,
  "type": "task",
  "properties": {
    "task_source": "USER",
    "owner_id": 1000052,
    "description": "Send the updated quote and confirm the renewal date.",
    "due_at": "2026-10-22T17:00:00Z",
    "title": "Follow up with Ada about the renewal (revised)",
    "priority": "Medium",
    "task_type": "USER_TASK",
    "status": "Open"
  },
  "created_at": "2026-10-15T09:58:49.930856Z",
  "updated_at": "2026-10-16T05:20:11.482301746Z",
  "created_by": 1000052
}

Complete a task

Marking a task done is an edit that sets status to Done (see Update a record). There is no separate "complete" endpoint. Because it is an edit, the access rule applies. You can complete a task only if you have access to it, and completing someone else's returns 403.

Returns

The task with status: "Done".

curl 'https://api.dreamteamcrm.ai/api/v1/objects/task/records/1044516' \
  -X PATCH \
  -H 'Authorization: Bearer <YOUR_TOKEN>' \
  -H 'Content-Type: application/merge-patch+json' \
  -d '{
    "properties": {
      "status": "Done"
    }
  }'

{
  "id": 1044516,
  "type": "task",
  "properties": {
    "task_source": "USER",
    "owner_id": 1000052,
    "meeting_id": null,
    "description": "Send the updated quote and confirm the renewal date.",
    "due_at": "2026-10-22T17:00:00Z",
    "title": "Follow up with Ada about the renewal (revised)",
    "priority": "Medium",
    "task_type": "USER_TASK",
    "status": "Done"
  },
  "created_at": "2026-10-15T09:58:49.930856Z",
  "updated_at": "2026-10-16T05:26:34.442992819Z",
  "created_by": 1000052
}

Delete a task

Deletes a task. This is the standard record delete (see Delete a record) applied to a task. The delete is permanent: there is no undo and no trash.

Returns

204 No Content with an empty body. There is no JSON to parse, so check the status code. You also get 204 if no task with that id exists, so repeating a delete you have access to is safe.

Errors

403 FORBIDDEN

The task belongs to someone else, or you do not have delete access to it. The body is {"message": "Access denied"}. It does not say which of the two, on purpose.

curl 'https://api.dreamteamcrm.ai/api/v1/objects/task/records/1044516' \
  -X DELETE \
  -H 'Authorization: Bearer <YOUR_TOKEN>'

# 204 No Content
# Task deleted - empty body, so check the status code.
# You also get 204 if no task with that id exists.

{
  "message": "Access denied",
  "path": "/api/v1/objects/task/records/1044516",
  "timestamp": "2026-10-16T05:32:10.118904"
}

Find eligible assignees

Returns the colleagues a task can be handed to: activated teammates who can see every record the task is linked to. Use it to pick a valid newOwnerId before reassigning. The response is a plain array of users (not the paginated results / metadata shape).

Path parameters

id integer · required

Numeric identifier of the task.

curl 'https://api.dreamteamcrm.ai/api/v1/sally/tasks/1044516/reassign-targets' \
  -H 'Authorization: Bearer <YOUR_TOKEN>'

[
  {
    "id": 1000045,
    "first_name": "Sam",
    "last_name": "Okafor",
    "primary_email": "sam.okafor@example.com",
    "username": "sam.okafor@example.com",
    "role": "sales_member",
    "title": "Account Executive",
    "status": "ACTIVATED",
    "sales_user": true,
    "created_at": "2026-05-22T08:38:24.479589Z"
  },
  {
    "id": 1000061,
    "first_name": "Priya",
    "last_name": "Nair",
    "primary_email": "priya.nair@example.com",
    "username": "priya.nair@example.com",
    "role": "sales_member",
    "title": "Account Executive",
    "status": "ACTIVATED",
    "sales_user": true,
    "created_at": "2026-08-05T09:05:15.533764Z"
  }
]

Reassign a task

Hands a task to another rep. This is the only way to change a task's owner - a plain edit won't do it. Send the new owner's id as newOwnerId. On success it returns 200 OK with an empty body.

Path parameters

id integer · required

Numeric identifier of the task to hand over.

Request body

newOwnerId user id · required

The colleague who should take the task. Use Find eligible assignees to get a valid id.

What the server checks

400 VALIDATION_FAILED	The task is no longer open ("This task is no longer open, so it cannot be handed on"), newOwnerId is missing, it's already that person's, or that person can't take a task.
403 FORBIDDEN	You don't hold the task and aren't an admin, or the new owner can't see a record the task is linked to.
409 CONFLICT	Another hand-off of the same task is in progress.

Only the current owner or a tenant admin can reassign, and only an open task can move.

curl 'https://api.dreamteamcrm.ai/api/v1/sally/tasks/1044516/reassign' \
  -X PATCH \
  -H 'Authorization: Bearer <YOUR_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "newOwnerId": 1000061
  }'

# 200 OK
# The task was handed to the new owner. The response body is empty.