Google Contacts integration

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.

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 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 }}.

Example Configuration

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

{
  "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:

{
  "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:

{
  "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:

{
  "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

This tool manages contacts in Google Contacts, allowing creation, retrieval, updates, and deletion. It is ideal for precise operations on individual contacts or for retrieving multiple contacts based on various criteria. The tool produces contact information, including names, emails, phone numbers, addresses, and group memberships.