There's a new version of the HubSpot API

As of November 30, 2022, HubSpot API Keys are being deprecated and are no longer supported. Continued use of HubSpot API Keys is a security risk to your account and data. Your API Keys could be deactivated at any time after Nov. 30th, and we recommend that you migrate to Private Apps as soon as possible so you do not lose business-critical functionality.

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).