May 21, 2021

Our plan for Google’s People API migration

CloudSponge has relied on the Google Contacts API for years to make it super easy for your users to access their contacts on your site.

Well, now that is changing. Google has announced their intention to limit and eventually shut down the Contacts API.

This brings up questions for all CloudSponge customers. What does it mean for your Google Contacts access? What is changing? Is anything going away?

Read on, and I’ll answer all your questions.

Firstly, don’t panic. We got you. We’ve been doing this for a long time and have seen lots of transitions between different APIs and we are experts at supporting multiple APIs to give our customers a long window of opportunity to migrate on your own terms. This situation is no different.

What changes do you need to make?

Most customers will want to add a new scope to their Google OAuth Consent settings so that they can continue to show users all the contacts they have email communications with.

We will publish clear step-by-step instructions for you. We also offer a Concierge service where we will do the work for you.

What is the timeline?

May 31, 2021 – You’ll be able to enable the People API and Other Contacts permission on CloudSponge. Once you enable the People API, you are done. Your integration will not be affected by any changes to the Contacts API.

June 15, 2021 – Google Contacts API will fail for 1% of API requests. CloudSponge will automatically retry these failed requests on the People API (without the Other Contacts). Google integration will continue to work for customers who have not completed the People API update.

September 15, 2021 – Google Contacts API will fail for 10% of API requests. CloudSponge will automatically retry these failed requests on the People API (without the Other Contacts). Google integration will continue to work for customers who have not completed the People API update.

December 15, 2021 – Google Contacts API will stop working. CloudSponge will stop trying to use the Contacts API and send all requests to the People API (without the Other Contacts). Google integration will continue to work for customers who have not completed the People API update.

You may notice a theme. Google integration will continue to work for customers who have not completed the People API update. You can do nothing and your integration will keep working.

However, it’s strongly recommended that you do add the new scope so that you keep getting all the contacts.

So, why the new scope?

There is one difference between the People API and the Contacts API that is significant to CloudSponge customers. Google has narrowed how permissions apply to the People API.

The Google Contacts product splits your contacts into two different categories.

My Contacts are the contacts that users have specifically added to their address book.

Other Contacts are people with whom they have had an email conversation. This group is often very useful. Even the people we know well may not be explicitly created in our address book. It’s so easy to find anyone’s email address in Gmail, that there’s low motivation to promote them to My Contacts.

Here’s a comparison of how the two APIs treat these categories differently:

Contacts APIPeople API
contacts.readonlyReturns My Contacts and Other Contacts.Returns My Contacts
contacts.other.readonlyn/aReturns Other Contacts

What else is changing?

There are other changes involved that you don’t have to worry about at all.

The API data format has changed from XML to JSON. The way we retrieve pages of data is different. The structure of each contact, including the field names, has changed in many cases. The way we indicate the fields we want the API to return is new.

But, you don’t have to worry about any of these details. We’re able to isolate you from them.

Reminder

The change you’ll want to consider is adding the contacts.other.readonly scope to your Google OAuth Consent Screen settings. Adding this field will require you to renew your approval from Google. Details are coming next week on how to do this.

If you want us to take care of the update to your Google OAuth, we have a Concierge service available.

Stay tuned for the next steps.

**Update** Check out our migration instructions here.

Graeme Rouse, CTO at CloudSponge

Follow @thunderouse

Try CloudSponge for free in your
testing environment

Get a Free Sandbox Account

Have a questions or prefer a guided tour?
Schedule a consultation with our Founder.