Timeline api integration


I am very new to hubspot. What is the process of timeline API? I want to track the user login, last login time, transaction initiate time, completed time, cancel time etc.. Anyone suggest the correct API integration from hubspot to track. Is the timeline API works for my requirement?


Welcome, @viswa46.

The Timeline API sounds like the best match for your use case. You can populate different events on contact, company, or deal record timelines, set custom properties, including timestamps, and segment on these properties in HubSpot active lists and workflows.

I think you may wish to create different timeline event types for the different interactions/events you are tracking. For example, one event type could be used to record log ins while another type would record log outs.

Please keep in mind that the Timeline API only allows you to write information to a contact, company, or deal record. You will actually need to track the log ins/outs with your own system and then call HubSpot when an action occurs that you want recorded.

Could you clarify what you mean by "transaction initiate time, completed time, cancel time"? It almost sounds like you are describing deals, which are separate objects from contacts. They are best used to reflect "transactions" which may have a monetary value associated with them. Let me know if you would like additional insight here.


Thanks for your time man. one more concern on OAuth. Every time user logged in, we need to establish authorization url with redirect url to grant access. can we do grant operation internally instead of taking user to hubspot page to select account? because user don't know which account they have to select.


And when i try to create new event for event type signup, getting response as 204 no content. is this good? where i can see the contact timeline. I tried in postman. below are the input


do we need to create contact using contact API for tracking contact timeline event? I don't know the process. Straightaway i created event type and trying to add event. is that fine?


Hey, @viswa46.

To address your first post, the OAuth connection process described here only happens between your HubSpot developer app and your production HubSpot account — your users will not have to go through the process whenever they log in.

Once you have created an app (it looks like you already have here) and connected it to your production HubSpot account, the path is something like this:

  1. User enters their login credentials on your site.
  2. Your backend system verifies the user's credentials and logs them in.
  3. Your backend system makes an OAuth-authenticated call to your app with this endpoint with the information for the login event.
  4. HubSpot verifies the call and creates a new login event on that user's contact record timeline.

Per your second question: Yes. When you call this endpoint, a 204 response indicates success.

Per your third question: No. You do not need to create a contact with the Contacts API before creating a timeline event for them. As noted in the section 5 Associating the event with a CRM object, in this article:

Email addresses must be unique for contacts in HubSpot, so if there is an existing contact with the provided email, that contact would be updated, but if no contact exists under the email address you provide, a new contact will be created. By default, this new contact will only have the email contact property provided.

Said differently, if you pass a new email when creating an event, it will automatically create a new contact record for you.

To be transparent, I'll be heading on vacation shortly, so I may miss your responses. While I'm out of office next week, my teammates @Derek_Gervais and @Connor_Barley will be keeping an eye on my ongoing threads.


I still have concern on connecting developer account with hubspot account internally. For timeline event, we need access token. we will get that only by calling authorization url and that will redirect to select account, after that that will go to redirect url. how we can make it as internally? can i get any demo or example with real time for this API?


I have gone through OAuth demo app. there also hubspot page is loading to select the account to grant access. can't we select account internally?


Hi @viswa46, since Isaac is out on vacation I'm happy to respond. Are you asking if you can bypass selecting the account you'd like to install an application to? If so, that isn't possible. Many people can be part of multiple HubSpot accounts, so you must select the account you'd like to install the app to. This is also a confirmation step so that the user knows that this account will be installed and the scopes that the app is requesting.


Thanks man
No. Let's take one example. Say my website is Yahoo mail. I have hubspot account and developer account as well. Within developer account I have application and event type. Everything is set. Now, user try to login in Yahoo mail. I have to add the user to timeline. Whenever user login, how to establish the connection between app and account internally? Because user logs in, I have to call the authorization url. Then it goes to the hubspot list of accounts page to select. But don't know the hubspot and what account have to select and all. Have you gone through all thread here?


You mentioned (This is also a confirmation step so that the user knows that this account will be installed and the scopes that the app is requesting).here who is the user?


@Connor_Barley how to establish connection between application in developer account and hubspot pro account internally or automatically? can you show any demo right from the connection establish to create event in contact's timeline?


Hi @viswa46 I've read your conversation. I'm not entirely sure of your question here. To clarify about OAuth, the way it works is that a user will install your integration one time to their live HubSpot Account. This will happen one time and the application will show up in their integration settings. It will remain there until a user uninstalls the application.

The Quickstart App is an example of how OAuth works. Once users select their HubSpot account from this screen: http://prntscr.com/m5wmnd and are redirected, they have successfully installed the application to their account. Then they are redirected to the redirect URI, and your program's code (written in any server side language) will grab the code parameter from the url (or if testing, you can grab this value manually), then use that to generate an access and refresh token. The access token is what you use in the Header of your HTTP request to authenticate requests to the Timeline API.

The user is somebody who is installing your application to their own HubSpot Account.


Is One time code generation is enough to generate access token for life Time?


Hi @viswa46, yes. When you choose your account at first you are granted 1. An Access token and 2. A refresh token. Access tokens expire every 6 hours, so you can continually generate new Access tokens from the refresh token via this endpoint: https://developers.hubspot.com/docs/methods/oauth2/refresh-access-token in order to authenticate your HTTP requests


Cool. This is what I want man. Thanks a lot.


@Connor_Barley if refresh token itself expires, can we generate new access token with same code ?
and can i know the expire time for "refresh token" and type of access token like JWT or someother?


Hi @viswa46, the refresh token doesn't expire unless you delete it yourself. If your refresh token happens to expire you can hit this endpoint again and get a new one.


Cool. One more thing. I want to add last login event in contact's timeline. For that, I want to fetch the login event from contact's timeline to find last login and add in to last login event. So how to filter like this?


Hi @viswa46, you'd have to do this calculation externally. Using the GET timeline event endpoint is likely your best bet, so that you can then get the timestamp for that event and calculate the difference.