There's a new version of the HubSpot API

We're also working on a new documentation website, you're invited to check it out and give us your feedback.

How do I use vidOffset and timeOffset when pulling a list of recent contacts?

When pulling recently updated and created contacts (GET /contacts/v1/lists/recently_updated/contacts/recent) or contacts recently added to a list (GET /contacts/v1/lists/:list_id/contacts/recent), each request will return a vid-offset and time-offset value.  These values must be used together to get the next page of records.

The first request to the endpoint returns the most recent records, and the following requests would contain the next most recent records.  The time-offset value in the response is a timestamp that represents the time that the least recent record, in that set of records, was updated or added, so you can use that value to determine when you have all of the changes since the last time you checked for updates.

As an example, if you were looking for recently created or updated records, and the last time you checked for records was April 2nd, 2015 1:00:00 PM EDT (which is a timestamp of 1427994000000), you would start by making the first request to get the most recent updates:

Which would return a list of contacts, and the offsets:
{ "contacts" : [...],
  "has-more" : true,
  "vid-offset" : 267292,
  "time-offset" : 1428077720267}

The next request would use the vid-offset and time-offset in the request URL (note the camel-casing of the URL parameters):

You would repeat this, paging backwards, until you reached a time-offset less than 1427994000000 (at which point you would have all new updates since the last time you checked).