API Explanation required




We are trying to use the following:

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?


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.


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,


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.



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,


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.