Skip to navigation

Bulk-update tasks

View as Markdown

Apply the same changes to every task that matches the filters, and return how many tasks were updated. Takes the same filters as GET /task/, as query params or in the _params body key. The other body fields are the changes to make, e.g.:

{"_params": {"id__in": "task_A,task_B,task_C"}, "is_complete": true}

One call updates at most _limit tasks, and the response doesn’t say whether more tasks matched. Repeat the call to update the rest. Returns 400 if id__in lists 1000 or more IDs.

Returns 400 if some tasks couldn’t be updated, with count set to the number that were, and the reasons in errors. Also returns 400 if any of the tasks is assigned to someone else and you don’t have the permission to manage other users’ tasks.

Authentication

AuthorizationBasic
Use your API key as the username and leave the password empty.
OR
AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Query parameters

_limitintegerOptional<=1000Defaults to 1000
Number of results to return.
_skipintegerOptionalDefaults to 0
Number of results to skip before returning, for pagination.
assigned_tostring or nullOptional

Only return tasks assigned to this user, e.g. user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA. Returns 403 for another user if your role restricts which leads you can see.

idstring or nullOptional

Only return the task with this ID, e.g. task_aRUZXCm9lMb2LwipTPhfFoFbCsUnaoQh1ncQ7WLnjlI.

id__instring or nullOptional

Comma-separated list of task IDs. Only return these tasks.

is_completebooleanOptional

true to only return completed tasks, false to only return incomplete tasks.

lead_idstring or nullOptional

Only return tasks on this lead, e.g. lead_5LmpOyrMQdJSUlbNGBSGfK5XzcioIm7aC94PSQamQJc.

_order_byenum or nullOptional

Field to sort by: date, due_date, date_created or date_updated. Prefix with - to sort in descending order, e.g. -date. Defaults to -date_created.

_typeenumOptional

Only return tasks of this type. Defaults to lead (tasks created on a lead) when neither _type nor _type__in is set. Use all to return every type.

_type__instring or nullOptional

Comma-separated list of task types, e.g. lead,outgoing_call. Only return tasks of any of these types. Takes the same values as _type, except all.

viewenum or nullOptional

Shortcut for a task view. inbox returns incomplete tasks due by the end of today, future returns incomplete tasks due from tomorrow on, and archive returns completed tasks. Today is based on your time zone. inbox overrides is_complete and date__lt, future overrides is_complete and date__gte, and archive overrides is_complete.

Allowed values:
datedate or datetimeOptional

Only return tasks due at exactly this date or time, in ISO 8601, e.g. 2024-01-31 or 2024-01-31T09:00:00Z. Values without a UTC offset are treated as UTC.

date__ltdate or datetimeOptional

Only return tasks due before this date or time, in ISO 8601, e.g. 2024-01-31 or 2024-01-31T09:00:00Z. Values without a UTC offset are treated as UTC.

date__ltedate or datetimeOptional

Only return tasks due on or before this date or time, in ISO 8601, e.g. 2024-01-31 or 2024-01-31T09:00:00Z. Values without a UTC offset are treated as UTC.

date__gtdate or datetimeOptional

Only return tasks due after this date or time, in ISO 8601, e.g. 2024-01-31 or 2024-01-31T09:00:00Z. Values without a UTC offset are treated as UTC.

date__gtedate or datetimeOptional

Only return tasks due on or after this date or time, in ISO 8601, e.g. 2024-01-31 or 2024-01-31T09:00:00Z. Values without a UTC offset are treated as UTC.

due_datedate or datetimeOptionalDeprecated

Deprecated: use date instead, which it matches.

due_date__ltdate or datetimeOptionalDeprecated

Deprecated: use date__lt instead, which it matches.

due_date__ltedate or datetimeOptionalDeprecated

Deprecated: use date__lte instead, which it matches.

due_date__gtdate or datetimeOptionalDeprecated

Deprecated: use date__gt instead, which it matches.

due_date__gtedate or datetimeOptionalDeprecated

Deprecated: use date__gte instead, which it matches.

date_created__ltdate or datetimeOptional

Only return tasks created before this date or time, in ISO 8601, e.g. 2024-01-31 or 2024-01-31T09:00:00Z.

date_created__ltedate or datetimeOptional

Only return tasks created on or before this date or time, in ISO 8601, e.g. 2024-01-31 or 2024-01-31T09:00:00Z.

date_created__gtdate or datetimeOptional

Only return tasks created after this date or time, in ISO 8601, e.g. 2024-01-31 or 2024-01-31T09:00:00Z.

date_created__gtedate or datetimeOptional

Only return tasks created on or after this date or time, in ISO 8601, e.g. 2024-01-31 or 2024-01-31T09:00:00Z.

date_updated__ltdate or datetimeOptional

Only return tasks last updated before this date or time, in ISO 8601, e.g. 2024-01-31 or 2024-01-31T09:00:00Z.

date_updated__ltedate or datetimeOptional

Only return tasks last updated on or before this date or time, in ISO 8601, e.g. 2024-01-31 or 2024-01-31T09:00:00Z.

date_updated__gtdate or datetimeOptional

Only return tasks last updated after this date or time, in ISO 8601, e.g. 2024-01-31 or 2024-01-31T09:00:00Z.

date_updated__gtedate or datetimeOptional

Only return tasks last updated on or after this date or time, in ISO 8601, e.g. 2024-01-31 or 2024-01-31T09:00:00Z.

Request

This endpoint expects an object.
_paramsmap from strings to strings or integersOptional

Filters that select the tasks to update, as an alternative to query params. Takes the same filters as GET /task/, e.g. {"id__in": "task_A,task_B"}. Values must be strings or integers. Other values are ignored.

assigned_tostringOptional

ID of the user to assign the task to. For an incomplete lead task, Close emails the new assignee, unless that’s you. On an outgoing_call task, this also removes the voice agent (agent_config_id).

datedatetime or dateOptional

When the task is due, in ISO 8601. A date, e.g. 2024-01-31, makes the task due that day. A date and time, e.g. 2024-01-31T09:00:00Z, makes it due at that time.

is_completebooleanOptional

true to complete the task, false to reopen it.

priorityenumOptional

Priority of the task. Only lead and outgoing_call tasks have a priority.

Allowed values:
resolutionenum or nullOptional

How the task was closed without being done. Only applies to outgoing_call, draft_email and draft_sms tasks, and is ignored on other types. Set to null to clear it.

Allowed values:
textstringOptional

Description of the task. Only lead and outgoing_call tasks have text, and it can’t be blank on lead tasks.

Response

Successful response
countinteger
Number of tasks that were updated.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
429
Too Many Requests Error