# 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](https://support.google.com/contacts/answer/7345608?p=other_contacts#auto):

- **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`

> [!NOTE]
> **Note:** The [Domain Shared Contacts API](https://developers.google.com/admin-sdk/domain-shared-contacts) is not affected by these changes.

## Contacts

### Fields Mapping

| Contact Field | Person Field |
|---|---|
| atom:content | [biographies](https://developers.google.com/people/api/rest/v1/people#Person.FIELDS.biographies) |
| atom:link rel='http://schemas.google.com/contacts/2008/rel#photo' | [photos](https://developers.google.com/people/api/rest/v1/people#Person.FIELDS.photos) |
| atom:title | [names](https://developers.google.com/people/api/rest/v1/people#Person.FIELDS.names) |
| gContact:billingInformation | [miscKeywords (type=OUTLOOK_BILLING_INFORMATION)](https://developers.google.com/people/api/rest/v1/people#Person.FIELDS.misc_keywords) |
| gContact:birthday | [birthdays](https://developers.google.com/people/api/rest/v1/people#Person.FIELDS.birthdays) |
| gContact:calendarLink | [calendarUrls](https://developers.google.com/people/api/rest/v1/people#Person.FIELDS.calendar_urls) |
| gContact:directoryServer | [miscKeywords (type=OUTLOOK_DIRECTORY_SERVER)](https://developers.google.com/people/api/rest/v1/people#Person.FIELDS.misc_keywords) |
| gContact:event | [events](https://developers.google.com/people/api/rest/v1/people#Person.FIELDS.events) |
| gContact:extendedProperty | [clientData](https://developers.google.com/people/api/rest/v1/people#Person.FIELDS.client_data) |
| gContact:externalId | [externalIds](https://developers.google.com/people/api/rest/v1/people#Person.FIELDS.external_ids) |
| gContact:fileAs | [fileAses](https://developers.google.com/people/api/rest/v1/people#Person.FIELDS.file_ases) |
| gContact:gender | [genders](https://developers.google.com/people/api/rest/v1/people#Person.FIELDS.genders) |
| gContact:groupMembershipInfo | [memberships.contactGroupMembership](https://developers.google.com/people/api/rest/v1/people#Person.FIELDS.memberships) |
| gContact:hobby | [interests](https://developers.google.com/people/api/rest/v1/people#Person.FIELDS.interests) |
| gContact:initials | **DEPRECATED** [nicknames (type=INITIALS)](https://developers.google.com/people/api/rest/v1/people#Person.FIELDS.nicknames) |
| gContact:jot type='home' | [miscKeywords (type=HOME)](https://developers.google.com/people/api/rest/v1/people#Person.FIELDS.misc_keywords) |
| gContact:jot type='keywords' | [miscKeywords (type=OUTLOOK_KEYWORD)](https://developers.google.com/people/api/rest/v1/people#Person.FIELDS.misc_keywords) |
| gContact:jot type='other' | [miscKeywords (type=OTHER)](https://developers.google.com/people/api/rest/v1/people#Person.FIELDS.misc_keywords) |
| gContact:jot type='user' | [miscKeywords (type=OUTLOOK_USER)](https://developers.google.com/people/api/rest/v1/people#Person.FIELDS.misc_keywords) |
| gContact:jot type='work' | [miscKeywords (type=WORK)](https://developers.google.com/people/api/rest/v1/people#Person.FIELDS.misc_keywords) |
| gContact:language | [languages](https://developers.google.com/people/api/rest/v1/people#Person.FIELDS.languages) |
| gContact:maidenName | **DEPRECATED** [nicknames (type=MAIDEN_NAME)](https://developers.google.com/people/api/rest/v1/people#Person.FIELDS.nicknames) |
| gContact:mileage | [miscKeywords (type=OUTLOOK_MILEAGE)](https://developers.google.com/people/api/rest/v1/people#Person.FIELDS.misc_keywords) |
| gContact:nickname | [nicknames (type=DEFAULT)](https://developers.google.com/people/api/rest/v1/people#Person.FIELDS.nicknames) |
| gContact:occupation | [occupations](https://developers.google.com/people/api/rest/v1/people#Person.FIELDS.occupations) |
| gContact:priority | [miscKeywords (type=OUTLOOK_PRIORITY)](https://developers.google.com/people/api/rest/v1/people#Person.FIELDS.misc_keywords) |
| gContact:relation | [relations](https://developers.google.com/people/api/rest/v1/people#Person.FIELDS.relations) |
| gContact:sensitivity | [miscKeywords (type=OUTLOOK_SENSITIVITY)](https://developers.google.com/people/api/rest/v1/people#Person.FIELDS.misc_keywords) |
| gContact:shortName | **DEPRECATED** [nicknames (type=SHORT_NAME)](https://developers.google.com/people/api/rest/v1/people#Person.FIELDS.nicknames) |
| gContact:subject | [miscKeywords (type=OUTLOOK_SUBJECT)](https://developers.google.com/people/api/rest/v1/people#Person.FIELDS.misc_keywords) |
| gContact:userDefinedField | [userDefined](https://developers.google.com/people/api/rest/v1/people#Person.FIELDS.user_defined) |
| gContact:website | [urls](https://developers.google.com/people/api/rest/v1/people#Person.FIELDS.urls) |
| gContact:yomiName | [names.phonetic_full_name](https://developers.google.com/people/api/rest/v1/people#Person.Name.FIELDS.phonetic_full_name) |
| gd:deleted | [metadata.deleted](https://developers.google.com/people/api/rest/v1/people#Person.PersonMetadata.FIELDS.deleted) |
| gd:email | [emailAddresses](https://developers.google.com/people/api/rest/v1/people#Person.FIELDS.email_addresses) |
| gd:im | [imClients](https://developers.google.com/people/api/rest/v1/people#Person.FIELDS.im_clients) |
| gd:organization | [organizations](https://developers.google.com/people/api/rest/v1/people#Person.FIELDS.organizations) |
| gd:phoneNumber | [phoneNumbers](https://developers.google.com/people/api/rest/v1/people#Person.FIELDS.phone_numbers) |
| gd:postalAddress | [addresses.formattedValue](https://developers.google.com/people/api/rest/v1/people#Person.Address.FIELDS.formatted_value) |
| gd:where | [residences](https://developers.google.com/people/api/rest/v1/people#Person.FIELDS.residences) |
| gd:structuredPostalAddress | [addresses](https://developers.google.com/people/api/rest/v1/people#Person.FIELDS.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`](https://developers.google.com/people/api/rest/v1/people/get)
- Read several specific contacts [`people.getBatchGet`](https://developers.google.com/people/api/rest/v1/people/getBatchGet)
- Read contacts using [`people.connections.list`](https://developers.google.com/people/api/rest/v1/people.connections/list)

#### Mutate

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

- Create a contact using [`people.createContact`](https://developers.google.com/people/api/rest/v1/people/createContact)
- Update an existing contact using [`people.updateContact`](https://developers.google.com/people/api/rest/v1/people/updateContact)
- Delete a contact using [`people.deleteContact`](https://developers.google.com/people/api/rest/v1/people/deleteContact).

#### Photo Mutate

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

- Update a contact photo using [`people.updateContactPhoto`](https://developers.google.com/people/api/rest/v1/people/updateContactPhoto).
- Delete a contact photo using [`people.deleteContactPhoto`](https://developers.google.com/people/api/rest/v1/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`](https://developers.google.com/people/api/rest/v1/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`](https://developers.google.com/people/api/rest/v1/otherContacts/copyOtherContactToMyContactsGroup).

### Global Address List Endpoints

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

- List all directory contacts and profiles [`people.listDirectoryPeople`](https://developers.google.com/people/api/rest/v1/people/listDirectoryPeople).
- Search directory contacts and profiles [`people.searchDirectoryPeople`](https://developers.google.com/people/api/rest/v1/people/searchDirectoryPeople).

## Contact Groups

### Fields Mapping

| Contacts API Contact Group Field | People API Contact Group Field |
|---|---|
| atom:updated | [metadata.updateTime](https://developers.google.com/people/api/rest/v1/contactGroups#ContactGroupMetadata.FIELDS.update_time) |
| atom:title | [name](https://developers.google.com/people/api/rest/v1/contactGroups#ContactGroup.FIELDS.name) |
| atom:content | [name](https://developers.google.com/people/api/rest/v1/contactGroups#ContactGroup.FIELDS.name) |
| gd:deleted | [metadata.deleted](https://developers.google.com/people/api/rest/v1/contactGroups#ContactGroupMetadata.FIELDS.deleted) |
| systemGroup | [groupType=SYSTEM_CONTACT_GROUP](https://developers.google.com/people/api/rest/v1/contactGroups#ContactGroup.FIELDS.group_type) |

### 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`](https://developers.google.com/people/api/rest/v1/contactGroups/get)
- List contact groups using [`people.contactGroups.list`](https://developers.google.com/people/api/rest/v1/contactGroups/list)

#### Mutate

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

- Create a contact group using [`people.contactGroups.create`](https://developers.google.com/people/api/rest/v1/contactGroups/create)
- Update a contact group using [`people.contactGroups.update`](https://developers.google.com/people/api/rest/v1/contactGroups/update)
- Delete a contact group using [`people.contactGroups.delete`](https://developers.google.com/people/api/rest/v1/contactGroups/delete)
- Add or remove contacts from the contact group using [`people.contactGroups.members.modify`](https://developers.google.com/people/api/rest/v1/contactGroups.members/modify)

  > [!NOTE]
  > **Note:** You can also modify contact group memberships by updating a contact's `memberships` field using [`people.updateContact`](https://developers.google.com/people/api/rest/v1/people/updateContact).

## 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](https://developers.google.com/people/v1/how-tos/authorizing).

## Client libraries

- For Apps Script, see [Advanced People Service](https://developers.google.com/apps-script/advanced/people).
- For other supported languages, see [Install Client Libraries](https://developers.google.com/people/v1/libraries).