Contacts API Migration Guide

The Contacts API was turned down on January 19, 2022. Use this guide to learn about changes to fields, endpoints, and authorization scopes as you migrate to the People API.

Overview

The People API has the same functionality as the legacy Contacts API for all features, with the following exceptions for Other Contacts:

  • Administrators have read-only permissions for "Other Contacts" through the new scope. As sending mutate/write signals back to "Other Contacts" is not supported, your users will have to add the Other Contact as a My Contact if they wish to update its data fields.

  • Only basic contact information for "Other Contacts" can be read through the API. For example, full name, email address, and phone number.

Additionally, the old Contacts scope (https://www.google.com/m8/feeds), which provided access to both personal contacts and directory information, is replaced by the following scopes:

  • To access personal contacts: https://www.googleapis.com/auth/contacts
  • To access directory information: https://www.googleapis.com/auth/directory.readonly

Contacts

Fields Mapping

Contact Field Person Field
atom:content biographies
atom:link rel='http://schemas.google.com/contacts/2008/rel#photo' photos
atom:title names
gContact:billingInformation miscKeywords (type=OUTLOOK_BILLING_INFORMATION)
gContact:birthday birthdays
gContact:calendarLink calendarUrls
gContact:directoryServer miscKeywords (type=OUTLOOK_DIRECTORY_SERVER)
gContact:event events
gContact:extendedProperty clientData
gContact:externalId externalIds
gContact:fileAs fileAses
gContact:gender genders
gContact:groupMembershipInfo memberships.contactGroupMembership
gContact:hobby interests
gContact:initials DEPRECATED nicknames (type=INITIALS)
gContact:jot type='home' miscKeywords (type=HOME)
gContact:jot type='keywords' miscKeywords (type=OUTLOOK_KEYWORD)
gContact:jot type='other' miscKeywords (type=OTHER)
gContact:jot type='user' miscKeywords (type=OUTLOOK_USER)
gContact:jot type='work' miscKeywords (type=WORK)
gContact:language languages
gContact:maidenName DEPRECATED nicknames (type=MAIDEN_NAME)
gContact:mileage miscKeywords (type=OUTLOOK_MILEAGE)
gContact:nickname nicknames (type=DEFAULT)
gContact:occupation occupations
gContact:priority miscKeywords (type=OUTLOOK_PRIORITY)
gContact:relation relations
gContact:sensitivity miscKeywords (type=OUTLOOK_SENSITIVITY)
gContact:shortName DEPRECATED nicknames (type=SHORT_NAME)
gContact:subject miscKeywords (type=OUTLOOK_SUBJECT)
gContact:userDefinedField userDefined
gContact:website urls
gContact:yomiName names.phonetic_full_name
gd:deleted metadata.deleted
gd:email emailAddresses
gd:im imClients
gd:organization organizations
gd:phoneNumber phoneNumbers
gd:postalAddress addresses.formattedValue
gd:where residences
gd:structuredPostalAddress addresses

Personal Contacts Endpoints

Read

Requires https://www.googleapis.com/auth/contacts or https://www.googleapis.com/auth/contacts.readonly scope.

Mutate

Requires https://www.googleapis.com/auth/contacts scope. Mutates all contact fields except photos.

Photo Mutate

Requires https://www.googleapis.com/auth/contacts scope.

Other Contacts Endpoints

Read

Other contacts are read-only and only names, emailAddresses, and phoneNumbers fields are returned.

Requires https://www.googleapis.com/auth/contacts.other.readonly scope.

Copy

Requires https://www.googleapis.com/auth/contacts.other.readonly and https://www.googleapis.com/auth/contacts scopes.

Global Address List Endpoints

Requires https://www.googleapis.com/auth/directory.readonly scope.

Contact Groups

Fields Mapping

Contacts API Contact Group Field People API Contact Group Field
atom:updated metadata.updateTime
atom:title name
atom:content name
gd:deleted metadata.deleted
systemGroup groupType=SYSTEM_CONTACT_GROUP

Endpoints

Read

Requires https://www.googleapis.com/auth/contacts or https://www.googleapis.com/auth/contacts.readonly scope.

Mutate

Requires https://www.googleapis.com/auth/contacts scope.

Authorization scopes

The legacy scope https://www.google.com/m8/feeds is an alias for the https://www.googleapis.com/auth/contacts scope. This means that existing oauth grants with the legacy scope will work for any endpoints in People API that require the https://www.googleapis.com/auth/contacts scope. Reading and writing contacts and contact groups will work with the legacy scope.

People API requires new scopes to access "Other Contacts" or Directory data. See details above for the scopes required.

For more details, see Authorize Requests.

Client libraries