Create an engagement

Last updated June 17, 2020

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:

contacts

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.)

 

 

Required parameters How to use Description
OAuth access token or API key Authorization: Bearer {token} header
or hapikey={key} query parameter.
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.