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