There's a new version of the HubSpot API

As of November 30, 2022, HubSpot API keys are no longer a supported authentication method for accessing HubSpot APIs. Instead, you should use a private app access token or OAuth to authenticate API calls. Learn more about this change and how to migrate an API key integration to use a private app instead.

Create an engagement

Last updated May 12, 2023

POST /engagements/v1/engagements

Method Details

HTTP Methods:

POST

Content Type:

application/json

Response Format:

json

Requires Authentication?

Yes

Rate Limited?

Yes

Headers

User-Agent

Products:

Marketing & CRM

Required Scope:

crm.objects.companies.write
crm.objects.contacts.write
crm.objects.deals.write
tickets
e-commerce

Use this endpoint to create an engagement (an email, call, meeting, task or note) on an object in HubSpot.

Use case for this endpoint: This endpoint is useful for keeping your CRM records up-to-date on any interactions that take place outside of HubSpot. Activity reporting in the CRM also feeds off of this data.

Associations

You can associate engagements with objects to ensure they're displayed correctly in the UI. (See example request body to the right.)

 

 

Tasks created through HubSpot's API will not trigger user notifications.

Required parameters How to use Description
OAuth access token or private app access token Authorization: Bearer {token} header Used to authenticate the request. Please see this page for more details about authentication.
Engagement JSON Included in request body An object representing the engagement you have created. See below for more details.

When creating an engagement, you will POST an engagement object containing the following data:

For note-type engagements, the body of the note will be limited to 65536 characters.

Field Description

type

Required. One of: EMAIL, CALL, MEETING, TASK, NOTE

metadata

Required. An object representing the details of the engagement. See the examples to the right for details about the format of the metadata for specific engagement types.

ownerId

Optional long, corresponding to an Owner. Task engagements use the ownerId to populate the Assigned to field.

timestamp

Optional timestamp (in milliseconds). This timestamp will be treated as the time that the engagement happened, and will determine where the engagement appears in the timeline for any associated records.

Response details

  • If the request is successful, returns a 200 response with the JSON of the new engagement.
  • If the request is unsuccessful, returns a 4xx response with error details.