Sign up to access and test APIs in beta.
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; 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
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:
"html": "The content of this email has been redacted. To include it in the response, your app must require the sales-email-read scope.",
ownerId field will also be redacted from the
engagement object of the response.
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.