Create an Engagement | Engagements API

There's a new version of the HubSpot API

Check out the new API

As of November 30, 2022, HubSpot API Keys are being deprecated and are no longer supported. Continued use of HubSpot API Keys is a security risk to your account and data. Your API Keys could be deactivated at any time after Nov. 30th, and we recommend that you migrate to Private Apps as soon as possible so you do not lose business-critical functionality.

Method Details

HTTP Methods:

POST

Content Type:

application/json

Response Format:

json

Requires Authentication?

Yes

Rate Limited?

Headers

Products:

Marketing & CRM

Required Scope:

crm.objects.companies.write
crm.objects.contacts.write
crm.objects.deals.write
tickets
e-commerce

Use this endpoint to create an engagement (an email, call, meeting, task or note) on an object in HubSpot.

Use case for this endpoint: This endpoint is useful for keeping your CRM records up-to-date on any interactions that take place outside of HubSpot. Activity reporting in the CRM also feeds off of this data.

Associations

You can associate engagements with objects to ensure they're displayed correctly in the UI. (See example request body to the right.)

Tasks created through HubSpot's API will not trigger user notifications.

Required parameters	How to use	Description
OAuth access token or API key	Authorization: Bearer {token} header or hapikey={key} query parameter.	Used to authenticate the request. Please see this page for more details about authentication.
Engagement JSON	Included in request body	An object representing the engagement you have created. See below for more details.

When creating an engagement, you will POST an engagement object containing the following data:

For note-type engagements, the body of the note will be limited to 65536 characters.

Field	Description
type	Required. One of: EMAIL, CALL, MEETING, TASK, NOTE
metadata	Required. An object representing the details of the engagement. See the examples to the right for details about the format of the metadata for specific engagement types.
ownerId	Optional long, corresponding to an Owner. Task engagements use the ownerId to populate the Assigned to field.
timestamp	Optional timestamp (in milliseconds). This timestamp will be treated as the time that the engagement happened, and will determine where the engagement appears in the timeline for any associated records.

Response details

If the request is successful, returns a 200 response with the JSON of the new engagement.
If the request is unsuccessful, returns a 4xx response with error details.

Example POST URL: https://api.hubapi.com/engagements/v1/engagements?hapikey=demo Example POST body (this example is for a NOTE engagement): { "engagement": { "active": true, "ownerId": 1, "type": "NOTE", "timestamp": 1409172644778 }, "associations": { "contactIds": [2], "companyIds": [ ], "dealIds": [ ], "ownerIds": [ ], "ticketIds":[ ] }, "attachments": [ { "id": 4241968539 } ], "metadata": { "body": "note body" } } The optional "attachments" parameter accepts a list of file IDs, corresponding to IDs you get for files from the CMS Files API. For email engagements, the type needs to be set to "EMAIL", and the metadata needs to have the following format: "metadata": { "from": { "email": "email@domain.com", "firstName": "First", "lastName": "Last" }, "to": [ { "email": "contact name <test@test.com>" } ], "cc": [], "bcc": [], "subject": "This is the subject of the email", "html": "<div>This is the body of the email</div><div><br></div><div>-Me</div>", "text": "This is the body of the email\n\n-Me" } 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.", "subject": "Task title", "status": "NOT_STARTED", "forObjectType": "CONTACT" } The status needs to be NOT_STARTED, COMPLETED, IN_PROGRESS, WAITING, or DEFERRED. For meetings, the type should be "MEETING", and the metadata is: "metadata": { "body": "This is the description.", "startTime": 1456858800000, "endTime": 1456862400000, "title": "Event title", "internalMeetingNotes" : "This is the team note" } For calls, the type should be "CALL" and the metadata is: "metadata" : { "toNumber" : "5618769964", "fromNumber" : "(857) 829-5489", "status" : "COMPLETED", "durationMilliseconds" : 38000, "recordingUrl" : "https://api.twilio.com/2010-04-01/Accounts/AC890b8e6fbe0d989bb9158e26046a8dde/Recordings/RE3079ac919116b2d22", "body" : "

" } Additionally calls now support HubSpot backed transcription. NOTE We will only transcribe calls associated with an `activity created by` user that has a paid Sales or Service hub seat. We only accept .WAV, .FLAC, and .MP4 formats. "metadata":{ "toNumber": "5735786232 ", "fromNumber": "6179030296", "status": "COMPLETED", "durationMilliseconds": 38000, "title" : "Call with Test", //new attribute (auto-created if not specified) "recordingUrl": "https://audiourl", // We support WAV file/ FLAC. We can take mp4's but the transcription may be worse "source" : "INTEGRATIONS_PLATFORM", // new attribute, optional "appId" : "123" // new attribute } Returns a 200 response with the JSON of the new engagement on success: { "engagement": { "id": 328550660, "portalId": 62515, "active": true, "createdAt": 1494352128974, "lastUpdated": 1494352128974, "ownerId": 1, "type": "NOTE", "timestamp": 1409172644778 }, "associations": { "contactIds": [ 2 ], "companyIds": [], "dealIds": [], "ownerIds": [], "workflowIds": [], "ticketIds": [] }, "attachments": [ { "id": 4241968539 } ], "metadata": { "body": "note body" } }

import requests import json url = "https://api.hubapi.com/engagements/v1/engagements" querystring = {"hapikey":"demo"} payload = json.dumps({ "engagement": { "active": 'true', "ownerId": 1, "type": "NOTE", "timestamp": 1409172644778 }, "associations": { "contactIds": [11877974], "companyIds": [ ], "dealIds": [ ], "ownerIds": [ ] }, "attachments": [ { "id": 4241968539 } ], "metadata": { "body": "note body" } }); headers = { 'Content-Type': "application/json", } response = requests.request("POST", url, data=payload, headers=headers, params=querystring) print(response.text)

var request = require("request"); var options = { method: 'POST', url: 'https://api.hubapi.com/engagements/v1/engagements', qs: { hapikey: 'demo' }, headers: {'Content-Type': 'application/json' }, body: { engagement: { active: true, ownerId: 1, type: 'NOTE', timestamp: 1409172644778 }, associations: { contactIds: [ 11877974 ], companyIds: [], dealIds: [], ownerIds: [] }, attachments: [ { id: 4241968539 } ], metadata: { body: 'note body' } }, json: true }; request(options, function (error, response, body) { if (error) throw new Error(error); console.log(body); });