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 discussion below.
Hi @kristinaw - Thank you very much for your question! I have sent you a direct message to gather more information and provide some feedback. Please let me know if my message addresses your concern or not. If not, I would be happy to assist you once I have more information. Thank you!
Hi @WDeCesare - Thank you so much for your question! Can you clarify if you meant HubSpot’s integration with Snowflake? If this is the case, then it will not be affected by the sunset. Please let us know - thank you!
I’m filling in for someone who set up our interfaces and are no longer with the company. I need a bit more direction on this. Can someone contact me directly please?
Hi @rweber7 - Thanks so much for reaching out and sharing your concerns! If you’re a developer, the changelog and the v3 Owners API documentation should have the technical details needed to update your integration.
However, if you are in need of a developer or developer resources, then I suggest you contact your CSM (Customer Success Manager) or browse our solution partners to help you with the changes needed!
Hi @Sachavskyi - Thank you for the comment! As you pointed out, it’s unclear if there is a way to get the userId for an archived owner record in the v3 Owners API. Do you mind me asking what you need that userId for archived users for?
There are 2 field types with association to user on HS:
with userId:
hs_created_by_user_id
,
hs_updated_by_user_id
…
with ownerId:
hubspot_owner_id
…
I represent just user ids in my application. When I see there is an ownerId in a field value, I will convert it to userId. How can I convert ownerId to a userId for deleted users?
Also, I need to know that in
@Sachavskyi - Thank you for the context and additional information. This is helpful! I recognize that converting an ownerId to a userId for deleted users using HubSpot’s APIs presents a real challenge.
I’ve contacted our tech lead to share your challenge and waiting to gather their feedback. However, I wonder if you could leverage a webhook to notify you when a user is deleted. This won’t directly solve the conversion issue but can help you manage the impact by updating your records in real-time when a user is removed from HubSpot.
In the meantime, to help clarify the field types you inquired about, they are different concepts, meaning hs_created_by_user_id is used to identify the userId of who created a record, whereas the hubspot_owner_id indicates who currently owns or is responsible for the record.
hs_created_by_user_id: This field usually indicates the user ID of the person who created a specific record in HubSpot. This could be the ID of a user who created a contact, deal, ticket, etc., directly in the HubSpot interface or through an integration/API. It’s used to track the origin of a record within HubSpot.
hubspot_owner_id: This field refers to the owner of a record in HubSpot. The “owner” is typically the user assigned to a contact, deal, company, or ticket and is responsible for managing that record. Ownership can be manually assigned by users within HubSpot or automatically through workflows or other assignment rules.
I will follow up with you once I receive additional input from our tech lead!
@Sachavskyi - Understood! I spoke with our engineering lead, and they will work on updating the v3 PublicOwner response with a new userIdIncludingInactive field to provide this missing information this week.
I will follow up with you once it’s implemented.
Hi @Sachavskyi - Yes, this is correct. It was added yesterday, and we are just waiting for our tech writers to update the API documentation for the v3 Owners API with this new field.
In v2 Owners API, there is a param called includeInactive which I can a get full list of owners (active & inactive) when I set to true. But, In the V3 API, this archived param can only get it to return either active users or inactive users. This removed the ability of the api of returning a full list. I don’t think returning inactive owner ONLY is a better subsitution of returning a full list. This crm/v3/owners api is supposed to be working the same as the original v2/owners api. Can you add back IncludeInactive param please? Thank you.
