Contacts API Migration Guide

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.

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

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.

Mutate

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