> ## Documentation Index
> Fetch the complete documentation index at: https://veryfront.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Contacts

> Search, read, create, and update the authenticated user's Google Contacts via the People API

## At a glance

* **Availability**: Experimental ([how to enable](/cloud/integrations)).
* **Auth**: OAuth 2.0.
* **Connection**: A user authorizes the connection in the provider's consent screen.
* **Scopes**: `https://www.googleapis.com/auth/contacts.readonly`.
* **Optional scopes**: `https://www.googleapis.com/auth/contacts`.
* **Docs**: [https://developers.google.com/people/api/rest](https://developers.google.com/people/api/rest)

## Credentials

Set these per environment. See [Connect an integration](/cloud/integrations).

With a managed OAuth app, Connect works without these variables; set them to use your own OAuth app instead.

| Variable               | Required | Description                                                                           |
| ---------------------- | -------- | ------------------------------------------------------------------------------------- |
| `GOOGLE_CLIENT_ID`     | Yes      | Google OAuth Client ID [Docs](https://console.cloud.google.com/apis/credentials).     |
| `GOOGLE_CLIENT_SECRET` | Yes      | Google OAuth Client Secret [Docs](https://console.cloud.google.com/apis/credentials). |

## Setup

1. **Create or reuse a Google Cloud project**: Go to [https://console.cloud.google.com](https://console.cloud.google.com) and create a project, or reuse the project that already hosts your shared Google OAuth app. Any free Google account works for testing - add a few contacts at [https://contacts.google.com](https://contacts.google.com) to have data to query.
2. **Enable the People API**: Open [https://console.cloud.google.com/apis/library/people.googleapis.com](https://console.cloud.google.com/apis/library/people.googleapis.com), select your project, and click Enable. Google Contacts data is served by the People API.
3. **Configure the OAuth consent screen and client**: Under APIs & Services > Credentials, create (or reuse) an OAuth 2.0 Client ID of type Web application and add your app's redirect URI ending in /api/auth/google-contacts/callback. The same Google OAuth client can be shared across all Google connectors.
4. **Set environment variables**: Set GOOGLE\_CLIENT\_ID and GOOGLE\_CLIENT\_SECRET from the OAuth client you created. These are shared with other Google integrations.

* The default scope is read-only (contacts.readonly); creating or updating contacts requires granting the optional [https://www.googleapis.com/auth/contacts](https://www.googleapis.com/auth/contacts) scope.
* Contact resource names look like 'people/c123'; tools take just the ID portion after 'people/' as the personId parameter.
* Updates are etag-guarded: fetch the contact (including metadata) first and send its etag and metadata.sources back, plus an updatePersonFields mask naming the changed fields.
* Search uses a prefix-match cache; send a warmup search with an empty query before the real query for fresh results.

Provider API reference: [https://developers.google.com/people/api/rest](https://developers.google.com/people/api/rest)

## Tools

| Tool                | Access | Description                                                                                                                                                                                                                                                                                            |
| ------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| List Contacts       | Read   | List the authenticated user's contacts (connections) with the requested person fields                                                                                                                                                                                                                  |
| Search Contacts     | Read   | Search the user's contacts by prefix match on names, nicknames, email addresses, and phone numbers. For best results send a warmup request with an empty query first, then search.                                                                                                                     |
| Get Contact         | Read   | Get a single contact by person ID, including the etag needed for updates                                                                                                                                                                                                                               |
| List Contact Groups | Read   | List the user's contact groups (labels), including system groups and member counts, e.g. to organize or filter contacts                                                                                                                                                                                |
| Create Contact      | Write  | Create a new contact in the user's Google Contacts (requires the full contacts scope)                                                                                                                                                                                                                  |
| Update Contact      | Write  | Update an existing contact (requires the full contacts scope). You must pass updatePersonFields naming the fields you are changing, and the body must include the contact's current etag (fetch it with Get Contact including metadata first); a stale etag fails with a 400 failedPrecondition error. |

## Example prompts

* Search my Google Contacts for a person and show their email address and phone number.
* Create a new contact in my Google Contacts with name, email, and phone number.
* Find a contact and update their email address or phone number in Google Contacts.