On August 30, 2024, we will be sunsetting the v2 of the Owners API.

We encourage users to migrate to the v3 of the Owners API because all endpoints from https://api.hubapi.com/owners/v2 will be sunset and return a 404 error response message.

What's changing?

The data returned by both versions of the API is similar, but there are a few differences for the v3 API:

• The ID of the owner record in the `ownerId` field in v2 is replaced by the `id` field in v3
• The `remoteList` and related remote IDs are no longer supported in the v3 API
• The HubSpot user ID is included in the `userId` field instead of being included as a remote ID.

Below are the listed ways we suggest migrating from Owners API v2 to Owners API v3 and any applicable changes to be aware of:

• Migrate GET api.hubspot.com/owners/v2/owners/{ownerId} to use GET api.hubspot.com/crm/v3/owners/{ownerId}.
  • The ID values for owner records are the same between the versions of the API.
• Migrate GET /owners/v2/owners/ to use GET /crm/v3/owners.
  • The v2 Owners API endpoint returns all owner records at once, while the v3 endpoint will only return up to 500 records at a time, so this migration requires you to implement paging to get all of the records.
    To page through all results, you'll need to use the `paging` data returned in the response. Use the `paging.next.after` field in the response as the value of the  `&after=` query parameter in your next request to get the next page of results.
  • This endpoint supports filtering by email, so you can search for a specific owner by email using the `email=` query parameter.

Please note: Because the v3 Owners API uses pagination, you need to make multiple API requests to obtain the complete list of owners. Therefore, it is crucial to monitor your usage to avoid hitting the rate limits.

When is it happening?

This sunset goes into effect on August 30, 2024. Read more about our Owners v3 API, view examples, and begin planning your migration to the new API version.

Questions or comments? Join us in the developer forums.