Upcoming Sunset: v2 Owners API

[hseligson]

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 discussion below.

[SHinojosa3]

Hi,

How much time should we expect to dedicate to this project?

[hseligson]

Hi @SHinojosa3, Thank you for your question! Unfortunately, we can't estimate this. If you're a developer, the changelog and the v3 Owners API documentation should have the technical details to identify the steps needed to update your integration. 
However, if you need a developer or developer resources, I suggest you contact your CSM (Customer Success Manager) or browse our solution partners to help you make the necessary changes!

[PranavRD]

Hi @hseligson,
With regards to the upcoming sunset, I have a requirement of fetching users who are active (isActive field in v2 version set to true). How do I identify such users in v3 API, as its returning active and inactive users in the response and there is no field to distinguish the same. 
P.S The archived field is false for 2 users. However, one user is active and the other one is inactive (as seen in the Hubspot UIInactive user as seen on Hubspot UIBoth active and inactive users returned in the v4 response

[hseligson]

@PranavRD - Thank you for sharing this use case! I shared this with one of our engineers, who pointed out that the user (userId: 64483100) shared on the screenshot above seems active based on the User API. The Owners API  returns the same result as the Users API, indicating that the user is active, so the userId field is populated, archived, and set to false. Can you clarify what filter/spec you used to indicate that the user is inactive - was this only the UI, and did you deactivate or remove the user when it prompted you to review?

We ask because it's best to follow the instructions in the v3 Owners API doc to distinguish whether a user is active. If you request all inactive users to a specific portal using the archived=true in your query param, it returns inactive users. For example, if you leverage: crm/v3/owners?portalId={portalId}&archived=true the response will look something like this: 

{
   "results":[
      {
         "id":"643062423",
         "email":"user@example.com",
         "firstName":"conflict",
         "lastName":"user",
         "userId":null,
         "userIdIncludingInactive":62387149,
         "createdAt":"2023-12-10T07:54:25.141Z",
         "updatedAt":"2024-08-26T07:46:37.609Z",
         "archived":true
      }
   ]
}

[PranavRD]

@hseligson Thank you for the quick response!
In Hubspot UI, as attached in the above screenshot, there is an Inactive Users section which redirected me to the page showing 1 record whose last active was more than 6 months old. I am also attaching the filter/spec that is being shown in the UI.

Filter/spec applied on clicking review users under Inactive Users option
I am also little curious to know on how a user is considered as inactive in Hubspot.
1. Is it when they have not logged in last 90 days as shown in the UI?

2. Is it when the user is deactivated?, or

3. Is it when the user is deactivated and deleted from Hubspot?

[hseligson]

Hi @PranavRD, Of course! HubSpot users are considered inactive based on their last login activity.  However, the exact criteria for determining inactive users may vary depending on how HubSpot has been configured by your organization.

To add your specific questions:

• In many cases, an inactive user is classified as someone who has not logged into HubSpot within a certain period of time, such as 90 days. This is a common threshold used in many systems to identify inactive users.
• Inactive users can also include those who have been deactivated by an administrator. Deactivating a user typically means that they are no longer able to access the system or perform any actions within it.
• If a user is both deactivated and deleted from HubSpot, they would likely be considered permanently removed from the system and no longer counted as an active user.
• The criteria for identifying inactive users can be customized in HubSpot, so it's always a good idea to check with your system administrator or refer to your organization's specific policies to better understand how inactive users are managed within your HubSpot instance.

I hope this information helps!

[JSincavage]

V2 returned the "signature" property for owner (if it exists). V3 does not. Can this be added? If not is there anyway to get this property with the API? 

[hseligson]

Hi @JSincavage - Hello! Thank you for your question and for inquiring about this prop. 

Initially, we thought this would be a straightforward addition. However, we must coordinate with another team to evaluate the feasibility. In the meantime, we are reviewing your request in more detail and will let you know as soon as we have more information. Thank you for your patience and understanding!

[VIntegrations]

In version 2 there was an attribute called "type" that use to returned "PERSON" or "QUEUE" values. In version 3 this attribute does not longer exists. How can I differenciate now which type of owner I'm receiving?

[hseligson]

@VIntegrations—Good news! Our engineering staff was able to include the type field in the result. Feel free to try it out, and please let me know if there are any issues! The API documentation for the v3 Owners API will soon reflect this new type.

[hseligson]

Hi @VIntegrations, I apologize for missing this comment! I have reached out to our engineering team about adding the "type" property. We are aiming to incorporate this into the new v3 Owners API. I expect to receive more feedback from our engineering team by next week. Thank you!

[WayneL]

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.

[Sachavskyi]

@WayneL There is archived=true param

[Sachavskyi]

Great news, but:
In response for owners/v2/owners I can get userId from field userIdIncludingInactive even for archived users:

And what do we have in crm/v3/owners? How to get the userId via the new API for archived users?

This has to be fixed ASAP. And fire your API developers, please

[hseligson]

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?

[Sachavskyi]

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 hs_created_by_user_id is the same user as in hubspot_owner_id

[hseligson]

@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]

@hseligson I can't use webhooks because sometimes users may be deleted before the client connects his HS account to my application.

[hseligson]

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

[Sachavskyi]

@hseligson Your dev team has added userIdIncludingInactive field to archived users as I see. Could You approve that it will work permanently?