Introduction

The People API lets you list and manage the authenticated user's Contacts and retrieve profile information for authenticated users and their contacts.

For example, suppose that the authenticated user, Jen, has Fabian and Ranjith in her private contacts. When your app calls people.connections.list to retrieve a list of her connections, Jen is presented with a consent screen asking to give the app access to the list. If Jen consents, the app retrieves a list containing person resources for Fabian and Ranjith.

If the app needs information for a specific person, it can then call people.get, passing in a resource name, to get the person resource for that person.

The app can also manage contacts by creating new contacts using people.createContact, update existing contacts it has retrieved from people.connections.list using people.updateContact, and delete contacts using people.deleteContact.

A merged view of people information

The people information that the People API retrieves is merged from various sources, depending on the following conditions:

Source Condition
Public Google profile data Always.
Google Apps domain profile data The domain admin has enabled external contact and profile sharing of domain-scoped data.
The authenticated user's private profile information One of the profile scopes has been granted.
The authenticated user's contacts The contacts scope has been granted.

Understanding Merged Person Data

The data for a person is derived from one main source type. Data from other sources is merged with this data if the sources are connected through verified email addresses, phone numbers, or profile URLs. These are the ways a person may be composed:

Main Source Contacts Profiles Google Apps Domain Profiles Usage
Contact 1 0+ 0+ Returned for most endpoints
Profile 0+ 1 0 or 1 Returned in people.get when it is used to get the person for the user or get a person for a Google Account.

Get Ready to Use the People API Request Contacts and Profiles