Skip to main content
Google Contacts logo

​
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

FieldDescriptionRequiredFormat
Client IDGoogle Cloud OAuth 2.0 Client ID.Yesxxxxxxxxxxxx-xxxxxxxxxxxxxxxx.apps.googleusercontent.com
Client SecretGoogle Cloud OAuth 2.0 Client Secret.YesGOCSPX-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

​
Parameters

​
person_fields
array
required
Contact fields to populate and return — any of: names, emailAddresses, phoneNumbers, addresses, biographies, birthdays, calendarUrls, genders, urls.
​
first_name
string
Contact’s first name (used when person_fields includes ‘names’).
​
middle_name
string
Contact’s middle name (used when person_fields includes ‘names’).
​
last_name
string
Contact’s last name (used when person_fields includes ‘names’).
​
email
string
Contact’s email address (used when person_fields includes ‘emailAddresses’).
​
phone_number
string
Contact’s phone number (used when person_fields includes ‘phoneNumbers’).
​
street_address
string
Street address (used when person_fields includes ‘addresses’).
​
city
string
City (used when person_fields includes ‘addresses’).
​
state
string
State / region (used when person_fields includes ‘addresses’).
​
zip_code
string
Postal / zip code (used when person_fields includes ‘addresses’).
​
country
string
Country (used when person_fields includes ‘addresses’).
​
biography
string
Biography text (used when person_fields includes ‘biographies’).
​
birthday
string
Birthday in YYYY-MM-DD format (used when person_fields includes ‘birthdays’).
​
calendar_url
string
Calendar URL (used when person_fields includes ‘calendarUrls’).
​
gender
string
Gender: male, female, or unspecified (used when person_fields includes ‘genders’).
​
urls
array
List of associated URLs (used when person_fields includes ‘urls’).
​
additional_fields
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"
}

​
Parameters

​
resource_name
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"
}

​
Parameters

​
resource_name
string
required
The People API resource name identifying the contact, e.g. ‘people/c123456789’.
​
fields
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"
}

​
Parameters

​
fields
array
required
Contact fields to return on every result — same enum as get_contact’s fields.
​
max_pages
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"
}

​
Parameters

​
fields
array
required
Contact fields to return — same enum as get_contact’s fields.
​
source
string
required
Directory source to return: ‘DIRECTORY_SOURCE_TYPE_DOMAIN_CONTACT’ or ‘DIRECTORY_SOURCE_TYPE_DOMAIN_PROFILE’.
​
merge_sources
array
Optional. Additional sources to merge in via verified join keys. Any of: ‘DIRECTORY_MERGE_SOURCE_TYPE_UNSPECIFIED’, ‘DIRECTORY_MERGE_SOURCE_TYPE_CONTACT’.
​
page_size
integer
Number of people per response page (1-1000). Defaults to 100. (Default: 100)
​
page_token
string
Page token returned from a previous response’s nextPageToken.
​
request_sync_token
boolean
Whether the response should include a nextSyncToken for incremental sync. (Default: false)
​
sync_token
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"
}

​
Parameters

​
resource_name
string
required
The People API resource name identifying the contact to update.
​
update_person_fields
array
required
Contact sections to update — any of: names, emailAddresses, phoneNumbers, addresses, biographies, birthdays, calendarUrls, genders, urls.
​
first_name
string
Updated first name (used when update_person_fields includes ‘names’).
​
middle_name
string
Updated middle name (used when update_person_fields includes ‘names’).
​
last_name
string
Updated last name (used when update_person_fields includes ‘names’).
​
email
string
Updated email (used when update_person_fields includes ‘emailAddresses’).
​
phone_number
string
Updated phone (used when update_person_fields includes ‘phoneNumbers’).
​
street_address
string
Updated street address (used when update_person_fields includes ‘addresses’).
​
city
string
Updated city.
​
state
string
Updated state / region.
​
zip_code
string
Updated postal / zip code.
​
country
string
Updated country.
​
biography
string
Updated biography.
​
birthday
string
Updated birthday in YYYY-MM-DD format.
​
calendar_url
string
Updated calendar URL.
​
gender
string
Updated gender: male, female, or unspecified.
​
urls
array
Updated list of associated URLs.
​
additional_fields
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.

Insightly

Microsoft Dynamics 365 Sales

Bloomerang