Get Associated Engagements | 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.

This endpoint is deprecated. Please use the new CRM Associations API to view and manage associated engagements.

Method Details

HTTP Methods:

GET

Response Format:

json

Requires Authentication?

Yes

Rate Limited?

Headers

Products:

CRM

Required Scope:

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

Get associated engagements (tasks or activities) on an object in HubSpot. This data is often used for per rep productivity reporting or integration with other back-office tools.

The response will contain:

results: list of associated engagements
hasMore: boolean, true if there are more associated engagements
offset: long, value to use as offset parameter if making another request

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.
Object Type	Used in the request URL (see above)	One of contact, company, or deal, depending on the object you want to fetch engagements for.
Object ID	Used in the request URL (see above)	The ID of the associated object you want to fetch contacts for. This will be the vid for a contact, companyId for a company, or dealId for a deal.

Optional Parameters	How to use	Description
offset	&offset=x	Used to page through associated engagements if there are more than can be retrieved in one page. Defaults to 0.
limit	&limit=x	Set an upper limit on the number of engagements to fetch. Cannot be set higher than 100.

Example URL to GET to: https://api.hubapi.com/engagements/v1/engagements/associated/COMPANY/184896670/paged?limit=2&hapikey=demo

JSON

Initial GET URL: https://api.hubapi.com/engagements/v1/engagements/associated/COMPANY/152408363/paged?hapikey=demo&limit=2 You will receive an object representing the list of engagements and information for requesting the next page: { "hasMore": true, "offset": 161604164, "results": [ { "associations": { "companyIds": [ 152408363 ], "contactIds": [], "dealIds": [], "ownerIds": [], "workflowIds": [] }, "attachments": [], "engagement": { "active": true, "createdAt": 1464380636427, "createdBy": 1201795, "id": 72529655, "lastUpdated": 1464685016313, "modifiedBy": 286756, "ownerId": 20, "portalId": 70000, "timestamp": 1464381900000, "type": "TASK" }, "metadata": { "body": "Set up sales presentation", "forObjectType": "COMPANY", "reminders": [], "status": "COMPLETED" }, "scheduledTasks": [] }, { "associations": { "companyIds": [ 152408363 ], "contactIds": [], "dealIds": [], "ownerIds": [], "workflowIds": [] }, "attachments": [], "engagement": { "active": true, "createdAt": 1474378242244, "createdBy": 1201795, "id": 140212298, "lastUpdated": 1474378242244, "modifiedBy": 1201795, "portalId": 70000, "timestamp": 1474378200000, "type": "CALL" }, "metadata": { "body": "Ring ring ring! Another successful phone call!", "durationMilliseconds": 0 } } ] } The first response indicated that there are more engagements, so make another request using the offset provided: https://api.hubapi.com/engagements/v1/engagements/associated/COMPANY/152408363/paged?limit=2&offset=161604164 { "hasMore": false, "offset": 161604164, "results": [ { "associations": { "companyIds": [ 152408363 ], "contactIds": [], "dealIds": [], "ownerIds": [], "workflowIds": [] }, "attachments": [], "engagement": { "active": true, "createdAt": 1474378312742, "createdBy": 1201795, "id": 161604164, "lastUpdated": 1474378312742, "modifiedBy": 1201795, "portalId": 70000, "timestamp": 1474378312742, "type": "NOTE" }, "metadata": { "body": "They're really interested in our business products. These guys know what they're doing!" } } ] }