Google Contacts Integration

Overview

Add Google Contacts to any ModuleX agent or workflow. Manage Google Contacts (People API v1) — create, list, get, update, and delete the authenticated user’s contacts, plus list Google Workspace directory people. All calls go to https://people.googleapis.com/v1.

Categories: Productivity & Collaboration · CRM · Auth: Google OAuth2 · Actions: 6

Authentication

Google OAuth2

Connect using Google OAuth (recommended) — Contacts + Directory scopes.

Required Credentials

Field	Description	Required	Format
Client ID	Google Cloud OAuth 2.0 Client ID.	Yes	`xxxxxxxxxxxx-xxxxxxxxxxxxxxxx.apps.googleusercontent.com`
Client Secret	Google Cloud OAuth 2.0 Client Secret.	Yes	`GOCSPX-xxxxxxxxxxxxxxxxxxxxxxxx`

OAuth Configuration

Authorization URL: https://accounts.google.com/o/oauth2/v2/auth
Token URL: https://oauth2.googleapis.com/token
Scopes: https://www.googleapis.com/auth/contacts, https://www.googleapis.com/auth/directory.readonly

Available Actions

create_contact — Create a new contact in the authenticated user's Google Contacts.

Parameters

array

required

Contact fields to populate and return — any of: names, emailAddresses, phoneNumbers, addresses, biographies, birthdays, calendarUrls, genders, urls.

string

Contact’s first name (used when person_fields includes ‘names’).

string

Contact’s middle name (used when person_fields includes ‘names’).

string

Contact’s last name (used when person_fields includes ‘names’).

string

Contact’s email address (used when person_fields includes ‘emailAddresses’).

string

Contact’s phone number (used when person_fields includes ‘phoneNumbers’).

string

Street address (used when person_fields includes ‘addresses’).

string

City (used when person_fields includes ‘addresses’).

string

State / region (used when person_fields includes ‘addresses’).

string

Postal / zip code (used when person_fields includes ‘addresses’).

string

Country (used when person_fields includes ‘addresses’).

string

Biography text (used when person_fields includes ‘biographies’).

string

Birthday in YYYY-MM-DD format (used when person_fields includes ‘birthdays’).

string

Calendar URL (used when person_fields includes ‘calendarUrls’).

string

Gender: male, female, or unspecified (used when person_fields includes ‘genders’).

array

List of associated URLs (used when person_fields includes ‘urls’).

object

Optional extra fields merged into the Person request body. See https://developers.google.com/people/api/rest/v1/people for the full schema.

Response

{
  "$defs": {
    "ContactSummary": {
      "additionalProperties": false,
      "description": "A Google People `Person` resource, projected to the fields most tools read.",
      "properties": {
        "resource_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Resource Name"
        },
        "etag": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Etag"
        },
        "display_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Display Name"
        },
        "given_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Given Name"
        },
        "family_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Family Name"
        },
        "middle_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Middle Name"
        },
        "email_addresses": {
          "items": {
            "type": "string"
          },
          "title": "Email Addresses",
          "type": "array"
        },
        "phone_numbers": {
          "items": {
            "type": "string"
          },
          "title": "Phone Numbers",
          "type": "array"
        },
        "organizations": {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "title": "Organizations",
          "type": "array"
        },
        "addresses": {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "title": "Addresses",
          "type": "array"
        },
        "biographies": {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "title": "Biographies",
          "type": "array"
        },
        "urls": {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "title": "Urls",
          "type": "array"
        },
        "birthdays": {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "title": "Birthdays",
          "type": "array"
        },
        "genders": {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "title": "Genders",
          "type": "array"
        },
        "raw": {
          "additionalProperties": true,
          "description": "Untouched upstream Person object — all fields requested via personFields.",
          "title": "Raw",
          "type": "object"
        }
      },
      "title": "ContactSummary",
      "type": "object"
    }
  },
  "additionalProperties": false,
  "properties": {
    "success": {
      "title": "Success",
      "type": "boolean"
    },
    "contact": {
      "anyOf": [
        {
          "$ref": "#/$defs/ContactSummary"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    }
  },
  "required": [
    "success"
  ],
  "title": "CreateContactOutput",
  "type": "object"
}

delete_contact — Delete a contact by its People API resource name (e.g. 'people/c123456').

Parameters

string

required

The People API resource name identifying the contact, e.g. ‘people/c123456789’.

Response

{
  "additionalProperties": false,
  "properties": {
    "success": {
      "title": "Success",
      "type": "boolean"
    },
    "resource_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Resource Name"
    }
  },
  "required": [
    "success"
  ],
  "title": "DeleteContactOutput",
  "type": "object"
}

get_contact — Fetch a single contact by its People API resource name.

Parameters

string

required

The People API resource name identifying the contact, e.g. ‘people/c123456789’.

array

required

Contact fields to return — any of: addresses, ageRanges, biographies, birthdays, calendarUrls, clientData, coverPhotos, emailAddresses, events, externalIds, genders, imClients, interests, locales, locations, memberships, metadata, miscKeywords, names, nicknames, occupations, organizations, phoneNumbers, photos, relations, sipAddresses, skills, urls, userDefined.

Response

{
  "$defs": {
    "ContactSummary": {
      "additionalProperties": false,
      "description": "A Google People `Person` resource, projected to the fields most tools read.",
      "properties": {
        "resource_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Resource Name"
        },
        "etag": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Etag"
        },
        "display_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Display Name"
        },
        "given_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Given Name"
        },
        "family_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Family Name"
        },
        "middle_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Middle Name"
        },
        "email_addresses": {
          "items": {
            "type": "string"
          },
          "title": "Email Addresses",
          "type": "array"
        },
        "phone_numbers": {
          "items": {
            "type": "string"
          },
          "title": "Phone Numbers",
          "type": "array"
        },
        "organizations": {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "title": "Organizations",
          "type": "array"
        },
        "addresses": {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "title": "Addresses",
          "type": "array"
        },
        "biographies": {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "title": "Biographies",
          "type": "array"
        },
        "urls": {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "title": "Urls",
          "type": "array"
        },
        "birthdays": {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "title": "Birthdays",
          "type": "array"
        },
        "genders": {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "title": "Genders",
          "type": "array"
        },
        "raw": {
          "additionalProperties": true,
          "description": "Untouched upstream Person object — all fields requested via personFields.",
          "title": "Raw",
          "type": "object"
        }
      },
      "title": "ContactSummary",
      "type": "object"
    }
  },
  "additionalProperties": false,
  "properties": {
    "success": {
      "title": "Success",
      "type": "boolean"
    },
    "contact": {
      "anyOf": [
        {
          "$ref": "#/$defs/ContactSummary"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    }
  },
  "required": [
    "success"
  ],
  "title": "GetContactOutput",
  "type": "object"
}

list_contacts — List every contact owned by the authenticated user (auto-paginates).

Parameters

array

required

Contact fields to return on every result — same enum as get_contact’s fields.

integer

Maximum number of pages to fetch (1-500). Prevents runaway pagination. (Default: 50)

Response

{
  "$defs": {
    "ContactSummary": {
      "additionalProperties": false,
      "description": "A Google People `Person` resource, projected to the fields most tools read.",
      "properties": {
        "resource_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Resource Name"
        },
        "etag": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Etag"
        },
        "display_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Display Name"
        },
        "given_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Given Name"
        },
        "family_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Family Name"
        },
        "middle_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Middle Name"
        },
        "email_addresses": {
          "items": {
            "type": "string"
          },
          "title": "Email Addresses",
          "type": "array"
        },
        "phone_numbers": {
          "items": {
            "type": "string"
          },
          "title": "Phone Numbers",
          "type": "array"
        },
        "organizations": {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "title": "Organizations",
          "type": "array"
        },
        "addresses": {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "title": "Addresses",
          "type": "array"
        },
        "biographies": {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "title": "Biographies",
          "type": "array"
        },
        "urls": {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "title": "Urls",
          "type": "array"
        },
        "birthdays": {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "title": "Birthdays",
          "type": "array"
        },
        "genders": {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "title": "Genders",
          "type": "array"
        },
        "raw": {
          "additionalProperties": true,
          "description": "Untouched upstream Person object — all fields requested via personFields.",
          "title": "Raw",
          "type": "object"
        }
      },
      "title": "ContactSummary",
      "type": "object"
    }
  },
  "additionalProperties": false,
  "properties": {
    "success": {
      "title": "Success",
      "type": "boolean"
    },
    "contacts": {
      "items": {
        "$ref": "#/$defs/ContactSummary"
      },
      "title": "Contacts",
      "type": "array"
    },
    "total": {
      "default": 0,
      "title": "Total",
      "type": "integer"
    }
  },
  "required": [
    "success"
  ],
  "title": "ListContactsOutput",
  "type": "object"
}

list_directory_contacts — List contacts from the Google Workspace directory (domain contacts / domain profiles). Requires the directory.readonly OAuth scope.

Parameters

array

required

Contact fields to return — same enum as get_contact’s fields.

string

required

Directory source to return: ‘DIRECTORY_SOURCE_TYPE_DOMAIN_CONTACT’ or ‘DIRECTORY_SOURCE_TYPE_DOMAIN_PROFILE’.

array

Optional. Additional sources to merge in via verified join keys. Any of: ‘DIRECTORY_MERGE_SOURCE_TYPE_UNSPECIFIED’, ‘DIRECTORY_MERGE_SOURCE_TYPE_CONTACT’.

integer

Number of people per response page (1-1000). Defaults to 100. (Default: 100)

string

Page token returned from a previous response’s nextPageToken.

boolean

Whether the response should include a nextSyncToken for incremental sync. (Default: false)

string

Sync token from a previous response — fetch only resources changed since then.

Response

{
  "$defs": {
    "ContactSummary": {
      "additionalProperties": false,
      "description": "A Google People `Person` resource, projected to the fields most tools read.",
      "properties": {
        "resource_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Resource Name"
        },
        "etag": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Etag"
        },
        "display_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Display Name"
        },
        "given_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Given Name"
        },
        "family_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Family Name"
        },
        "middle_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Middle Name"
        },
        "email_addresses": {
          "items": {
            "type": "string"
          },
          "title": "Email Addresses",
          "type": "array"
        },
        "phone_numbers": {
          "items": {
            "type": "string"
          },
          "title": "Phone Numbers",
          "type": "array"
        },
        "organizations": {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "title": "Organizations",
          "type": "array"
        },
        "addresses": {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "title": "Addresses",
          "type": "array"
        },
        "biographies": {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "title": "Biographies",
          "type": "array"
        },
        "urls": {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "title": "Urls",
          "type": "array"
        },
        "birthdays": {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "title": "Birthdays",
          "type": "array"
        },
        "genders": {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "title": "Genders",
          "type": "array"
        },
        "raw": {
          "additionalProperties": true,
          "description": "Untouched upstream Person object — all fields requested via personFields.",
          "title": "Raw",
          "type": "object"
        }
      },
      "title": "ContactSummary",
      "type": "object"
    }
  },
  "additionalProperties": false,
  "properties": {
    "success": {
      "title": "Success",
      "type": "boolean"
    },
    "people": {
      "items": {
        "$ref": "#/$defs/ContactSummary"
      },
      "title": "People",
      "type": "array"
    },
    "next_page_token": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Next Page Token"
    },
    "next_sync_token": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Next Sync Token"
    },
    "total": {
      "default": 0,
      "title": "Total",
      "type": "integer"
    }
  },
  "required": [
    "success"
  ],
  "title": "ListDirectoryContactsOutput",
  "type": "object"
}

update_contact — Update an existing contact. Re-fetches the latest etag first to avoid stale-update errors.

Parameters

string

required

The People API resource name identifying the contact to update.

array

required

Contact sections to update — any of: names, emailAddresses, phoneNumbers, addresses, biographies, birthdays, calendarUrls, genders, urls.

string

Updated first name (used when update_person_fields includes ‘names’).

string

Updated middle name (used when update_person_fields includes ‘names’).

string

Updated last name (used when update_person_fields includes ‘names’).

string

Updated email (used when update_person_fields includes ‘emailAddresses’).

string

Updated phone (used when update_person_fields includes ‘phoneNumbers’).

string

Updated street address (used when update_person_fields includes ‘addresses’).

string

Updated city.

string

Updated state / region.

string

Updated postal / zip code.

string

Updated country.

string

Updated biography.

string

Updated birthday in YYYY-MM-DD format.

string

Updated calendar URL.

string

Updated gender: male, female, or unspecified.

array

Updated list of associated URLs.

object

Optional extra fields merged into the Person request body. See https://developers.google.com/people/api/rest/v1/people for the full schema.

Response

{
  "$defs": {
    "ContactSummary": {
      "additionalProperties": false,
      "description": "A Google People `Person` resource, projected to the fields most tools read.",
      "properties": {
        "resource_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Resource Name"
        },
        "etag": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Etag"
        },
        "display_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Display Name"
        },
        "given_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Given Name"
        },
        "family_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Family Name"
        },
        "middle_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Middle Name"
        },
        "email_addresses": {
          "items": {
            "type": "string"
          },
          "title": "Email Addresses",
          "type": "array"
        },
        "phone_numbers": {
          "items": {
            "type": "string"
          },
          "title": "Phone Numbers",
          "type": "array"
        },
        "organizations": {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "title": "Organizations",
          "type": "array"
        },
        "addresses": {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "title": "Addresses",
          "type": "array"
        },
        "biographies": {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "title": "Biographies",
          "type": "array"
        },
        "urls": {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "title": "Urls",
          "type": "array"
        },
        "birthdays": {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "title": "Birthdays",
          "type": "array"
        },
        "genders": {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "title": "Genders",
          "type": "array"
        },
        "raw": {
          "additionalProperties": true,
          "description": "Untouched upstream Person object — all fields requested via personFields.",
          "title": "Raw",
          "type": "object"
        }
      },
      "title": "ContactSummary",
      "type": "object"
    }
  },
  "additionalProperties": false,
  "properties": {
    "success": {
      "title": "Success",
      "type": "boolean"
    },
    "contact": {
      "anyOf": [
        {
          "$ref": "#/$defs/ContactSummary"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    }
  },
  "required": [
    "success"
  ],
  "title": "UpdateContactOutput",
  "type": "object"
}

Limits & Quotas

Google People API default quota: 90 reads/minute and 60 writes/minute per user, 1,200 reads/minute per project. Higher limits available via Google Cloud quota request.
list_contacts auto-paginates through people/me/connections — beware large contact directories (each page is 100 contacts by default; the implementation fetches every page in sequence).
list_directory_contacts returns one page per call; supply page_token / sync_token from a previous response for pagination or incremental sync.
update_contact performs an extra GET to refresh the etag before the PATCH. Stale-etag updates are rejected by Google with HTTP 400.
Error model: non-2xx responses raise httpx.HTTPStatusError. The modulex runtime surfaces these as failed tool calls — plan for retries on the agent side if a transient 5xx is possible.

Using

Providers

Building

Tools

Google Contacts Integration for AI Agents & Workflows

Overview

Authentication

Google OAuth2

Required Credentials

OAuth Configuration

Available Actions

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Limits & Quotas

Insightly

Microsoft Dynamics 365 Sales

Bloomerang

Links

​Overview

​Authentication

​Google OAuth2

​Required Credentials

​OAuth Configuration

​Available Actions

​Parameters

​Response

​Parameters

​Response

​Parameters

​Response

​Parameters

​Response

​Parameters

​Response

​Parameters

​Response

​Limits & Quotas

​Related integrations

Insightly

Microsoft Dynamics 365 Sales

Bloomerang

​Links

Overview

Authentication

Google OAuth2

Required Credentials

OAuth Configuration

Available Actions

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Limits & Quotas

Related integrations

Links