# Google Contacts

Create, find, update and delete contacts in Google Contacts, and sort them into labels.

## Connect Google Contacts

1. In the sidebar, open **Connections** and press **Add connection**.
2. Type `google contacts` and choose **Google Contacts**.
3. Press **Sign in with Google**.
4. Choose your account in Google’s window and allow access.

You should see **Signed in as** and the account’s address.

You can also connect from a step: under **Connection**, press **New**.

**What if it says “Google sign-in isn’t set up here”?**

This installation has no Google app yet. An admin of the installation sees **Set up Google sign-in** instead, and sets it up once for everyone:

1. In Google Cloud, create an OAuth client of type **Web application**, and turn on the API for Google Contacts.
2. In GoRunner, copy the **Redirect address to add in Google Cloud**, and add it to the client.
3. Paste the **Client ID** and **Client secret**, then press **Save and sign in**.

Publish the app in Google Cloud. An app left in Testing signs everyone out after 7 days.

Everyone else sees who to ask.

[Set up Google sign-in for connections](https://docs.gorunner.io/self-host/oauth-apps)

**Can I use my own Google app?**

Yes. In the sheet, open **Use your own Google app** and paste its **Client ID** and **Client secret**. Add the **Redirect address to add in Google Cloud** to your app first. The connection then signs in through your app instead of the installation’s.

[Connections](https://docs.gorunner.io/build/connections) says how to sign in again, rename or delete it. In a product that embeds GoRunner, **Add connection** can be missing: then [your provider makes connections](https://docs.gorunner.io/embed/customer-connections) for you.

## Do things in Google Contacts

Add a **Google Contacts** step, choose a **Resource**, then an **Operation**. Choose a row to see its fields.

- [Contact](https://docs.gorunner.io/apps/google-contacts#fields-f-contact): Create · Get · Get Many · Update · Delete
- [Contact Group (label)](https://docs.gorunner.io/apps/google-contacts#fields-f-contactgroup): Create · Get · Get Many · Rename · Delete · Add Contacts · Remove Contacts

To start a workflow from Google Contacts, use a [Schedule](https://docs.gorunner.io/apps/schedule), [Webhook](https://docs.gorunner.io/apps/webhook) or [Form](https://docs.gorunner.io/apps/form) trigger.

Later steps read a step’s output by its name: see [Use data from earlier steps](https://docs.gorunner.io/build/use-data-from-earlier-steps).

## Limits

- A reply from Google Contacts can be up to 16 MB (a file download can have its own limit). A larger one fails the step; it is never cut short.
- When Google Contacts says to slow down (429), the step waits as long as it asks, if the step’s time allows. Otherwise it fails and says when to try again.

Not in your list? See [When an app isn’t here](https://docs.gorunner.io/apps/when-an-app-isnt-here#q-not-in-list).

## For developers

In the API, which calls apps pieces, Google Contacts is `pieceId: "googlecontacts"` with `actionId: "googlecontacts"`, set by `resource` and an `operation_…` field, such as `operation_contact`. [Get an app](https://docs.gorunner.io/api/apps/get-app) returns every field.

It can change something outside the run (`writes_external`). See [How versions and side effects work](https://docs.gorunner.io/apps#q-versions).

### Google Contacts › Contact

### Create

- **First Name · Optional**
- **Last Name · Optional**
- **Middle Name · Optional**
- **Title · Optional**: Before the name, such as Dr.
- **Suffix · Optional**: After the name, such as Jr.
- **Emails · Optional**: Email addresses, one per line or as a list: ["ada@example.com"] or [{"value": "ada@example.com", "type": "work"}]. On update they replace the contact's emails.
- **Phone Numbers · Optional**: Phone numbers, one per line or as a list: ["+49 30 1234567"] or [{"value": "+49 30 1234567", "type": "mobile"}]. On update they replace the contact's numbers.
- **Company · Optional**
- **Job Title · Optional**
- **Department · Optional**
- **Birthday · Optional**: YYYY-MM-DD, or --MM-DD without a year.
- **Notes · Optional**: Free text about the contact.
- **Addresses · Optional**: A list of addresses, such as [{"streetAddress": "1 Main St", "city": "Berlin", "postalCode": "10115", "country": "Germany", "type": "work"}]. On update they replace the contact's addresses.
- **Websites · Optional**: Web addresses, one per line or as a list. On update they replace the contact's websites.
- **Custom Fields · Optional**: Custom label/value pairs, such as {"Customer ID": "A-1042"}. On update they replace the contact's custom fields.
- **Labels · Optional**: Contact groups (labels) to put the new contact in, besides My Contacts. To change a contact's labels later, use Contact Group › Add Contacts or Remove Contacts.
- **More Person Fields · Optional**: Other People API Person fields as JSON, such as {"nicknames": [{"value": "Addie"}], "relations": [{"person": "Byron", "type": "father"}]}. Each one replaces that field.
- **Fields · Optional**: The contact fields to return. Empty returns names, emails, phone numbers, organizations, addresses, birthdays, notes, websites, custom fields, labels, photos and metadata. Options: addresses to userDefined (29 options).

### Get

- **Contact · Required**: The contact to read, change or delete.
- **Fields · Optional**: The contact fields to return. Empty returns names, emails, phone numbers, organizations, addresses, birthdays, notes, websites, custom fields, labels, photos and metadata. Options: addresses to userDefined (29 options).

### Get Many

- **Search · Optional**: Find contacts whose name, nickname, email, phone or company starts with this text (at most 30). Empty lists every contact.
- **Order · Optional**: The order of a list without Search. Options: Last changed, newest first, Last changed, oldest first, First name, Last name. Default: Last changed, newest first.
- **Return All · Optional**: Read every contact, page by page (at most 5000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many contacts to return (1–5000). Default: 50. Shows when **Return All** is off.
- **Fields · Optional**: The contact fields to return. Empty returns names, emails, phone numbers, organizations, addresses, birthdays, notes, websites, custom fields, labels, photos and metadata. Options: addresses to userDefined (29 options).

### Update

- **Contact · Required**: The contact to read, change or delete.
- **First Name · Optional**
- **Last Name · Optional**
- **Middle Name · Optional**
- **Title · Optional**: Before the name, such as Dr.
- **Suffix · Optional**: After the name, such as Jr.
- **Emails · Optional**: Email addresses, one per line or as a list: ["ada@example.com"] or [{"value": "ada@example.com", "type": "work"}]. On update they replace the contact's emails.
- **Phone Numbers · Optional**: Phone numbers, one per line or as a list: ["+49 30 1234567"] or [{"value": "+49 30 1234567", "type": "mobile"}]. On update they replace the contact's numbers.
- **Company · Optional**
- **Job Title · Optional**
- **Department · Optional**
- **Birthday · Optional**: YYYY-MM-DD, or --MM-DD without a year.
- **Notes · Optional**: Free text about the contact.
- **Addresses · Optional**: A list of addresses, such as [{"streetAddress": "1 Main St", "city": "Berlin", "postalCode": "10115", "country": "Germany", "type": "work"}]. On update they replace the contact's addresses.
- **Websites · Optional**: Web addresses, one per line or as a list. On update they replace the contact's websites.
- **Custom Fields · Optional**: Custom label/value pairs, such as {"Customer ID": "A-1042"}. On update they replace the contact's custom fields.
- **More Person Fields · Optional**: Other People API Person fields as JSON, such as {"nicknames": [{"value": "Addie"}], "relations": [{"person": "Byron", "type": "father"}]}. Each one replaces that field.
- **Fields · Optional**: The contact fields to return. Empty returns names, emails, phone numbers, organizations, addresses, birthdays, notes, websites, custom fields, labels, photos and metadata. Options: addresses to userDefined (29 options).

### Delete

- **Contact · Required**: The contact to read, change or delete.

### Google Contacts › Contact Group (label)

### Create

- **Name · Required**: The label's name.

### Get

- **Label · Required**: The contact group (label).
- **Members to List · Optional**: How many member contact ids to return with the label (0 returns none). Default: 0.

### Get Many

- **Return All · Optional**: Read every label, page by page (at most 1000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many labels to return (1–1000). Default: 100. Shows when **Return All** is off.

### Rename

- **Label · Required**: The contact group (label).
- **Name · Required**: The label's name.

### Delete

- **Label · Required**: The contact group (label).
- **Also Delete Its Contacts · Optional**: Delete the contacts in the label too. Off, only the label goes and its contacts stay. Off by default.

### Add Contacts and Remove Contacts

- **Label · Required**: The contact group (label).
- **Contacts · Required**: The contacts to add or remove: a list of ids, such as ["c4729318826510376123"], or ids one per line.

Source: https://docs.gorunner.io/apps/google-contacts