APIs & Integrations

Not applicable

API Explanation required

Hi,

We are trying to use the following:

Get recently updated and created contacts | Contacts API

GET /contacts/v1/lists/recently_updated/contacts/recent - For a given portal, return all contacts that have been recently updated or created. A paginated list of contacts will be returned to you, with a maximum of 100 contacts per page, as specified...

However we are struggling to understand why vidOffset is required and what it does. Doing a request without vidOffset, returns different records every time even though the timeOffset is the same?

0 Upvotes
5 Replies 5
Derek_Gervais
HubSpot Alumni
HubSpot Alumni

API Explanation required

Hi @cegadmin,

I'm not sure what you mean; are you keeping timeOffset static and varying vidOffset? Or something else? Both parameters are combined to create a pointer to the right place in the list, so changing them in undocumented ways might produce strange effects.

To pull all records modified since X, you'd need to start with the first page of most recently modified contacts and page backwards until the last_modified_date property is equal to / older than the date X you're interested in.

0 Upvotes
Not applicable

API Explanation required

@Derek_Gervais

Hi Derek,

Thanks for your reply. Why is it when I provide a static "timeOffset", the values returned still change on every request?

Additionally, how would I get all modified since X time, lets modified in the last 3 hours (7am to, now, 10am)?

Kind Regards,
Regson

0 Upvotes
Derek_Gervais
HubSpot Alumni
HubSpot Alumni

API Explanation required

Hi @cegadmin,

Each response from this endpoint includes a top level vid-offset and time-offset field, like this:

 {
  "contacts": [
// Contact info here...
],
  "has-more": true,
  "vid-offset": 3714024,
  "time-offset": 1484854580823
}

You'll want to include these two values in the vidOffset and timeOffset parameters of your next request. This will return the next page of contacts; the time-offset field will give you an idea for where the 'Last modified date' property for each page of contacts starts, and you can parse the contacts in the contacts array for more precise information on when each specific contact was updated.

0 Upvotes
Derek_Gervais
HubSpot Alumni
HubSpot Alumni

API Explanation required

Hi @cegadmin,

When you request contacts from this endpoint, it returns a page of contacts (no more than 100) in order of most recently updated/created. To return the next page, you need to include the vidOffset and timeOffset so that the service knows exactly where in the list to start returning contacts. The system uses both vidOffset and timeOffset to track where in the list you are.

0 Upvotes
Not applicable

API Explanation required

Hi @Derek_Gervais,

Thanks for your response. Here's a bit more context to help you understand how we are trying to use this API:

We need to get all of the contacts which have been updated since the last time we have made the request. When we make a request, we understand that the returned results are paginated, however we don't understand what the values of vidOffSet and timeOffset are supposed to take.

In normal cases of paginated API results, I would expect to hand in index offsets (record 1-100,101-200,201-300 and so on). vidOffset and timeOffset don't seem to take values of an index offset.

How are we supposed to use these values to get all modified records since the date of our last request?

Thanks again for your help.
Kind Regards,
Regson

0 Upvotes