Engagements

This API is currently in development. For the latest stable version check out this page. 

 


 

Sign up to access and test APIs in beta. 

Please note: This API is currently under development and is subject to change based on testing and feedback. When you sign up for beta access, you agree to adhere to our Developer & Developer Beta Terms of Use and to provide timely feedback on the APIs through our community forums. You also acknowledge and understand the risk associated with testing an unstable API. Sign up below to start testing
Engagements are used to store data from CRM actions, including notes, tasks, emails, meetings, and calls. At a minimum, engagements should be 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 types

Engagement objects all have a type that determines what the metadata field should look like; these types and their corresponding metadata are detailed below. The Engagements API currently 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.

NOTE: Engagements are used internally by other HubSpot tools, and therefore you may come across engagement types other than those listed here. Integrators should be prepared to gracefully handle these other engagement types, as well as new engagement types going forward. While these non-documented engagement types may appear when reading engagements, creating/editing them is not supported.

Email content and OAuth scopes

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:

"metadata": {
"cc": [],
"to": [],
"validationSkipped": [],
"html": "The content of this email has been redacted. To include it in the response, your app must require the sales-email-read scope.",
"bcc": []
}

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

Response details

Individual engagements will have the data listed below. For more information on how the disposition field relates to the call outcome, please see this endpoint.

This endpoint has not been updated. Please click here to use the most recent stable version.