Create an Engagement

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

Create an engagement (a note, task, or activity) on an object in HubSpot. Engagements are any interaction with a contact that should be logged inside of the CRM. Activity reporting in the CRM also feeds off of this data.

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 that contains the following data:

Field Description

type

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

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

portalId

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

You can also set associations on the engagements so they can be properly displayed in the UI with the object they are tied to (see request body to the right).

Returns a 200 response with the JSON of the new engagement on success.

Otherwise, you'll get a 4xx response with a message detailing the error in the body of the response.