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.

Calls

Use the calls engagement API to log and manage calls on CRM records. You can log calls either in HubSpot or through the calls API. Below, learn the basic methods of managing calls through the API. To view all available endpoints and their requirements, click the Endpoints tab at the top of this article.

Create a call engagement

To create a call engagement, make a POST request to /crm/v3/objects/calls.

In the request body, add call 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 call's time of creation and determines where the call sits on the record timeline. You can use either a Unix timestamp in milliseconds or UTC format. 

hs_call_title

The title of the call.

hubspot_owner_id

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

hs_call_body

The description of the call, including any notes that you want to add.

hs_call_duration

The duration of the call in seconds.

hs_call_from_number

The phone number that the call was made from.

hs_call_to_number

The phone number that received the call.

hs_call_recording_url

The URL that stores the call recording. [note about the other calling update?]

hs_call_status

The status of the call. The statuses are busy, calling CRM user, canceled, completed, connecting, failed, in progress, no answer, queued, and ringing. 

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

JSON
// Example request body
{
  "properties": {
    "hs_timestamp": "2021-03-17T01:32:44.872Z",
    "hs_call_title": "Discovery call",
    "hubspot_owner_id": "11349275740",
    "hs_call_body": "Decision maker out, will call back tomorrow",
    "hs_call_duration": "3800",
    "hs_call_from_number": "(857) 829 5489",
    "hs_call_to_number": "(509) 999 9999",
    "hs_call_recording_url": "https://api.twilio.com/2010-04-01/Accounts/AC890b8e6fbe0d989bb9158e26046a8dde/Recordings/RE3079ac919116b2d22",
    "hs_call_status": "COMPLETED"
  }
}

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

Associate calls with records

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

Use this table to describe parameters / fields
FieldDescription
callId

The ID of the call.

toObjectType

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

toObjectId

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

associationType

The ID of the association type between the call 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/calls/17591596434/associations/contact/104901/194

Remove an association

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

/crm/v3/objects/calls/{callId}/associations/{toObjectType}/{toObjectId}/{associationType}

Retrieve calls

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

To retrieve an individual call by its call ID, make a GET request to /crm/v3/objects/calls/{callId}. You can 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 calls, make a GET request to /crm/v3/objects/calls. 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. 

When you make a successful request, the response will include the callId which you can use to retrieve, update, and delete the call. 

Update calls

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

In the request body, include the call properties that you want to update:

JSON
//Example PATCH request to https://api.hubspot.com/crm/v3/objects/calls/{callID}
{
  "properties": {
    "hs_timestamp": "2021-03-17T01:32:44.872Z",
    "hs_call_title": "Discovery call",
    "hubspot_owner_id": "11349275740",
    "hs_call_body": " Decision maker out, will call back tomorrow",
    "hs_call_duration": "3800",
    "hs_call_from_number": "(857) 829 5489",
    "hs_call_to_number": "(509) 999 9999",
    "hs_call_recording_url": "https://api.twilio.com/2010-04-01/Accounts/AC890b8e6fbe0d989bb9158e26046a8dde/Recordings/RE3079ac919116b2d22",
    "hs_call_status": "COMPLETED"
  }
}'

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 calls

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

To delete an individual call by its call ID, make a DELETE request to /crm/v3/objects/calls/{callId}.

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.