Contacts API Migration Guide

    • The Contacts API was turned down on January 19, 2022 and developers should migrate to the People API for similar functionality with some changes to fields, endpoints, and authorization scopes.

    • The People API has largely the same contact management capabilities as the Contacts API, but "Other Contacts" are now read-only with limited data access for administrators.

    • The previous https://www.google.com/m8/feeds scope is replaced with separate scopes for personal contacts ( https://www.googleapis.com/auth/contacts ) and directory information ( https://www.googleapis.com/auth/directory.readonly ).

    • This guide provides field mapping between Contacts and People API, endpoint details for various actions (reading, mutating, copying), and information on authorization scopes and client libraries.

    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.

    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

    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.

    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
    Design a Mobile Site
    View Site in Mobile | Classic
    Share by: