AI-generated Key Takeaways
-
The People API allows reading and managing the authenticated user's contacts, including private contacts and "Other contacts".
-
Users can access profile information for authenticated users and their contacts, including public Google profile data and, when permitted, Google Workspace domain profile data.
-
The API facilitates managing contacts by creating, updating, and deleting contacts through specific endpoints.
-
Google Workspace users can utilize the API to list and search domain profiles and domain contacts.
-
The People API merges data from various sources like public profiles, private profiles, contacts, and domain information based on verified email addresses, phone numbers, or profile URLs.
The People API lets you:
- Read and manage the authenticated user's Contacts
- Read and copy the authenticated user's "Other contacts"
- 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
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
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 read from people.connections.list
using people.updateContact
, and delete contacts
using people.deleteContact
.
Google Workspace users can also list their directory domain profiles and domain
contacts using people.listDirectoryPeople
or search
them using 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
of domain-scoped data and the directory.readonly
scope
has been
granted |
| 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 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
when it is used to get the person for the signed-in user
or get a person for another user's Google Account
. |
|
Domain Contact
|
0+ | 0 | 0 | 1 | Returned in people.listDirectoryPeople
or people.searchDirectoryPeople
. |
Only contact based people can be modified by mutation endpoints. Profile and domain contact mutations are not supported.
