Google Contacts

Access the Google People API with managed OAuth authentication. Manage contacts, contact groups, and search your address book.

Reference

List Contacts

GET /google-contacts/v1/people/me/connections?personFields=names,emailAddresses,phoneNumbers&pageSize=100

Query Parameters:

personFields (required): Comma-separated list of fields to return (see Person Fields section)
pageSize: Number of contacts to return (max 1000, default 100)
pageToken: Token for pagination
sortOrder: LAST_MODIFIED_ASCENDING, LAST_MODIFIED_DESCENDING, FIRST_NAME_ASCENDING, or LAST_NAME_ASCENDING

Response:

{
  "connections": [
    {
      "resourceName": "people/c1234567890",
      "names": [{"displayName": "John Doe", "givenName": "John", "familyName": "Doe"}],
      "emailAddresses": [{"value": "john@example.com"}],
      "phoneNumbers": [{"value": "+1-555-0123"}]
    }
  ],
  "totalPeople": 1,
  "totalItems": 1,
  "nextPageToken": "..."
}

Get Contact

GET /google-contacts/v1/people/{resourceName}?personFields=names,emailAddresses,phoneNumbers

Use the resource name from list or create operations (e.g., people/c1234567890).

Create Contact

POST /google-contacts/v1/people:createContact
Content-Type: application/json

{
  "names": [{"givenName": "John", "familyName": "Doe"}],
  "emailAddresses": [{"value": "john@example.com"}],
  "phoneNumbers": [{"value": "+1-555-0123"}],
  "organizations": [{"name": "Acme Corp", "title": "Engineer"}]
}

Update Contact

PATCH /google-contacts/v1/people/{resourceName}:updateContact?updatePersonFields=names,emailAddresses
Content-Type: application/json

{
  "etag": "%EgcBAgkLLjc9...",
  "names": [{"givenName": "John", "familyName": "Smith"}],
  "emailAddresses": [{"value": "john.smith@example.com"}]
}

Note: Include the etag from the get/list response to ensure you're updating the latest version.

Delete Contact

DELETE /google-contacts/v1/people/{resourceName}:deleteContact

Batch Get Contacts

GET /google-contacts/v1/people:batchGet?resourceNames=people/c123&resourceNames=people/c456&personFields=names,emailAddresses

Batch Create Contacts

POST /google-contacts/v1/people:batchCreateContacts
Content-Type: application/json

{
  "contacts": [
    {
      "contactPerson": {
        "names": [{"givenName": "Alice", "familyName": "Smith"}],
        "emailAddresses": [{"value": "alice@example.com"}]
      }
    },
    {
      "contactPerson": {
        "names": [{"givenName": "Bob", "familyName": "Jones"}],
        "emailAddresses": [{"value": "bob@example.com"}]
      }
    }
  ],
  "readMask": "names,emailAddresses"
}

Batch Delete Contacts

POST /google-contacts/v1/people:batchDeleteContacts
Content-Type: application/json

{
  "resourceNames": ["people/c123", "people/c456"]
}

Search Contacts

GET /google-contacts/v1/people:searchContacts?query=John&readMask=names,emailAddresses

Note: Search results may have a slight delay for newly created contacts due to indexing.

List Contact Groups

GET /google-contacts/v1/contactGroups?pageSize=100

Response:

{
  "contactGroups": [
    {
      "resourceName": "contactGroups/starred",
      "groupType": "SYSTEM_CONTACT_GROUP",
      "name": "starred",
      "formattedName": "Starred"
    },
    {
      "resourceName": "contactGroups/abc123",
      "groupType": "USER_CONTACT_GROUP",
      "name": "Work",
      "formattedName": "Work",
      "memberCount": 5
    }
  ],
  "totalItems": 2
}

Get Contact Group

GET /google-contacts/v1/contactGroups/{resourceName}?maxMembers=100

Use contactGroups/starred, contactGroups/family, etc. for system groups, or the resource name for user groups.

Create Contact Group

POST /google-contacts/v1/contactGroups
Content-Type: application/json

{
  "contactGroup": {
    "name": "Work Contacts"
  }
}

Delete Contact Group

DELETE /google-contacts/v1/contactGroups/{resourceName}?deleteContacts=false

Set deleteContacts=true to also delete the contacts in the group.

Batch Get Contact Groups

GET /google-contacts/v1/contactGroups:batchGet?resourceNames=contactGroups/starred&resourceNames=contactGroups/family

Modify Group Members

Add or remove contacts from a group:

POST /google-contacts/v1/contactGroups/{resourceName}/members:modify
Content-Type: application/json

{
  "resourceNamesToAdd": ["people/c123", "people/c456"],
  "resourceNamesToRemove": ["people/c789"]
}

List Other Contacts

GET /google-contacts/v1/otherContacts?readMask=names,emailAddresses&pageSize=100

Copy Other Contact to My Contacts

POST /google-contacts/v1/{resourceName}:copyOtherContactToMyContactsGroup
Content-Type: application/json

{
  "copyMask": "names,emailAddresses,phoneNumbers"
}