Skip to main content

Engagements store data from CRM actions, including notes, tasks, emails, meetings, and calls. Engagements are associated with at least one CRM record.

Use case for this API: The Engagements API can be used to create engagements (in order to log calls, notes, or emails from an external system) and get engagement data for reporting.

Engagement objects all have a type that determines what the metadata field should look like. The types and their corresponding metadata are detailed below. The Engagements API supports the following engagement types:

  • NOTE - Note engagements are used to hold simple text information about an object record.
  • EMAIL - Email engagements are used to track emails sent on an object record.
  • TASK - Task engagements are used by users to manage tasks, and are available on the tasks dashboard as well as on associated object records.
  • MEETING - Meeting engagements are used to track face-to-face meetings on an object record.
  • CALL - Call engagements are used to track calls made by users on an object record.

Email engagements (any engagements with the type of EMAIL, INCOMING_EMAIL, or FORWARDED_EMAIL) can contain the content of email messages sent to or received from a contact record. These emails are sent and received through the HubSpot user's email service provider. In order for your integration to receive the content and details of these types of email engagements, your integration will need to request the sales-email-read scope. If your integration does not request this scope, the metadata fields of email engagements will be redacted:

The ownerId field will also be redacted from the engagement object of the response.

An example of data returned by the engagements API is shown below. Depending on your account's properties and the engagement type, additional information may be returned beyond the data listed. For more information on how the disposition field relates to the call outcome, please see this endpoint.