# Introduction

The People API lets you:

- Read and manage the authenticated user's [Contacts](https://contacts.google.com)
- Read and copy the authenticated user's ["Other contacts"](https://contacts.google.com/other)
- Read profile information for authenticated users and their contacts
- Read domain profiles and contacts

For example, suppose that the authenticated user, Jen, has Fabian and Ranjith in
her private contacts. When your app calls
[`people.connections.list`](https://developers.google.com/people/api/rest/v1/people.connections/list) to read 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 reads a list containing
[`person resources`](https://developers.google.com/people/api/rest/v1/people) for Fabian and Ranjith.

If the app needs information for a specific person, it can then call
[`people.get`](https://developers.google.com/people/api/rest/v1/people/get), passing in a resource name, to get
the [`person resource`](https://developers.google.com/people/api/rest/v1/people) for that person.

The app can also manage contacts by creating new contacts using
[`people.createContact`](https://developers.google.com/people/api/rest/v1/people/createContact), update existing
contacts it has read from
[`people.connections.list`](https://developers.google.com/people/api/rest/v1/people.connections/list) using
[`people.updateContact`](https://developers.google.com/people/api/rest/v1/people/updateContact), and delete contacts
using [`people.deleteContact`](https://developers.google.com/people/api/rest/v1/people/deleteContact).

Google Workspace users can also list their directory domain profiles and domain
contacts using
[`people.listDirectoryPeople`](https://developers.google.com/people/api/rest/v1/people/listDirectoryPeople) or search
them using
[`people.searchDirectoryPeople`](https://developers.google.com/people/api/rest/v1/people/searchDirectoryPeople).

## A merged view of people information

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

| Source | Condition |
|---|---|
| Public Google profile data | Always. |
| Google Workspace domain profile data | The domain admin has [enabled external contact and profile sharing](https://support.google.com/a/answer/6343701) of domain-scoped data and the [`directory.readonly` scope](https://developers.google.com/people/v1/how-tos/authorizing#directory) has been granted |
| The authenticated user's private profile information | One of the [`profile` scopes](https://developers.google.com/people/v1/how-tos/authorizing#OAuth2Authorizing) has been granted. |
| The authenticated user's contacts | The [`contacts` scope](https://developers.google.com/people/v1/how-tos/authorizing#contacts) 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 Workspace Domain Profiles | Google Workspace Domain Contacts | Usage |
|---|---|---|---|---|---|
| Contact | 1 | 0+ | 0+ | 0+ | Returned for most endpoints |
| Profile | 0+ | 1 | 0 or 1 | 0 | Returned in [`people.get`](https://developers.google.com/people/api/rest/v1/people/get) when it is used to get the person [for the signed-in user](https://developers.google.com/people/v1/profiles#get_the_person_for_the_authenticated_user) or get a person for [another user's Google Account](https://developers.google.com/people/v1/read-people#get_the_person_for_a_google_account_id). |
| Domain Contact | 0+ | 0 | 0 | 1 | Returned in [`people.listDirectoryPeople`](https://developers.google.com/people/api/rest/v1/people/listDirectoryPeople) or [`people.searchDirectoryPeople`](https://developers.google.com/people/api/rest/v1/people/searchDirectoryPeople). |

Only contact based people can be modified by mutation endpoints. Profile and
domain contact mutations are not supported.