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.
- Read a single specific contact
people.get - Read several specific contacts
people.getBatchGet - Read contacts using
people.connections.list
Mutate
Requires https://www.googleapis.com/auth/contacts scope. Mutates all contact
fields except photos.
- Create a contact using
people.createContact - Update an existing
contact using
people.updateContact - Delete a contact
using
people.deleteContact.
Photo Mutate
Requires https://www.googleapis.com/auth/contacts scope.
- Update a contact photo using
people.updateContactPhoto. - Delete a contact photo using
people.deleteContactPhoto.
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.
- Read other contacts using
otherContacts.list.
Copy
Requires https://www.googleapis.com/auth/contacts.other.readonly and https://www.googleapis.com/auth/contacts scopes.
- Copy other contacts using
otherContacts.copyOtherContactToMyContactsGroup.
Global Address List Endpoints
Requires https://www.googleapis.com/auth/directory.readonly scope.
- List all directory contacts and profiles
people.listDirectoryPeople. - Search directory contacts and profiles
people.searchDirectoryPeople.
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.
- Get a specific contact group using
people.contactGroups.get - List contact groups using
people.contactGroups.list
Mutate
Requires https://www.googleapis.com/auth/contacts scope.
- Create a contact group using
people.contactGroups.create - Update a contact group using
people.contactGroups.update - Delete a contact group using
people.contactGroups.delete Add or remove contacts from the contact group using
people.contactGroups.members.modify
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
- For Apps Script, see Advanced People Service.
- For other supported languages, see Install Client Libraries.