Skip to content
Scalekit Docs
Talk to an EngineerDashboard

Google Contacts

scalekit24 toolsOAuth 2.0Productivity

Google Contacts (People API) lets you manage your contacts, contact groups, and directory information. Create, read, update, and delete contacts and...

Google Contacts connector

  1. Install the SDK

    Section titled “Install the SDK”
    Terminal window
    npm install @scalekit-sdk/node

    Full SDK reference: Node.js | Python

  2. Set your credentials

    Section titled “Set your credentials”

    Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

    .env
    SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
    SCALEKIT_CLIENT_ID=<your-client-id>
    SCALEKIT_CLIENT_SECRET=<your-client-secret>

  3. Authorize and make your first call

    Section titled “Authorize and make your first call”
    quickstart.ts
    import { ScalekitClient } from '@scalekit-sdk/node'
    import 'dotenv/config'
    

    const scalekit = new ScalekitClient(
      process.env.SCALEKIT_ENV_URL,
      process.env.SCALEKIT_CLIENT_ID,
      process.env.SCALEKIT_CLIENT_SECRET,
    )
    const actions = scalekit.actions
    

    const connector = 'googlecontacts'
    const identifier = 'user_123'
    

    // Generate an authorization link for the user
    const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
    console.log('Authorize Google Contacts:', link)
    process.stdout.write('Press Enter after authorizing...')
    await new Promise(r => process.stdin.once('data', r))
    

    // Make your first call
    const result = await actions.executeTool({
      connector,
      identifier,
      toolName: 'googlecontacts_groups_list',
      toolInput: {},
    })
    console.log(result)

What you can do

Section titled “What you can do”

Connect this agent connector to let your agent:

  • Get people batch, groups batch, group — Retrieves up to 200 contacts in a single request by their resource names from Google Contacts
  • Search other contacts, directory, contacts — Searches the authenticated user’s ‘Other Contacts’ by prefix query across names, email addresses, and phone numbers
  • List other contacts, groups, directory — Returns the authenticated user’s ‘Other Contacts’ — contacts auto-generated from email history that haven’t been saved to personal contacts
  • Copy other contact — Copies an ‘Other Contact’ (auto-generated from email history) into the authenticated user’s main contacts (myContacts group)
  • Update group, contacts batch, contact — Updates the name of an existing contact group in Google Contacts
  • Modify group members — Adds or removes contacts from a contact group

Tool list

Section titled “Tool list”

Use the exact tool names from the Tool list below when you call execute_tool. If you’re not sure which name to use, list the tools available for the current user first.

googlecontacts_contact_create#Creates a new contact in Google Contacts for the authenticated user.10 params

Creates a new contact in Google Contacts for the authenticated user.

NameTypeRequiredDescription
person_fieldsstringrequiredComma-separated fields to return in the response.
emailstringoptionalPrimary email address of the contact.
email_typestringoptionalType of email: home, work, or other.
family_namestringoptionalLast name of the contact.
given_namestringoptionalFirst name of the contact.
job_titlestringoptionalJob title at the organization.
notesstringoptionalFree-text notes or biography for the contact.
organizationstringoptionalCompany or organization name.
phonestringoptionalPrimary phone number of the contact.
phone_typestringoptionalType of phone: mobile, home, work, or other.
googlecontacts_contact_delete#Permanently deletes a contact from Google Contacts by resource name.1 param

Permanently deletes a contact from Google Contacts by resource name.

NameTypeRequiredDescription
person_idstringrequiredThe person ID of the contact to delete (the part after 'people/').
googlecontacts_contact_delete_photo#Removes the profile photo of a contact in Google Contacts.2 params

Removes the profile photo of a contact in Google Contacts.

NameTypeRequiredDescription
person_idstringrequiredThe person ID of the contact (the part after 'people/').
person_fieldsstringoptionalComma-separated FieldMask of person fields to return after deleting the photo.
googlecontacts_contact_get#Returns a single contact by resource name from Google Contacts.2 params

Returns a single contact by resource name from Google Contacts.

NameTypeRequiredDescription
person_fieldsstringrequiredComma-separated fields to return for the contact.
person_idstringrequiredThe person ID of the contact to retrieve (the part after 'people/'). 'me' is not supported by this connector: it requires Google's userinfo.profile scope, which is not part of this connection's granted scopes and will return a 403.
googlecontacts_contact_update#Updates an existing contact in Google Contacts. Only fields specified in update_person_fields are modified.13 params

Updates an existing contact in Google Contacts. Only fields specified in update_person_fields are modified.

NameTypeRequiredDescription
person_idstringrequiredThe person ID of the contact to update (the part after 'people/').
update_person_fieldsstringrequiredComma-separated list of fields to update (FieldMask).
emailstringoptionalUpdated primary email address.
email_typestringoptionalType of email: home, work, or other.
etagstringoptionalEtag of the contact for conflict detection (recommended).
family_namestringoptionalUpdated last name of the contact.
given_namestringoptionalUpdated first name of the contact.
job_titlestringoptionalUpdated job title at the organization.
notesstringoptionalUpdated free-text notes or biography.
organizationstringoptionalUpdated company or organization name.
person_fieldsstringoptionalComma-separated fields to return in the response.
phonestringoptionalUpdated primary phone number.
phone_typestringoptionalType of phone: mobile, home, work, or other.
googlecontacts_contact_update_photo#Uploads a new profile photo for a contact in Google Contacts. The photo must be provided as base64-encoded bytes.3 params

Uploads a new profile photo for a contact in Google Contacts. The photo must be provided as base64-encoded bytes.

NameTypeRequiredDescription
person_idstringrequiredThe person ID of the contact to update (the part after 'people/').
photo_bytesstringrequiredBase64-encoded bytes of the photo to upload.
person_fieldsstringoptionalComma-separated FieldMask of person fields to return after updating the photo.
googlecontacts_contacts_batch_create#Creates up to 200 new contacts in a single request in Google Contacts.2 params

Creates up to 200 new contacts in a single request in Google Contacts.

NameTypeRequiredDescription
contactsstringrequiredJSON array of contact objects to create (max 200). Each object is a Person resource with fields like names, emailAddresses, phoneNumbers.
read_maskstringrequiredComma-separated FieldMask of person fields to return for each created contact. Valid values: addresses, biographies, birthdays, emailAddresses, memberships, names, nicknames, organizations, phoneNumbers, photos, urls.
googlecontacts_contacts_batch_delete#Permanently deletes up to 500 contacts in a single request from Google Contacts.1 param

Permanently deletes up to 500 contacts in a single request from Google Contacts.

NameTypeRequiredDescription
resource_namesarrayrequiredArray of contact resource names to delete (max 500). e.g. ['people/c123456789']
googlecontacts_contacts_batch_update#Updates up to 200 existing contacts in a single request in Google Contacts.3 params

Updates up to 200 existing contacts in a single request in Google Contacts.

NameTypeRequiredDescription
contactsstringrequiredJSON object mapping each contact's resourceName (e.g. 'people/c123') to a Person object with updated fields (max 200 entries).
read_maskstringrequiredComma-separated FieldMask of person fields to return for each updated contact.
update_maskstringrequiredComma-separated FieldMask of person fields to update across all contacts.
googlecontacts_contacts_list#Returns all contacts (connections) for the authenticated user from Google Contacts, with cursor-based pagination and optional sync token support.6 params

Returns all contacts (connections) for the authenticated user from Google Contacts, with cursor-based pagination and optional sync token support.

NameTypeRequiredDescription
person_fieldsstringrequiredComma-separated FieldMask of person fields to return. Valid values: 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.
page_sizeintegeroptionalNumber of contacts to return per page (max 1000).
page_tokenstringoptionalPage token from a previous response for pagination.
request_sync_tokenbooleanoptionalIf true, returns a sync token on the last page for incremental sync.
sort_orderstringoptionalSort order for contacts. One of: LAST_MODIFIED_ASCENDING, LAST_MODIFIED_DESCENDING, FIRST_NAME_ASCENDING, LAST_NAME_ASCENDING.
sync_tokenstringoptionalSync token from a previous response to fetch only changed contacts.
googlecontacts_directory_list#Lists people in the Google Workspace domain directory. Requires the directory.readonly OAuth scope.6 params

Lists people in the Google Workspace domain directory. Requires the directory.readonly OAuth scope.

NameTypeRequiredDescription
read_maskstringrequiredComma-separated FieldMask of person fields to return. Valid values: 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.
sourcesstringrequiredDirectory source type to return. Use DIRECTORY_SOURCE_TYPE_DOMAIN_CONTACT for domain contacts or DIRECTORY_SOURCE_TYPE_DOMAIN_PROFILE for domain profiles.
page_sizeintegeroptionalNumber of people to return per page (1–1000, default 100).
page_tokenstringoptionalPage token from a previous response for pagination.
request_sync_tokenbooleanoptionalIf true, returns a sync token on the last page for incremental sync.
sync_tokenstringoptionalSync token from a previous response to fetch only changed people.
googlecontacts_group_create#Creates a new contact group with the given name in Google Contacts. Group names must be unique per user.2 params

Creates a new contact group with the given name in Google Contacts. Group names must be unique per user.

NameTypeRequiredDescription
namestringrequiredName of the new contact group (must be unique).
read_group_fieldsstringoptionalComma-separated fields to return in the response.
googlecontacts_group_delete#Deletes a contact group from Google Contacts. Optionally also deletes all contacts that belong to the group.2 params

Deletes a contact group from Google Contacts. Optionally also deletes all contacts that belong to the group.

NameTypeRequiredDescription
group_idstringrequiredThe group ID of the contact group to delete (the part after 'contactGroups/').
delete_contactsbooleanoptionalIf true, also deletes all contacts in the group.
googlecontacts_group_get#Returns a single contact group by resource name, including its members if requested.3 params

Returns a single contact group by resource name, including its members if requested.

NameTypeRequiredDescription
group_idstringrequiredThe group ID of the contact group (the part after 'contactGroups/').
group_fieldsstringoptionalComma-separated fields to return: clientData, groupType, memberCount, metadata, name.
max_membersintegeroptionalMaximum number of group members to return (default 0 = none).
googlecontacts_group_members_modify#Adds or removes contacts from a contact group. Supports adding to 'myContacts' and 'starred' groups, and removing from any group.3 params

Adds or removes contacts from a contact group. Supports adding to 'myContacts' and 'starred' groups, and removing from any group.

NameTypeRequiredDescription
group_idstringrequiredThe group ID of the contact group to modify (the part after 'contactGroups/').
resource_names_to_addarrayoptionalJSON array of contact resource names to add to the group.
resource_names_to_removearrayoptionalJSON array of contact resource names to remove from the group.
googlecontacts_group_update#Updates the name of an existing contact group in Google Contacts.5 params

Updates the name of an existing contact group in Google Contacts.

NameTypeRequiredDescription
group_idstringrequiredThe group ID of the contact group to update (the part after 'contactGroups/').
namestringrequiredNew name for the contact group (must be unique).
etagstringoptionalEtag of the contact group for conflict detection.
read_group_fieldsstringoptionalComma-separated fields to return in the response.
update_group_fieldsstringoptionalComma-separated fields to update: clientData, name. Defaults to name.
googlecontacts_groups_batch_get#Retrieves up to 200 contact groups in a single request from Google Contacts.3 params

Retrieves up to 200 contact groups in a single request from Google Contacts.

NameTypeRequiredDescription
resource_namesarrayrequiredOne or more contact group resource names to retrieve, in the format 'contactGroups/<id>' (e.g. 'contactGroups/myContacts' or 'contactGroups/starred'), up to 200. Get IDs from googlecontacts_groups_list. Sent as repeated resourceNames query parameters.
group_fieldsstringoptionalComma-separated fields to return for each group: clientData, groupType, memberCount, metadata, name.
max_membersintegeroptionalMaximum number of group members to return per group (default 0 = none).
googlecontacts_groups_list#Returns all contact groups owned by the authenticated user, including system groups like 'My Contacts' and 'Starred'.4 params

Returns all contact groups owned by the authenticated user, including system groups like 'My Contacts' and 'Starred'.

NameTypeRequiredDescription
group_fieldsstringoptionalComma-separated fields to return: clientData, groupType, memberCount, metadata, name.
page_sizeintegeroptionalNumber of contact groups to return per page (max 1000).
page_tokenstringoptionalPage token from a previous response for pagination.
sync_tokenstringoptionalSync token to fetch only changed contact groups. Unlike googlecontacts_contacts_list, this endpoint always returns nextSyncToken on the last page — no request flag is needed.
googlecontacts_other_contact_copy#Copies an 'Other Contact' (auto-generated from email history) into the authenticated user's main contacts (myContacts group).3 params

Copies an 'Other Contact' (auto-generated from email history) into the authenticated user's main contacts (myContacts group).

NameTypeRequiredDescription
copy_maskstringrequiredComma-separated FieldMask of fields to copy from the Other Contact. Valid values: emailAddresses, names, phoneNumbers.
person_idstringrequiredThe person ID of the Other Contact to copy (the part after 'otherContacts/').
read_maskstringoptionalComma-separated FieldMask of person fields to return for the newly created contact.
googlecontacts_other_contacts_list#Returns the authenticated user's 'Other Contacts' — contacts auto-generated from email history that haven't been saved to personal contacts.5 params

Returns the authenticated user's 'Other Contacts' — contacts auto-generated from email history that haven't been saved to personal contacts.

NameTypeRequiredDescription
read_maskstringrequiredComma-separated fields to return. Valid values: emailAddresses, metadata, names, phoneNumbers, photos.
page_sizeintegeroptionalNumber of contacts to return per page (max 1000).
page_tokenstringoptionalPage token from a previous response for pagination.
request_sync_tokenbooleanoptionalIf true, returns a sync token on the last page.
sync_tokenstringoptionalSync token to fetch only changed contacts (expires after 7 days).
googlecontacts_people_batch_get#Retrieves up to 200 contacts in a single request by their resource names from Google Contacts.2 params

Retrieves up to 200 contacts in a single request by their resource names from Google Contacts.

NameTypeRequiredDescription
person_fieldsstringrequiredComma-separated FieldMask of person fields to return. Valid values: 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.
resource_namesarrayrequiredOne or more contact resource names in the format 'people/<id>' (e.g. 'people/c123456789'), up to 200. Get resource names from googlecontacts_contacts_list. Sent as repeated resourceNames query parameters.