google-contactsGoogle Contacts API integration with managed OAuth. Manage contacts, contact groups, and search your address book. Use this skill when users want to create, read, update, or delete contacts, manage contact groups, or search for people in their Google account. For other third party apps, use the api-gateway skill (https://clawhub.ai/byungkyu/api-gateway).
Install via ClawdBot CLI:
clawdbot install byungkyu/google-contactsAccess the Google People API with managed OAuth authentication. Manage contacts, contact groups, and search your address book.
# List contacts
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/google-contacts/v1/people/me/connections?personFields=names,emailAddresses,phoneNumbers&pageSize=10')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOFhttps://gateway.maton.ai/google-contacts/{native-api-path}Replace {native-api-path} with the actual Google People API endpoint path. The gateway proxies requests to people.googleapis.com and automatically injects your OAuth token.
All requests require the Maton API key in the Authorization header:
Authorization: Bearer $MATON_API_KEYEnvironment Variable: Set your API key as MATON_API_KEY:
export MATON_API_KEY="YOUR_API_KEY"Manage your Google Contacts OAuth connections at https://ctrl.maton.ai.
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections?app=google-contacts&status=ACTIVE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOFpython <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'google-contacts'}).encode()
req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOFpython <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOFResponse:
{
"connection": {
"connection_id": "21fd90f9-5935-43cd-b6c8-bde9d915ca80",
"status": "ACTIVE",
"creation_time": "2025-12-08T07:20:53.488460Z",
"last_updated_time": "2026-01-31T20:03:32.593153Z",
"url": "https://connect.maton.ai/?session_token=...",
"app": "google-contacts",
"metadata": {}
}
}Open the returned url in a browser to complete OAuth authorization.
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOFIf you have multiple Google Contacts connections, specify which one to use with the Maton-Connection header:
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/google-contacts/v1/people/me/connections?personFields=names&pageSize=10')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', '21fd90f9-5935-43cd-b6c8-bde9d915ca80')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOFIf omitted, the gateway uses the default (oldest) active connection.
GET /google-contacts/v1/people/me/connections?personFields=names,emailAddresses,phoneNumbers&pageSize=100Query Parameters:
personFields (required): Comma-separated list of fields to return (see Person Fields section)pageSize: Number of contacts to return (max 1000, default 100)pageToken: Token for paginationsortOrder: LAST_MODIFIED_ASCENDING, LAST_MODIFIED_DESCENDING, FIRST_NAME_ASCENDING, or LAST_NAME_ASCENDINGResponse:
{
"connections": [
{
"resourceName": "people/c1234567890",
"names": [{"displayName": "John Doe", "givenName": "John", "familyName": "Doe"}],
"emailAddresses": [{"value": "john@example.com"}],
"phoneNumbers": [{"value": "+1-555-0123"}]
}
],
"totalPeople": 1,
"totalItems": 1,
"nextPageToken": "..."
}GET /google-contacts/v1/people/{resourceName}?personFields=names,emailAddresses,phoneNumbersUse the resource name from list or create operations (e.g., people/c1234567890).
POST /google-contacts/v1/people:createContact
Content-Type: application/json
{
"names": [{"givenName": "John", "familyName": "Doe"}],
"emailAddresses": [{"value": "john@example.com"}],
"phoneNumbers": [{"value": "+1-555-0123"}],
"organizations": [{"name": "Acme Corp", "title": "Engineer"}]
}PATCH /google-contacts/v1/people/{resourceName}:updateContact?updatePersonFields=names,emailAddresses
Content-Type: application/json
{
"etag": "%EgcBAgkLLjc9...",
"names": [{"givenName": "John", "familyName": "Smith"}],
"emailAddresses": [{"value": "john.smith@example.com"}]
}Note: Include the etag from the get/list response to ensure you're updating the latest version.
DELETE /google-contacts/v1/people/{resourceName}:deleteContactGET /google-contacts/v1/people:batchGet?resourceNames=people/c123&resourceNames=people/c456&personFields=names,emailAddressesPOST /google-contacts/v1/people:batchCreateContacts
Content-Type: application/json
{
"contacts": [
{
"contactPerson": {
"names": [{"givenName": "Alice", "familyName": "Smith"}],
"emailAddresses": [{"value": "alice@example.com"}]
}
},
{
"contactPerson": {
"names": [{"givenName": "Bob", "familyName": "Jones"}],
"emailAddresses": [{"value": "bob@example.com"}]
}
}
],
"readMask": "names,emailAddresses"
}POST /google-contacts/v1/people:batchDeleteContacts
Content-Type: application/json
{
"resourceNames": ["people/c123", "people/c456"]
}GET /google-contacts/v1/people:searchContacts?query=John&readMask=names,emailAddressesNote: Search results may have a slight delay for newly created contacts due to indexing.
GET /google-contacts/v1/contactGroups?pageSize=100Response:
{
"contactGroups": [
{
"resourceName": "contactGroups/starred",
"groupType": "SYSTEM_CONTACT_GROUP",
"name": "starred",
"formattedName": "Starred"
},
{
"resourceName": "contactGroups/abc123",
"groupType": "USER_CONTACT_GROUP",
"name": "Work",
"formattedName": "Work",
"memberCount": 5
}
],
"totalItems": 2
}GET /google-contacts/v1/contactGroups/{resourceName}?maxMembers=100Use contactGroups/starred, contactGroups/family, etc. for system groups, or the resource name for user groups.
POST /google-contacts/v1/contactGroups
Content-Type: application/json
{
"contactGroup": {
"name": "Work Contacts"
}
}DELETE /google-contacts/v1/contactGroups/{resourceName}?deleteContacts=falseSet deleteContacts=true to also delete the contacts in the group.
GET /google-contacts/v1/contactGroups:batchGet?resourceNames=contactGroups/starred&resourceNames=contactGroups/familyAdd or remove contacts from a group:
POST /google-contacts/v1/contactGroups/{resourceName}/members:modify
Content-Type: application/json
{
"resourceNamesToAdd": ["people/c123", "people/c456"],
"resourceNamesToRemove": ["people/c789"]
}Other contacts are people you've interacted with (e.g., via email) but haven't explicitly added to your contacts.
GET /google-contacts/v1/otherContacts?readMask=names,emailAddresses&pageSize=100POST /google-contacts/v1/{resourceName}:copyOtherContactToMyContactsGroup
Content-Type: application/json
{
"copyMask": "names,emailAddresses,phoneNumbers"
}Use these fields with personFields or readMask parameters:
| Field | Description |
|-------|-------------|
| names | Display name, given name, family name |
| emailAddresses | Email addresses with type |
| phoneNumbers | Phone numbers with type |
| addresses | Postal addresses |
| organizations | Company, title, department |
| biographies | Bio/notes about the person |
| birthdays | Birthday information |
| urls | Website URLs |
| photos | Profile photos |
| memberships | Contact group memberships |
| metadata | Source and update information |
Multiple fields: personFields=names,emailAddresses,phoneNumbers,organizations
Use pageSize and pageToken for pagination:
GET /google-contacts/v1/people/me/connections?personFields=names&pageSize=100&pageToken=NEXT_PAGE_TOKENResponse includes pagination info:
{
"connections": [...],
"totalPeople": 500,
"nextPageToken": "...",
"nextSyncToken": "..."
}Continue fetching with pageToken until nextPageToken is not returned.
const response = await fetch(
'https://gateway.maton.ai/google-contacts/v1/people/me/connections?personFields=names,emailAddresses&pageSize=50',
{
headers: {
'Authorization': `Bearer ${process.env.MATON_API_KEY}`
}
}
);
const data = await response.json();import os
import requests
response = requests.get(
'https://gateway.maton.ai/google-contacts/v1/people/me/connections',
headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'},
params={
'personFields': 'names,emailAddresses,phoneNumbers',
'pageSize': 50
}
)
data = response.json()people/c{id} (e.g., people/c1234567890)contactGroups/{id} (e.g., contactGroups/abc123)starred, friends, family, coworkers, myContacts, all, blockedpersonFields parameter is required for most read operationsetag to prevent overwriting concurrent changescurl -g when URLs contain brackets to disable glob parsingjq or other commands, environment variables like $MATON_API_KEY may not expand correctly in some shell environments| Status | Meaning |
|--------|---------|
| 400 | Missing Google Contacts connection or invalid request |
| 401 | Invalid or missing Maton API key |
| 403 | Permission denied (check OAuth scopes) |
| 404 | Contact or group not found |
| 429 | Rate limited |
| 4xx/5xx | Passthrough error from Google People API |
MATON_API_KEY environment variable is set:echo $MATON_API_KEYpython <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOFgoogle-contacts. For example:https://gateway.maton.ai/google-contacts/v1/people/me/connectionshttps://gateway.maton.ai/v1/people/me/connectionsGenerated Feb 24, 2026
Sales teams can automatically sync new leads from CRM systems to Google Contacts, ensuring contact details are updated in real-time. This reduces manual data entry and improves accuracy in client communication. It also enables quick access to contact histories during sales calls.
Event planners can manage attendee lists by creating and updating contacts for participants, speakers, and vendors in Google Contacts. This facilitates easy communication and scheduling through integrated email and calendar tools. It helps streamline event logistics and follow-ups.
Support teams can link customer support tickets to Google Contacts to maintain up-to-date contact information and interaction histories. This allows for personalized support and faster resolution by accessing past communications. It enhances customer relationship management in service industries.
HR departments can use this skill to manage candidate contacts, track application stages, and schedule interviews via integrated tools. It helps organize recruitment pipelines and improve communication with potential hires. This streamlines the hiring process for companies.
Freelancers can centralize client contacts, project details, and billing information in Google Contacts for easy access and organization. This simplifies invoicing and follow-up communications, improving productivity. It supports small business operations and independent contractors.
Offer a subscription-based service that integrates Google Contacts with other business tools like CRMs or email marketing platforms. Charge monthly or annual fees for access to advanced features and support. This model provides recurring revenue and scales with customer growth.
Implement a tiered pricing model based on API call volume, number of contacts managed, or features like advanced search. Offer free tiers for basic usage and paid tiers for higher limits and premium functionalities. This attracts a wide range of users from individuals to enterprises.
Provide white-label versions of the integration for other companies to rebrand and resell as part of their own products. Charge licensing fees or revenue shares for customization and support services. This expands market reach through partnerships and resellers.
💬 Integration Tip
Ensure the MATON_API_KEY is securely stored in environment variables and test connection management endpoints before deploying to production to avoid authentication issues.
Google Workspace CLI for Gmail, Calendar, Drive, Contacts, Sheets, and Docs.
Query Google Places API (New) via the goplaces CLI for text search, place details, resolve, and reviews. Use for human-friendly place lookup or JSON output for scripts.
Search for places (restaurants, cafes, etc.) via Google Places API proxy on localhost.
Gmail, Calendar, Drive, Docs, Sheets — NO Google Cloud Console required. Just OAuth sign-in. Zero setup complexity vs traditional Google API integrations.
Google Drive API integration with managed OAuth. List, search, create, and manage files and folders. Use this skill when users want to interact with Google D...
Google Sheets API integration with managed OAuth. Read and write spreadsheet data, create sheets, apply formatting, and manage ranges. Use this skill when users want to read from or write to Google Sheets. For other third party apps, use the api-gateway skill (https://clawhub.ai/byungkyu/api-gateway).