Tasks

Please note: This API is currently in beta and is subject to change based on testing and feedback. By using these endpoints you agree to adhere to our Developer TermsDeveloper Beta Terms. You also acknowledge and understand the risk associated with testing an unstable API. For the latest stable version of the engagements API, check out the legacy engagements overview.

Use the tasks engagement API to log and manage tasks on CRM records. You can log task activities either in HubSpot or through the tasks API. 

Below, learn the basic methods of managing tasks through the API. To view all available endpoints and their requirements, click the Endpoints tab at the top of this article.

Create a task engagement

To create a task engagement, make a POST request to /crm/v3/objects/tasks.

In the request body, add task details in a properties object, which can contain the following fields:

Use this table to describe parameters / fields
FieldDescription
hs_timestamp

Required. This field marks the task's time of creation and determines where the task sits on the record timeline. You can use either a Unix timestamp in milliseconds or UTC format. 

hs_task_body

The task description. 

hubspot_owner_id

The ID of the owner associated with the task. This field determines the user listed as the task creator on the record timeline.

hs_task_subject

The title of the task. 

hs_task_status

The status of the task. The value can be completed, deferred, in progress, not started, or waiting. 

hs_task_priority

The priority of the task. Use this field to mark a task as high priority. 

For example, your request body might look similar to the following:

JSON
// Example request body
{
  "properties": {
     "hs_timestamp": "2019-10-30T03:30:17.883Z",
     "hs_task_body": "Send Proposal",
     "hubspot_owner_id": "64492917",
     "hs_task_subject": "Follow-up for Brian Buyer",
     "hs_task_status": "WAITING",
     "hs_task_priority": "HIGH"
}
}

Learn more about batch creating tasks by clicking the Endpoints tab at the top of this article.

Associate tasks with records

To associate a task with records, such as a contact and its associated companies, make a PUT request to /crm/v3/objects/tasks/{taskId}/associations/{toObjectType}/{toObjectId}/{associationType}. The request URL contains the following fields:

Use this table to describe parameters / fields
FieldDescription
taskId

The ID of the task.

toObjectType

The type of object that you want to associate the task with (e.g., contact or company)

toObjectId

The ID of the record that you want to associate the task with.

associationType

The ID of the association type between the task and the other object type. You can retrieve this value through the associations API.

For example, your request URL might look similar to the following:

https://api.hubspot.com/crm/v3/objects/tasks/17687016786/associations/contacts/104901/204

Remove an association

To remove an association between a task and a record, make a DELETE request to the same URL as above:

/crm/v3/objects/tasks/{taskId}/associations/{toObjectType}/{toObjectId}/{associationType}

Retrieve tasks

You can retrieve tasks individually or in bulk. Learn more about batch retrieval by clicking the Endpoints tab at the top of this article.

To retrieve an individual task by its task ID, make a GET request to /crm/v3/objects/tasks/{taskId}. You can also include the following parameters in the request URL: 

Use this table to describe parameters / fields
ParameterDescription
properties

A comma separated list of the properties to be returned. 

associations

A comma separated list of objects to you want to retrieve associated record IDs from. 

To request a list of all of tasks, make a GET request to crm/v3/objects/tasks. You can include the following parameters in the request URL: 

Use this table to describe parameters / fields
ParameterDescription
limit

The maximum number of results to display per page.

properties

A comma separated list of the properties to be returned. 

Update tasks

You can update tasks individually or in batches. To update an individual task by its task ID, make a PATCH request to /crm/v3/objects/tasks/{taskId}

In the request body, include the task properties that you want to update. For example, your request body might look similar to the following:

JSON
//Example PATCH request to https://api.hubspot.com/crm/v3/objects/tasks/{taskId}
{
  "properties": {
  "hs_timestamp": "2019-10-30T03:30:17.883Z",
  "hs_task_body": "Send Proposal",
  "hubspot_owner_id": "64492917",
  "hs_task_subject": "Close deal",
  "hs_task_status": "COMPLETED",
  "hs_task_priority": "HIGH"
}
}

HubSpot will ignore values for read-only and non-existent properties. To clear a property value, pass an empty string for the property in the request body.

Learn more about batch updating by clicking the Endpoints tab at the top of this article.

Delete tasks

You can delete tasks individually or in batches, which will add the task to the recycling bin in HubSpot. You can later restore the task from the record timeline.

To delete an individual task by its task ID, make a DELETE request to /crm/v3/objects/tasks/{taskId}.

Learn more about batch deleting by clicking the Endpoints tab at the top of this article.


Was this page helpful? *
This form is for feedback on our developer docs. If you have feedback on the HubSpot product, please share it in our Idea Forum instead.