Tasks
Use the tasks API to create and manage tasks. You can create tasks in HubSpot or via 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
To create a task, make a POST
request to /crm/v3/objects/tasks
.
In the request body, add task details in a properties object. You can also add an associations object to associate your new task with an existing record (e.g., contacts, companies).
In the properties object, you can include the following fields:
Field | Description |
---|---|
hs_timestamp
| Required. This field marks the task's due date. You can use either a Unix timestamp in milliseconds or UTC format. |
hs_task_body
| The task notes. |
hubspot_owner_id
| The owner ID of the user assigned to the task. |
hs_task_subject
| The title of the task. |
hs_task_status
| The status of the task, either |
hs_task_priority
| The priority of the task. Values include |
hs_task_type
| The type of task. Values include |
To create and associate a task with existing records, include an associations object in your request. The object should include the following fields:
Field | Description |
---|---|
toObjectId
| The ID of the record that you want to associate the task with. |
associationTypeId
| A unique identifier to indicate the association type between the task and the other object. You can retrieve the value through the associations API. |
For example, to create a task and associate it with two contacts, your request body might look similar to the following:
Learn more about batch creating tasks by clicking the Endpoints tab at the top of this article.
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:
Parameter | Description |
---|---|
properties
| A comma separated list of the properties to be returned. |
associations
| A comma separated list of object types to retrieve associated IDs for. Any specified associations that don't exist will not be returned in the response. Learn more about the associations API. |
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:
Parameter | Description |
---|---|
limit
| The maximum number of results to display per page. |
properties
| A comma separated list of the properties to be returned. |
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:
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.
To associate an existing task with records (e.g., contacts, deals, etc.), make a PUT
request to /crm/v3/objects/tasks/{taskId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}
. The request URL should contains the following fields:
Field | Description |
---|---|
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. |
associationTypeId
| A unique identifier to indicate the association type between the task and the other object. The ID can be represented numerically or in snake case (e.g., |
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}/{associationTypeId}
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.
Thank you for your feedback, it means a lot to us.