Create an engagement

Last updated December 30, 2019

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, should be used for logical ordering (e.g. when a call occurred, vs when it was last modified)

uid

Optional unique identifier for the Engagement. Can be reused across types. Include inside the engagement object in the request body.

portalId

Optional long corresponding to the Hub ID of the target portal; useful if you have access to multiple portals

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.