<!-- BusyBot node reference — https://busybot.net/tools/google-contacts/ -->

> Node: Google Contacts (`google_contacts`) · Action · v1
> Category: Productivity · Credentials: Google Contacts OAuth2 (`googleContactsOAuth2Api`)
> Updated: 2026-08-16

# Google Contacts

> Manage Google Contacts using the People API — create, read, update, delete contacts and group memberships.

## Overview

Google Contacts tool manages contacts via the Google People API (v1). Contact operations: create a contact with name, emails, phones, addresses, organizations, birthday, events, relations, custom fields and group memberships; delete a contact by resource name; get a contact by resource name with selectable person fields; get all contacts with optional search query, sort order, and pagination; update a contact with selective field patching. All contact operations use the contactId (people/{personId} resource name, or just the ID part). getAll supports both connections list and search query modes. The rawData toggle preserves full API response. The fields parameter controls which person fields are returned.

**Category:** Productivity  
**Tool Name:** `google_contacts`  
**Version:** 1

**Appearance:** Icon: `lucide-Users` | Color: `#4285F4`

## Node Type

**Action** — processes input items and produces output

## Input / Output

| Direction | Port(s) |
|-----------|--------|
| Input | `Input` |
| Output | `Output`, `Error` |

## Credentials

This tool requires **Google Contacts OAuth2** credentials.
See the [Credentials Guide](https://busybot.net/credentials/google-contacts-oauth2-api/) for setup instructions.

### Resources

| Resource | Value |
|----------|-------|
| Contact | `contact` |

### Operations

| Operation | Value | Description |
|-----------|-------|-------------|
| Create | `create` | Create a new contact. |
| Delete | `delete` | Delete a contact. |
| Get | `get` | Get a contact by ID. |
| Get Many | `getAll` | Retrieve many contacts. |
| Update | `update` | Update a contact. |

### Parameters

#### Contact: Create (`create`)

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Family Name | `string` | No | — | The last name (family name) of the contact. Supports expressions like {{ $json.lastName }}. |
| Given Name | `string` | No | — | The first name (given name) of the contact. Supports expressions. |
| Additional Fields | `collection` | No | `{}` | Optional contact details to set on creation. |
| — Addresses | `fixedCollection` | No | `{}` | Postal addresses. Add one entry per address. |
| — — Street Address | `string` | No | — | Street address line. |
| — — City | `string` | No | — | City. |
| — — Region | `string` | No | — | Region, state or province. |
| — — Country Code | `string` | No | — | Country code. |
| — — Postal Code | `string` | No | — | Postal or ZIP code. |
| — — Type | `options` | No | — | The kind of address. |
| | | | | Options: `home`, `work`, `other` |
| — Birthday | `dateTime` | No | — | The birthday of the contact. |
| — Company | `fixedCollection` | No | `{}` | Organizations the contact belongs to. Add one entry per organization. |
| — — Current | `boolean` | No | `false` | Whether this is the contact's current organization. |
| — — Domain | `string` | No | — | The organization's domain. |
| — — Name | `string` | No | — | The organization's name. |
| — — Title | `string` | No | — | The contact's job title at this organization. |
| — Custom Fields | `fixedCollection` | No | `{}` | User-defined key/value pairs. Add one entry per field. |
| — — Key | `string` | No | — | The end user specified key of the user defined data. |
| — — Value | `string` | No | — | The end user specified value of the user defined data. |
| — Emails | `fixedCollection` | No | `{}` | Email addresses. Add one entry per address. |
| — — Type | `options` | No | — | The kind of email address. |
| | | | | Options: `home`, `work`, `other` |
| — — Value | `string` | No | — | The email address. |
| — Events | `fixedCollection` | No | `{}` | Dated events. Add one entry per event. |
| — — Date | `dateTime` | No | — | The date of the event. |
| — — Type | `options` | No | — | The kind of event. |
| | | | | Options: `anniversary`, `other` |
| — File As | `string` | No | — | The name that should be used to sort the person in a list. |
| — Group Names or IDs | `multiOptions` | No | `[]` | Contact groups to add this contact to. Specify contactGroup resource names (e.g. "contactGroups/myContacts"). The list is loaded from your account. |
| — Honorific Prefix | `string` | No | — | Honorific prefix (e.g. "Dr.", "Mr.", "Ms."). |
| — Honorific Suffix | `string` | No | — | Honorific suffix (e.g. "Jr.", "Sr.", "PhD"). |
| — Middle Name | `string` | No | — | The contact's middle name. |
| — Notes | `string` | No | — | Free-form text notes about the contact. |
| — Phone | `fixedCollection` | No | `{}` | Phone numbers. Add one entry per number. |
| — — Type | `options` | No | — | The kind of phone number. |
| | | | | Options: `googleVoice`, `home`, `homeFax`, `main`, `mobile`, `other`, `otherFax`, `pager`, `work`, `workFax`, `workMobile`, `workPager` |
| — — Value | `string` | No | — | The phone number. |
| — Relations | `fixedCollection` | No | `{}` | People related to this contact. Add one entry per relation. |
| — — Person | `string` | No | — | The name of the other person this relation refers to. |
| — — Type | `options` | No | — | How the other person is related to this contact. |
| | | | | Options: `assistant`, `brother`, `child`, `domesticPartner`, `father`, `friend`, `manager`, `mother`, `parent`, `referredBy`, `relative`, `sister`, `spouse` |

#### Contact: Delete (`delete`)

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Contact ID | `string` | Yes | — | The contact resource name or numeric ID (e.g. "people/c123456789" or just "c123456789"). Supports expressions. |

#### Contact: Get (`get`)

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Contact ID | `string` | Yes | — | The contact resource name or numeric ID (e.g. "people/c123456789" or just "c123456789"). Supports expressions. |
| Fields | `multiOptions` | No | `[]` | Person fields to return. Use ["*"] for all fields. |
| | | | | Options: `*`, `addresses`, `biographies`, `birthdays`, `coverPhotos`, `emailAddresses`, `events`, `genders`, `imClients`, `interests`, `locales`, `memberships`, `metadata`, `names`, `nicknames`, `occupations`, `organizations`, `phoneNumbers`, `photos`, `relations`, `residences`, `sipAddresses`, `skills`, `urls`, `userDefined` |
| RAW Data | `boolean` | No | `false` | Return the raw API response without data cleaning. |

#### Contact: Get Many (`getAll`)

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Fields | `multiOptions` | No | `[]` | Person fields to return. Use ["*"] for all fields. |
| | | | | Options: `*`, `addresses`, `biographies`, `birthdays`, `coverPhotos`, `emailAddresses`, `events`, `genders`, `imClients`, `interests`, `locales`, `memberships`, `metadata`, `names`, `nicknames`, `occupations`, `organizations`, `phoneNumbers`, `photos`, `relations`, `residences`, `sipAddresses`, `skills`, `urls`, `userDefined` |
| Return All | `boolean` | No | `false` | Whether to return all results or only up to a given limit. |
| Limit | `number` | No | `100` | Max number of results to return. Between 1 and 500. _(shown when Return All is `false`)_ |
| Use Query | `boolean` | No | `false` | Whether to filter results using a search query (uses searchContacts endpoint) instead of listing all connections. |
| Query | `string` | No | — | Plain-text query to filter contacts. Matches name, email, phone, etc. prefix phrases. _(shown when Use Query is `true`)_ |
| RAW Data | `boolean` | No | `false` | Return raw API response without data cleaning. |
| Options | `collection` | No | `{}` | Extra listing options. _(shown when Use Query is `false`)_ |
| — Sort Order | `options` | No | — | The order in which contacts are returned. |
| | | | | Options: `LAST_MODIFIED_ASCENDING`, `LAST_MODIFIED_DESCENDING`, `FIRST_NAME_ASCENDING`, `LAST_NAME_ASCENDING` |

#### Contact: Update (`update`)

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Contact ID | `string` | Yes | — | The contact resource name or numeric ID (e.g. "people/c123456789" or just "c123456789"). Supports expressions. |
| Fields | `multiOptions` | No | `[]` | Person fields to return. Use ["*"] for all fields. |
| | | | | Options: `*`, `addresses`, `biographies`, `birthdays`, `coverPhotos`, `emailAddresses`, `events`, `genders`, `imClients`, `interests`, `locales`, `memberships`, `metadata`, `names`, `nicknames`, `occupations`, `organizations`, `phoneNumbers`, `photos`, `relations`, `residences`, `sipAddresses`, `skills`, `urls`, `userDefined` |
| Update Fields | `collection` | No | `{}` | The fields to patch. Only the fields you add are sent, and only those are overwritten. |
| — Etag | `string` | No | — | The etag of the contact to prevent conflicts. If omitted, it is fetched automatically. |
| — Family Name | `string` | No | — | The last name (family name) of the contact. |
| — Given Name | `string` | No | — | The first name (given name) of the contact. |
| — Middle Name | `string` | No | — | The contact's middle name. |
| — Honorific Prefix | `string` | No | — | Honorific prefix. |
| — Honorific Suffix | `string` | No | — | Honorific suffix. |
| — Addresses | `fixedCollection` | No | `{}` | Postal addresses. Add one entry per address. |
| — — Street Address | `string` | No | — | Street address line. |
| — — City | `string` | No | — | City. |
| — — Region | `string` | No | — | Region, state or province. |
| — — Country Code | `string` | No | — | Country code. |
| — — Postal Code | `string` | No | — | Postal or ZIP code. |
| — — Type | `options` | No | — | The kind of address. |
| | | | | Options: `home`, `work`, `other` |
| — Birthday | `dateTime` | No | — | The birthday of the contact. |
| — Company | `fixedCollection` | No | `{}` | Organizations the contact belongs to. Add one entry per organization. |
| — — Current | `boolean` | No | `false` | Whether this is the contact's current organization. |
| — — Domain | `string` | No | — | The organization's domain. |
| — — Name | `string` | No | — | The organization's name. |
| — — Title | `string` | No | — | The contact's job title at this organization. |
| — Custom Fields | `fixedCollection` | No | `{}` | User-defined key/value pairs. Add one entry per field. |
| — — Key | `string` | No | — | The key of the user defined data. |
| — — Value | `string` | No | — | The value of the user defined data. |
| — Emails | `fixedCollection` | No | `{}` | Email addresses. Add one entry per address. |
| — — Type | `options` | No | — | The kind of email address. |
| | | | | Options: `home`, `work`, `other` |
| — — Value | `string` | No | — | The email address. |
| — Events | `fixedCollection` | No | `{}` | Dated events. Add one entry per event. |
| — — Date | `dateTime` | No | — | The date of the event. |
| — — Type | `options` | No | — | The kind of event. |
| | | | | Options: `anniversary`, `other` |
| — File As | `string` | No | — | The name used to sort this person in a list. |
| — Group Names or IDs | `multiOptions` | No | `[]` | Contact groups to set for this contact. The list is loaded from your account. |
| — Notes | `string` | No | — | Free-form text notes about the contact. |
| — Phone | `fixedCollection` | No | `{}` | Phone numbers. Add one entry per number. |
| — — Type | `options` | No | — | The kind of phone number. |
| | | | | Options: `googleVoice`, `home`, `homeFax`, `main`, `mobile`, `other`, `otherFax`, `pager`, `work`, `workFax`, `workMobile`, `workPager` |
| — — Value | `string` | No | — | The phone number. |
| — Relations | `fixedCollection` | No | `{}` | People related to this contact. Add one entry per relation. |
| — — Person | `string` | No | — | The name of the other person this relation refers to. |
| — — Type | `options` | No | — | How the other person is related to this contact. |
| | | | | Options: `assistant`, `brother`, `child`, `domesticPartner`, `father`, `friend`, `manager`, `mother`, `parent`, `referredBy`, `relative`, `sister`, `spouse` |

#### All Operations

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Authentication | `options` | No | `oAuth2` | Authentication method to use. |
| | | | | Options: `oAuth2` (OAuth2, recommended), `serviceAccount` (Service Account) |
| Google Account | `credential` | No | — | Connect or select your Google account. _(shown when Authentication is `oAuth2`)_ |
| Service Account Email | `string` | Yes | — | The email address of the Google service account, for example `my-service-account@project.iam.gserviceaccount.com`. _(shown when Authentication is `serviceAccount`)_ |
| Private Key | `string` | Yes | — | The private key from the service account JSON key file. Paste the full PEM block, including the BEGIN and END lines. _(shown when Authentication is `serviceAccount`)_ |
| Max Concurrency | `number` | No | `5` | Maximum number of items to process concurrently. Between 1 and 20. |

## Output Data

The People API response is merged into the item JSON, so the incoming fields pass through except where a response field uses the same name. Binary data on the input item is not carried to the output.

Wherever the API returns a person record, the node also adds `contactId` — the ID part of the record's `resourceName`, so you can feed it straight back into a later Get, Update or Delete.

| Operation | Output |
|-----------|--------|
| `create` | One item carrying the created person record plus `contactId`. |
| `delete` | One item carrying `success: true`. The API returns no body for a delete. |
| `get` | One item carrying the person record plus `contactId`. |
| `getAll` | **Fans out** — one item per contact, each with `contactId`. A search that matches nothing still emits one item, carrying the input JSON unchanged. |
| `update` | One item carrying the patched person record plus `contactId`. |

With **RAW Data** off (the default) on `get` and `getAll`, the record is flattened for easier downstream use; turn it on to receive the People API response exactly as returned. Because `getAll` already emits one item per contact, you do not need a Split Out node after it.

Reference the result downstream by expression, e.g. `{{ $json.contactId }}`.

## Usage Examples

- Create a new contact with name, email, and phone number
- Delete a contact by its resource ID
- Get a contact by ID and return selected person fields
- List all contacts with sorting and pagination
- Search contacts by name or email
- Update a contact email address or phone number
- Add a contact to a contact group

## Example Configuration

Create a contact with a work email and a mobile number:

```json
{
  "type": "google_contacts",
  "parameters": {
    "authentication": "oAuth2",
    "resource": "contact",
    "operation": "create",
    "givenName": "{{ $json.firstName }}",
    "familyName": "{{ $json.lastName }}",
    "additionalFields": {
      "emailsUi": {
        "emailsValues": [
          { "type": "work", "value": "{{ $json.email }}" }
        ]
      },
      "phoneUi": {
        "phoneValues": [
          { "type": "mobile", "value": "{{ $json.phone }}" }
        ]
      }
    }
  }
}
```

List contacts newest-first, one item per contact:

```json
{
  "type": "google_contacts",
  "parameters": {
    "resource": "contact",
    "operation": "getAll",
    "fields": ["names", "emailAddresses", "phoneNumbers"],
    "returnAll": false,
    "limit": 100,
    "useQuery": false,
    "options": {
      "sortOrder": "LAST_MODIFIED_DESCENDING"
    }
  }
}
```

Search contacts by a plain-text query:

```json
{
  "type": "google_contacts",
  "parameters": {
    "resource": "contact",
    "operation": "getAll",
    "fields": ["names", "emailAddresses"],
    "useQuery": true,
    "query": "{{ $json.searchTerm }}",
    "returnAll": true
  }
}
```

Patch one field on an existing contact:

```json
{
  "type": "google_contacts",
  "parameters": {
    "resource": "contact",
    "operation": "update",
    "contactId": "{{ $json.contactId }}",
    "fields": ["names", "emailAddresses"],
    "updateFields": {
      "emailsUi": {
        "emailsValues": [
          { "type": "work", "value": "{{ $json.newEmail }}" }
        ]
      }
    }
  }
}
```

### Error Handling

| Mode | Behavior |
|------|----------|
| **stop** | Halts workflow on first error |
| **continue** | Skips failed items, passes successful ones through |
| **errorPort** | Routes failed items to Error output port |

## Tips

Create, read, update, and delete Google Contacts using the People API — manage names, emails, phones, addresses, and group memberships.