--- name: google-contacts description: | Google 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). compatibility: Requires network access and valid Maton API key metadata: author: maton version: "1.0" clawdbot: emoji: 🧠 requires: env: - MATON_API_KEY ---

Google Contacts

Access the Google People API with managed OAuth authentication. Manage contacts, contact groups, and search your address book.

Quick Start

# 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))
EOF

Base URL

https://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.

Authentication

All requests require the Maton API key in the Authorization header:

Authorization: Bearer $MATON_API_KEY

Environment Variable: Set your API key as MATON_API_KEY:

export MATON_API_KEY="YOUR_API_KEY"

Getting Your API Key

1. Sign in or create an account at maton.ai
2. Go to maton.ai/settings
3. Copy your API key

Connection Management

Manage your Google Contacts OAuth connections at https://ctrl.maton.ai.

List Connections

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))
EOF

Create Connection

python <<'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))
EOF

Get Connection

python <<'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))
EOF

Response:

{
  "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.

Delete Connection

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))
EOF

Specifying Connection

If 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))
EOF

If omitted, the gateway uses the default (oldest) active connection.

API Reference

Contact Operations

List Contacts

GET /google-contacts/v1/people/me/connections?personFields=names,emailAddresses,phoneNumbers&pageSize=100

Query 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 pagination
• sortOrder: LAST_MODIFIED_ASCENDING, LAST_MODIFIED_DESCENDING, FIRST_NAME_ASCENDING, or LAST_NAME_ASCENDING

Response:

{
  "connections": [
    {
      "resourceName": "people/c1234567890",
      "names": [{"displayName": "John Doe", "givenName": "John", "familyName": "Doe"}],
      "emailAddresses": [{"value": "[email protected]"}],
      "phoneNumbers": [{"value": "+1-555-0123"}]
    }
  ],
  "totalPeople": 1,
  "totalItems": 1,
  "nextPageToken": "..."
}

Get Contact

GET /google-contacts/v1/people/{resourceName}?personFields=names,emailAddresses,phoneNumbers

Use the resource name from list or create operations (e.g., people/c1234567890).

Create Contact

POST /google-contacts/v1/people:createContact
Content-Type: application/json

{
  "names": [{"givenName": "John", "familyName": "Doe"}],
  "emailAddresses": [{"value": "[email protected]"}],
  "phoneNumbers": [{"value": "+1-555-0123"}],
  "organizations": [{"name": "Acme Corp", "title": "Engineer"}]
}

Update Contact

PATCH /google-contacts/v1/people/{resourceName}:updateContact?updatePersonFields=names,emailAddresses
Content-Type: application/json

{
  "etag": "%EgcBAgkLLjc9...",
  "names": [{"givenName": "John", "familyName": "Smith"}],
  "emailAddresses": [{"value": "[email protected]"}]
}

Note: Include the etag from the get/list response to ensure you're updating the latest version.

Delete Contact

DELETE /google-contacts/v1/people/{resourceName}:deleteContact

Batch Get Contacts

GET /google-contacts/v1/people:batchGet?resourceNames=people/c123&resourceNames=people/c456&personFields=names,emailAddresses

Batch Create Contacts

POST /google-contacts/v1/people:batchCreateContacts
Content-Type: application/json

{
  "contacts": [
    {
      "contactPerson": {
        "names": [{"givenName": "Alice", "familyName": "Smith"}],
        "emailAddresses": [{"value": "[email protected]"}]
      }
    },
    {
      "contactPerson": {
        "names": [{"givenName": "Bob", "familyName": "Jones"}],
        "emailAddresses": [{"value": "[email protected]"}]
      }
    }
  ],
  "readMask": "names,emailAddresses"
}

Batch Delete Contacts

POST /google-contacts/v1/people:batchDeleteContacts
Content-Type: application/json

{
  "resourceNames": ["people/c123", "people/c456"]
}

Search Contacts

GET /google-contacts/v1/people:searchContacts?query=John&readMask=names,emailAddresses

Note: Search results may have a slight delay for newly created contacts due to indexing.

Contact Group Operations

List Contact Groups

GET /google-contacts/v1/contactGroups?pageSize=100

Response:

{
  "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 Contact Group

...