GET Contact's Engagements via API


We want to be able to synchronize contact information from our system to HubSpot and vice versa. But I’m stuck trying to figure out how contact notes will sync. I can see how to push contact notes to HubSpot by creating an Engagement. But if someone adds a note to a Contact on HubSpot, I don’t see how to access that via the API to update the contact on our system. Is that possible? I hope!


Hi @jreily

We don’t currently have an API to get engagements associated with a contact, but it’s something we’re working on now and we plan on having that ready soon.



Hi @dadams,
We are currently on the integration with Spiro and the Hubspot engagements are critical as a source for our machine learning recommendations. When are you guys expecting to expose this API? Is there a way that we could get into a BETA program for this :slight_smile:



Sorry, I’m a bit of a novice when it comes to APIs, but does this mean that there is no way to export all of the engagements out of the CRM? Meaning, if we decide to leave HubSpot’s CRM, our data is trapped? I was unclear from this posted link: Thank you.


@kevindp There’s a new endpoint that can be used to get all engagements that was created after the last update in this thread.


Thanks for your reply. A few questions:

  1. If I want to migrate away, I’ll likely have more than 250 engagements at that point. How can I get the remaining engagements if 250 is the limit for the API?

  2. When I try to use the API, I get, {“status”:“error”,“message”:“This hapikey (MY KEY) does not have proper permissions! (requires any of [contacts-read])”,“correlationId”:“BIG-STRING-OF-NUMBERS-AND-LETTERS”,“requestId”:“ANOTHER-STRING-OF-NUMBERS-AND-LETTERS”}. Can you help me understand what I’m doing wrong? Do I need to connect this account somehow with my CRM?

  3. How can I convert the API data to a CSV document?


Hi! Just checking in to see if anyone has answers related to these questions. This is the last thing that’s keeping us from going full-bore with Hubspot. Thank you in advance!


@kevindp The Engagements API supports paging, so you’ll only be able to get 250 items in a single request, and then use the offset= parameter to get the next set of records, until the response has "hasMore": false

Are you using the hapikey from the developer portal? The Developer HAPIkey can only be used to access the integrations platform settings (currently the Timeline and Webhooks APIs). You’d need to get the API key from the specific portal you’re trying to get the engagements from.

Engagements aren’t a flat object, so they won’t translate directly to a CSV and you’d need to decide what data you’d want in the CSV, but most languages have existing libraries to create CSVs after you decide what data you want.


Thank you. I’ve been able to get the All Engagements report. The next trick is to make sure that I can relate an engagement to a contact. The Engagement record uses “contactIds”. When I export all Contacts, I get “vid.” Are these one and the same?


This same question here. We would like to know last user behaviour and engagement in Hubspot in external tool for customer success (freshdesk). How we can get user history in API?