Upcoming: contacts scope sunset

[Dadams]

Last year HubSpot split the contacts scope into more granular CRM scopes, to provide app developers separate access for contacts, companies, and deals (i.e., contacts.read, companies.write, etc.). With privacy and security being a top priority for HubSpot, we will be removing the contacts scope on Jul 31, 2022.

 

What does this mean for you?

All public app developers currently using the contacts scope will need to complete the migration process by July 31, 2022.

If you're working with Private Apps, you should not need to make any changes, as Private Apps have only supported granular scopes since they launched.

 

Migration process

All apps using the contacts scope have had  the OAuth settings updated to use the granular CRM scopes. To complete your app migration and prevent your app from breaking upon contacts scope deprecation:

1. Log in to your developer account, and go into the auth settings for your app.
2. Scroll down and click Scopes to expand the section. If you see any scopes selected that your app no longer uses, remove them and then save the settings.
3. Scroll down to the Install URL (OAuth) section. Click Copy full URL.
4. Update your install URL wherever users install your app. This would be the link that HubSpot users use to connect your app to their account. If your app is in the HubSpot App Marketplace, this link would be presented to users on the page that they get to when they click Install app.
5. Replace any references in your app's code to the contacts scope and replace them with the associated granular CRM scopes (e.g., replace contacts with crm.objects.contacts.read).

When is this happening?

The contacts scope will no longer function starting on July 31st. After this, any OAuth authorizations using the contacts scope will result in an error. This will include users installing apps in a HubSpot account, as well as refreshing access tokens.

Please let us know if you have any questions by replying below.

[BKerkhoven]

I am a little confused with what needs to be changed. Our developer accountshows the correct new granular CRM scopes for contacts, ex: crm.objects.contacts.read. So for that part I know we are good. But we are using the following to retrieve the contacts:

https://api.hubapi.com/contacts/v1/lists/recently_updated/contacts/recent?count=100

Does it need to be changed to the following:

https://api.hubapi.com/crm/v3/objects/contacts//associations/?count=100 and if we do need to update the url, how do we differentiate between recently_updated contacts and recently_created contacts?

The v1 contacts api call that we are using is still working up till now. On July 30th will it no longer work?

And I agree with Walter. Even though this is part of a bigger project, like Jayceee said in her response, nowhere in the documentation is the date of July 30th listed for the sunsetting of this scope. It has definitely left us scrambling trying to make sure our code will still work...

Thank you for the reply,

Bryan

[walterl]

I understand this is critical, but giving devs 30 days in a vacation period is not really a proper way of managing this transition. same as with the API keys, is there a way to either notify earlier or ask for exceptions by portal (hubID)?

[Jaycee_Lewis]

Hey, Walter. Thanks for your comment. For additional context, this is the last notice in a longer-term project — a final nudge and follow up to act if you haven't already. Here is a link to the previous developer documentation outlining the changes and the expected timeline — Contacts Scope Migration for App Partners.

The team has been migrating active listed and unlisted apps to granular CMS scopes since 2021. This final push is for apps that have a low install rate — typically 1-2 installations. If you have concerns specific to your app, please don't hesitate to reach out to your Account Manager directly to continue the conversation.

Best,

Jaycee