Read and Manage Contacts

After you've completed the steps in Get Ready to Use the People API you are ready to read and manage contacts.

The following code samples demonstrate how to send a few simple requests:

  • List the user's contacts.
  • Search the user's contacts.
  • Create a new contact.
  • Update an existing contact.
  • Delete an existing contact.
  • Batch create new contacts.
  • Batch update existing contacts.
  • Batch delete existing contacts.

For a full list of methods, see the reference documentation.

Only contact based people can be modified. Profile based people read using resource name "people/me" or by an account ID can not be modified.

List the user's contacts

To get a list of people in the user's contacts, use the following code:

Protocol

GET /v1/people/me/connections?personFields=names,emailAddresses HTTP/1.1
Host: people.googleapis.com

Java

ListConnectionsResponse response = peopleService.people().connections().list("people/me")
    .setPersonFields("names,emailAddresses")
    .execute();
List<Person> connections = response.getConnections();

Python

connections = people_service.people().connections()
    .list('people/me', personFields='names,emailAddresses')

PHP

$connections = $people_service->people_connections->listPeopleConnections(
    'people/me', array('personFields' => 'names,emailAddresses'));

.NET

PeopleResource.ConnectionsResource.ListRequest peopleRequest =
    peopleService.People.Connections.List("people/me");
peopleRequest.PersonFields = "names,emailAddresses";
ListConnectionsResponse connectionsResponse = peopleRequest.Execute();
IList<Person> connections = connectionsResponse.Connections;
You can get a list of only changed contacts by setting requestSyncToken to true in the request, and then using the syncToken returned in the response in the syncToken param for the next request. Sync tokens expire after 7 days, and will result in a 410 error. To handle that error, clients should send a request without the syncToken to get the full list of contacts.

Search the user's contacts

To search all of the user's contacts, use the following code:

Protocol

GET /v1/people:searchContacts?query=query&readMask=names,emailAddresses HTTP/1.1
Host: people.googleapis.com

Java

SearchResponse response = peopleService.people().searchContacts()
    .setQuery("query")
    .setReadMask("names,emailAddresses")
    .execute();
Search does a prefix match of the query with the fields on a person. For example, a person with name "foo name" matches queries such as "f", "fo", "foo", "foo n", "nam", etc., but not "oo n".

Create a new contact

To create a new contact, use the following code:

Protocol

POST /v1/people:createContact HTTP/1.1
Body: { "names": [{ "givenName": "John", "familyName": "Doe" }] }
Host: people.googleapis.com

Java

Person contactToCreate = new Person();
List names = new ArrayList<>();
names.add(new Name().setGivenName("John").setFamilyName("Doe"));
contactToCreate.setNames(names);

Person createdContact = peopleService.people().createContact(contactToCreate).execute();

Update an existing contact

To update an existing contact, you must include the person.metadata.sources.etag field in the person for the contact to be updated to make sure the contact has not changed since your last read. Use the following code:

Protocol

PATCH /v1/resource_name:updateContact?updatePersonFields=emailAddresses HTTP/1.1
Body: {
    "resourceName": "resource_name",
    "etag": "etag",
    "emailAddresses": [{ "value": "john.doe@gmail.com" }],
}
Host: people.googleapis.com

Java

Person contactToUpdate = peopleService.people().get("resource_name").execute();

List emailAddresses = new ArrayList<>();
emailAddresses.add(new EmailAddress().setValue("john.doe@gmail.com"));
contactToUpdate.setEmailAddresses(emailAddresses);

Person updatedContact = peopleService.people()
    .updateContact(contactToUpdate.getResourceName(), contactToUpdate)
    .setUpdatePersonFields("emailAddresses")
    .execute();

Delete an existing contact

To delete an existing contact, use the following code:

Protocol

DELETE /v1/resource_name:deleteContact HTTP/1.1
Host: people.googleapis.com

Java

peopleService.people().deleteContact("resource_name").execute();

Batch create new contacts

To batch create new contacts, use the following code:

Protocol

POST /v1/people:batchCreateContacts?readMask=names HTTP/1.1
Body: {
  "contacts": [
    {
      "contactPerson": {
        "names": [
          {
            "givenName": "John",
            "familyName": "Doe"
          }
        ]
      }
    }
  ]
}
Host: people.googleapis.com

Java

Person person1 = new Person();
person1.setNames(ImmutableList.of(new Name().setGivenName("John").setFamilyName("Doe")));
ContactToCreate contactToCreate1 = new ContactToCreate();
contactToCreate1.setContactPerson(person1);

Person person2 = new Person();
person2.setNames(ImmutableList.of(new Name().setGivenName("Bob").setFamilyName("Dylan")));
ContactToCreate contactToCreate2 = new ContactToCreate();
contactToCreate2.setContactPerson(person2);

BatchCreateContactsRequest request = new BatchCreateContactsRequest();
request.setContacts(ImmutableList.of(contactToCreate1, contactToCreate2)).setReadMask("names");

BatchCreateContactsResponse response =
    peopleService.people().batchCreateContacts(request).execute();
Batch mutate requests are limited to 10 parallel requests per user.

Batch update existing contacts

To update an existing contact, you must include the person.metadata.sources.etag field in each person for the contact to be updated to make sure the contact has not changed since your last read. Use the following code:

Protocol

POST /v1/people:batchUpdateContacts?updateMask=names&readMask=names,emailAddresses HTTP/1.1
Body: {
  "contacts": {
    "resource_name": {
      "emailAddresses": [
        {
          "value": "john.doe@gmail.com"
        }
      ]
      "etag": "etag"
    }
  }
}
Host: people.googleapis.com

Java

Person contactToUpdate = peopleService.people().get("resource_name").execute();

contactToUpdate.setNames(
    ImmutableList.of(new Name().setGivenName("John").setFamilyName("Doe")));

BatchUpdateContactsRequest request = new BatchUpdateContactsRequest();
ImmutableMap map =
    ImmutableMap.of(contactToUpdate.getResourceName(), contactToUpdate);
request.setContacts(map).setUpdateMask("names").setReadMask("names,emailAddresses");

BatchUpdateContactsResponse response =
    peopleService.people().batchUpdateContacts(request).execute();
Batch mutate requests are limited to 10 parallel requests per user.

Batch delete existing contacts

To batch delete existing contacts, use the following code:

Protocol

POST /v1/people:batchDeleteContacts HTTP/1.1
Body: {"resource_names": ["resource_name"]}
Host: people.googleapis.com

Java

BatchDeleteContactsRequest request = new BatchDeleteContactsRequest();

request.setResourceNames(ImmutableList.of(resource_name));

peopleService.people().batchDeleteContacts(request).execute();
Batch mutate requests are limited to 10 parallel requests per user.