Apr 6, 2020 3:56 PM
As we continue to build the next generation of HubSpot’s APIs to provide the consistency and completeness our developer community has requested, we are excited to announce that a net new API and several more updated APIs are now in developer preview.
A brand new Events API
Since the Analytics API was released in early 2018 developers have been able to retrieve their aggregated analytics report data, including page views, CTA clicks, form submissions, etc. However, some of our earliest feedback has turned out to be our most consistent: customers also need the API to provide their raw, unaggregated data.
Today, we are excited to introduce a new Events API, which features endpoints to retrieve event data for web activities such as page views and form submissions. The new endpoint allows developers to find and filter events associated with a CRM object (e.g. contacts, companies, deals, etc.) of any type. These events show the interactions the selected object has had within the HubSpot system. With this new API, developers will be able to:
Currently two events are supported `e_page_views` and `e_form_submissions` with more to come in the near future.
Updated Ecosystem APIs
We’ve updated the Timeline, and Custom Cards API to be more consistent with our latest version of the CRM APIs. The biggest change comes to the Timeline API which is now treating events as immutable. This means that if an integration relies on being able to update an event, it should not be updated to this version of the API. We are currently considering alternatives to supporting integrations that currently rely on updating event information. Please join the conversation here if you are relying on this functionality.
Updated CMS APIs
The Domains, URL Redirects, and Site Search APIs have also been updated to be consistent with the latest version of the CRM APIs. Regardless of which system developers interact with, they can use the same patterns. We believe this is a big win for the usability of our APIs.
What this means for developers
Start testing out these endpoints. Developer preview is the perfect time to let us know what you think. We’ll be collecting and iterating quickly on your feedback, which could mean breaking changes. It’s not recommended to use these endpoints in a production environment yet, but we’ll let you know when they’re ready.
If you have any questions, please join the conversation here
May 4, 2021 8:33 PM
Thanks Zack. Yep, agreed that custom objects often work well for these use cases (we are big fans of custom objects!). Unfortunately not all of our customers have an enterprise license and so don't have access to custom objects. That is a dilemma we have, we don't like setting up new integrations for customers using features that may be discontinued at a future date, so we can encourage the customers to upgrade their license level however for cost reasons that is not always possible.
May 4, 2021 4:00 PM
Hi @TimMunro ,
Thanks for those examples. To answer the immediate question, you can continue use the previous version of the Timeline API for this, we have no plans to end of life that at this time.
Looking forward what we used to think about as a single Timeline Event, will likely be better served as either a Custom Object with a Timeline Event, or just a Custom Object. If we take a look at the ATS use case, the application, with it's status (and any other data you might want to capture) would be an object while the actual act of submitting an application would be an event.
The timing isn't quiet right for actually moving to this approach in my opinion. I mention it here to offer some insight into how we are thinking about this and why the newer version of Timeline Events assumes immutability.
Let me know if you have any other questions or concerns here.
May 3, 2021 7:17 PM
Re "Timeline API ... is now treating events as immutable": this change poses challenges for some of our integrations.
Here is an example:
Connecting HubSpot to Applicant Tracking Systems (ATS) e.g. Greenhouse
A candidate can submit many job applications into the ATS, these are sent to HubSpot as custom timeline events against the contact (one timeline event per unique application). One of the tokens included in the event sent to HubSpot is the application status (e.g. new, under review, accepted, rejected). Using this approach, rather than creating a unique event per status change, offers the following benefits:
1) Allows for simpler workflow/list setup in HubSpot (e.g. list containing all candidates that have an application with status 'new')
2) Less "noise" and data duplication in the timeline events view in HubSpot (i.e. will be a lot more events if creating one event per status transition)
Another similar use case:
Connecting HubSpot to a platform that holds customer Contract/Agreement data:
Wish to create one timeline event per contract against the HubSpot Company timeline. This allows allows for simple workflow rule creation, however when a particular contract is cancelled we would update the timeline even'st "Contract status" token to ensure those contracts (& so the associated Companies/Contacts) are excluded from future HubSpot workflows.
So, would you recommend we continue to use the legacy timeline events API for these use cases, or use a different strategy? Will we start hitting end of life issues for the now legacy timeline events API?