This guide lists the People API fields and endpoints to use in place of the fields and endpoints in the deprecated Contacts API. Also read up on the People API data model to understand how the People API merges contact and profile data.
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
Contact Group 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
Scope Migration
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.
Client Libraries
Apps Script
Everything Else
Find the supported languages in the Install Client Libraries.