Google People API v1
The Google People API provides programmatic access to contacts and profile information. Manage contacts, contact groups, and access directory data for Google Workspace users.
OpenAPI Specification
openapi: 3.1.0
info:
title: Google People API (Contacts)
description: >-
The Google People API provides access to information about profiles and
contacts. It allows you to list, create, update, delete, and search
contacts, as well as manage contact groups. It replaces the legacy Google
Contacts API.
version: v1
contact:
name: Google
url: https://developers.google.com/people
servers:
- url: https://people.googleapis.com/v1
paths:
/people/{resourceName}:
get:
operationId: getPerson
summary: Get a person
description: >-
Provides information about a person by specifying a resource name.
parameters:
- name: resourceName
in: path
required: true
schema:
type: string
description: The resource name of the person to provide information about.
- name: personFields
in: query
schema:
type: string
description: >-
A field mask to restrict which fields on the person are returned.
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Person'
/people/{resourceName}/connections:
get:
operationId: listConnections
summary: List contacts
description: >-
Provides a list of the authenticated user's contacts.
parameters:
- name: resourceName
in: path
required: true
schema:
type: string
default: people/me
- name: personFields
in: query
schema:
type: string
- name: pageSize
in: query
schema:
type: integer
maximum: 1000
- name: pageToken
in: query
schema:
type: string
- name: sortOrder
in: query
schema:
type: string
enum:
- LAST_MODIFIED_ASCENDING
- LAST_MODIFIED_DESCENDING
- FIRST_NAME_ASCENDING
- LAST_NAME_ASCENDING
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/ListConnectionsResponse'
/people:createContact:
post:
operationId: createContact
summary: Create a contact
description: Create a new contact and return the person resource for that contact.
parameters:
- name: personFields
in: query
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Person'
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Person'
/people/{resourceName}:updateContact:
patch:
operationId: updateContact
summary: Update a contact
description: >-
Update contact data for an existing contact person.
parameters:
- name: resourceName
in: path
required: true
schema:
type: string
- name: updatePersonFields
in: query
schema:
type: string
- name: personFields
in: query
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Person'
responses:
'200':
description: Successful response
/people/{resourceName}:deleteContact:
delete:
operationId: deleteContact
summary: Delete a contact
description: Delete a contact person.
parameters:
- name: resourceName
in: path
required: true
schema:
type: string
responses:
'200':
description: Successful response
/people:searchContacts:
get:
operationId: searchContacts
summary: Search contacts
description: >-
Provides a list of contacts in the authenticated user's grouped contacts
that matches the search query.
parameters:
- name: query
in: query
schema:
type: string
- name: readMask
in: query
schema:
type: string
- name: pageSize
in: query
schema:
type: integer
responses:
'200':
description: Successful response
/contactGroups:
get:
operationId: listContactGroups
summary: List contact groups
description: >-
List all contact groups owned by the authenticated user.
parameters:
- name: pageSize
in: query
schema:
type: integer
- name: pageToken
in: query
schema:
type: string
responses:
'200':
description: Successful response
post:
operationId: createContactGroup
summary: Create a contact group
description: Create a new contact group.
requestBody:
content:
application/json:
schema:
type: object
properties:
contactGroup:
$ref: '#/components/schemas/ContactGroup'
responses:
'200':
description: Successful response
/contactGroups/{resourceName}:
get:
operationId: getContactGroup
summary: Get a contact group
description: Get a specific contact group.
parameters:
- name: resourceName
in: path
required: true
schema:
type: string
- name: maxMembers
in: query
schema:
type: integer
responses:
'200':
description: Successful response
put:
operationId: updateContactGroup
summary: Update a contact group
description: Update the name of an existing contact group.
parameters:
- name: resourceName
in: path
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
contactGroup:
$ref: '#/components/schemas/ContactGroup'
responses:
'200':
description: Successful response
delete:
operationId: deleteContactGroup
summary: Delete a contact group
description: Delete an existing contact group.
parameters:
- name: resourceName
in: path
required: true
schema:
type: string
- name: deleteContacts
in: query
schema:
type: boolean
responses:
'200':
description: Successful response
components:
schemas:
Person:
type: object
properties:
resourceName:
type: string
description: The resource name for the person.
etag:
type: string
metadata:
type: object
properties:
sources:
type: array
items:
type: object
properties:
type:
type: string
id:
type: string
names:
type: array
items:
type: object
properties:
displayName:
type: string
familyName:
type: string
givenName:
type: string
middleName:
type: string
emailAddresses:
type: array
items:
type: object
properties:
value:
type: string
format: email
type:
type: string
phoneNumbers:
type: array
items:
type: object
properties:
value:
type: string
type:
type: string
addresses:
type: array
items:
type: object
properties:
formattedValue:
type: string
type:
type: string
streetAddress:
type: string
city:
type: string
region:
type: string
postalCode:
type: string
country:
type: string
organizations:
type: array
items:
type: object
properties:
name:
type: string
title:
type: string
department:
type: string
birthdays:
type: array
items:
type: object
properties:
date:
type: object
properties:
year:
type: integer
month:
type: integer
day:
type: integer
photos:
type: array
items:
type: object
properties:
url:
type: string
format: uri
default:
type: boolean
biographies:
type: array
items:
type: object
properties:
value:
type: string
contentType:
type: string
urls:
type: array
items:
type: object
properties:
value:
type: string
format: uri
type:
type: string
ContactGroup:
type: object
properties:
resourceName:
type: string
etag:
type: string
name:
type: string
formattedName:
type: string
memberCount:
type: integer
groupType:
type: string
enum:
- GROUP_TYPE_UNSPECIFIED
- USER_CONTACT_GROUP
- SYSTEM_CONTACT_GROUP
ListConnectionsResponse:
type: object
properties:
connections:
type: array
items:
$ref: '#/components/schemas/Person'
nextPageToken:
type: string
totalPeople:
type: integer
totalItems:
type: integer
securitySchemes:
oauth2:
type: oauth2
flows:
authorizationCode:
authorizationUrl: https://accounts.google.com/o/oauth2/auth
tokenUrl: https://oauth2.googleapis.com/token
scopes:
https://www.googleapis.com/auth/contacts: See, edit, download, and permanently delete your contacts
https://www.googleapis.com/auth/contacts.readonly: See and download your contacts
https://www.googleapis.com/auth/contacts.other.readonly: See and download contact info automatically saved in your Other contacts
https://www.googleapis.com/auth/directory.readonly: See and download your organization's GSuite directory
security:
- oauth2: []