There's a new version of the HubSpot API

As of November 30, 2022, HubSpot API keys are no longer a supported authentication method for accessing HubSpot APIs. Instead, you should use a private app access token or OAuth to authenticate API calls. Learn more about this change and how to migrate an API key integration to use a private app instead.

Engagements API Overview

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 types

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.

NOTE: Engagements are used internally by other HubSpot tools and new engagement types may be created., so you may interact with engagement types other than those listed here. Creating or editing non-documented engagement types are 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

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.


{
  "engagement": {
  // A set of details about the engagement itself
    "id": 328550660,
    // Integer, read-only; The unique ID for the engagement
    "portalId": 62515,
    // Integer, read-only; The Hub ID the engagement belongs to.
    "active": true,
    // Boolean; Only active engagements will appear in the timeline.
    "createdAt": 1494352128974,
    // Integer, read-only; A Unix timestamp in milliseconds representing when the engagement was created.
    "lastUpdated": 1494352128974,
    // Integer, read-only; A Unix timestamp in milliseconds representing when the engagement was last updated.
    "ownerId": 1,
    // Integer; the ID of an Owner object that will be set as the owner of the engagement.
    "type": "NOTE",
    // String; One of NOTE, EMAIL, TASK, MEETING, or CALL, the type of the engagement.
    "timestamp": 1409172644778
    // Integer; A Unix timestamp in milliseconds representing the time that the engagement should appear in the timeline
  },
  "associations": {
  // A set of associated object IDs
    "contactIds": [2],
    // A list vids of associated contact records
    "companyIds": [],
    // The companyId of the associated company. Engagements should only be associated with a single comapny
    "dealIds": [],
    // A list of dealIds of associated deal records.
    "ownerIds": [],
    // Deprecated, use the ownerId to associate engagements with an owner. 
    "workflowIds": [],
    // Deprecated, has no effect on the engagement
    "ticketIds": []
    // Deprecated, has no effect on the engagement
  },
  "attachments": [
  // For NOTE type engagements, a list of ids of files from the file manager that should show up in the attachments list when viewing the record in HubSpot
    {
      "id": 4241968539
    }
  ],
  "metadata": {
  // A set of data specific to the type of the engagement. See below for more details.
  }
}

For note engagements, the type should be 'NOTE', and the metadata needs to have the following format:
"metadata": {
    "body": "note body"
    //String; The body of the note. The body has a limit of 65536 characters.
}

For email engagements, the type needs to be set to 'EMAIL, and the metadata needs to have the following format:
"metadata": {
    "from": {
    // The details of the sender
      "email": "email@domain.com",
      // String; the email address of the sender
      "firstName": "First",
      // String; The first name of the sender
      "lastName": "Last"
      // String; The last name of the sender
    },
    "to": [
    // The details of the recipient
      {
        "email": "contact name <test@test.com>"
        // String; the email address of the recipient 
      }
    ],
    "cc": [],
    // A list of details for anyone cc'd on the email.
    "bcc": [],
    // A list of details for anyone bcc'd on the email.
    "subject": "This is the subject of the email",
    // String; The subject of the email
    "html": "<div>This is the body of the email</div><div><br></div><div>-Me</div>",
    // String; The body of the HTML email
    "text": "This is the body of the email\n\n-Me"
    // String; The body of the text-only email.
}

For tasks, the type needs to be "TASK"
The 'Assigned to' field will be the owner set by the ownerId in the engagement data.
The metadata format is:
"metadata": {
    "body": "This is the body of the task.",
    // String; The body or details of the task
    "subject": "Task title"
    // String; The subject or title of the task
    "status": "NOT_STARTED",
    // String; One of NOT_STARTED, COMPLETED, IN_PROGRESS, WAITING, or DEFERRED.
    // The status of the task
    "forObjectType": "CONTACT"
    // String; One of CONTACT or COMPANY, what object type the task is for.
}

For meetings, the type should be "MEETING", and the metadata is:
"metadata": {
    "body": "This is the description.",
    // String; the details or body of the meeting
    "startTime": 1456858800000,
    // Integer; A Unix timestamp in milliseconds representing the start time of the meeting
    "endTime": 1456862400000,
    // Integer; A Unix timestamp in milliseconds representing the end time of the meeting
    "title": "Event title",
    // String; the title or subject of the meeting
    "internalMeetingNotes" : "This is the team note"
	// String; internal notes for the meeting, displayed in the team notes when viewed in HubSpot.
}

For calls, the type should be "CALL" and the metadata is:  
"metadata" : {
    "toNumber" : "5618769964",
    // String; the phone number that was called
    "fromNumber" : "(857) 829-5489",
    // String; the phone number that was used as the from number
    "status" : "COMPLETED",
    // String; will be COMPLETED once the call is finished.
    "externalId" : "CAc052aca6842211ab1c548dcfed5c9",
    // String; for calls made in HubSpot, this will be the internal ID of the call
    // Has no effect for engagements created through the API
    "durationMilliseconds" : 38000,
    // Integer; the length of the call in milliseconds
    "externalAccountId" : "AC890b8e6fbebd59158e26046a8dde",
    // String; for calls made in HubSpot, this will be the internal ID of the account used to make the call
    // Has no effect for engagements created through the API
    "recordingUrl" : "https://api.twilio.com/2010-04-01/Accounts/AC890b8e6fbe0d989bb9158e26046a8dde/Recordings/RE3079ac919116b2d22",
    // String; the URL of the recording file 
    "body" : "Details go here"
    // String; the details or notes of the call
    "disposition" : "73a0d17f-1163-4015-bdd5-ec830791da20"
    // String; internal GUID that corresponds to the Call Outcome
}

Docs for this section or API