Engagements overview

Engagements are used to store data from CRM actions, including notes, tasks, meetings, and calls. Engagements should be associated with at least one contact record, and optionally other contacts, deals, and a company record.

The Engagements API can be used to create engagements, in order to log calls, notes, or emails from an external system, and also to get the engagements to track what actions have been happening in HubSpot. 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 can 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, and new engagement types going forward. While these non-documented engagement types may appear when reading engagements, creating/editing them is not supported.

For more detail on how the disposition field relates to the Call Outcome, please see this endpoint.

Individual engagements will have the following data:

{
  "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
}

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
}

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