Google People API - Contacts

Interact programmatically with a user's Google contacts using the People API. Supports reading, creating, updating, deleting, searching, and batch operations on contacts, with field selection and pagination. OAuth2 is required for all operations.

Version v18 endpoints

Endpoints

GET/people/me/connectionslistContacts

Retrieves a list of contacts for the authenticated user. Specify which details to include via the `personFields` parameter (e.g., names, email addresses, phone numbers). Supports results pagination.

Parameters

Name	In	Required	Description
personFields	query	Yes	Comma-separated list of fields to return, e.g., 'names,emailAddresses'.
pageToken	query	No	Token to retrieve a specific page of results.

Responses

Status	Description
200	A list of contacts with the requested fields.

DELETE/people/{resourceName}:deleteContactdeleteContact

Permanently deletes a contact identified by its resource name from the user's Google Contacts.

Parameters

Name	In	Required	Description
resourceName	path	Yes	Resource name of the contact to delete.

Responses

Status	Description
200	Contact deleted successfully.

PATCH/people/{resourceName}:updateContactupdateContact

Updates a contact by resource name. The latest `etag` value must be provided for concurrency control. Specify fields to update with `updatePersonFields`.

Parameters

Name	In	Required	Description
resourceName	path	Yes	Resource name of the contact (e.g., 'people/c123').
updatePersonFields	query	Yes	Comma-separated fields to update (e.g., 'emailAddresses').

Request body

application/json

Responses

Status	Description
200	Updated contact details.

POST/people:batchCreateContactsbatchCreateContacts

Create multiple contacts in a single request by providing an array of contact objects.

Request body

application/json

Responses

Status	Description
200	Details of batch created contacts.

POST/people:batchDeleteContactsbatchDeleteContacts

Delete multiple contacts by specifying an array of resource names.

Request body

application/json

Responses

Status	Description
200	Contacts deleted successfully.

POST/people:batchUpdateContactsbatchUpdateContacts

Update multiple existing contacts at once. Each contact object must include `etag` and the fields to update, as well as `resourceName`.

Parameters

Name	In	Required	Description
updateMask	query	Yes	Comma-separated fields to update (e.g., 'names,emailAddresses').
readMask	query	Yes	Comma-separated fields to return in response (e.g., 'names,emailAddresses').

Request body

application/json

Responses

Status	Description
200	Batch updated contact details.

POST/people:createContactcreateContact

Creates a new contact. Supply details such as names and email addresses in the request body. The new contact is added to the user's Google Contacts.

Request body

application/json

Responses

Status	Description
200	Newly created contact details.

GET/people:searchContactssearchContacts

Searches contacts for the authenticated user matching a query string (e.g., name or email). The returned fields are specified by the `readMask` query parameter.

Parameters

Name	In	Required	Description
query	query	Yes	Text query for searching contacts (e.g., part of a name or email address).
readMask	query	Yes	Comma-separated fields to return, e.g., 'names,emailAddresses'.

Responses

Status	Description
200	Matching contacts for the search query.

See Deploy in action in under five minutes

Get Started