Skip to main content

​
Overview

The People API allows you to manage Google Contacts, read user profile information, and access directory information. API Name: people
Version: v1
Official Documentation: People API Reference

​
Common Resources

​
People

Access person information and contacts.
​
resourceName
string
required
The person resource name (e.g., people/c1234567890 or people/me)
​
personFields
string
required
Comma-separated list of fields to return (e.g., names,emailAddresses,phoneNumbers)

​
Contact Groups

Manage contact groups (labels).
​
resourceName
string
The contact group resource name
​
name
string
The contact group name

​
Common Methods

​
Get Person

gws people people get --params '{
  "resourceName": "people/me",
  "personFields": "names,emailAddresses,phoneNumbers"
}'
​
resourceName
string
The person’s resource name
​
names
array
Array of name objects
​
displayName
string
Full name
​
emailAddresses
array
Array of email address objects

​
Search Contacts

gws people people searchContacts --params '{
  "query": "alice",
  "readMask": "names,emailAddresses"
}'

​
List Contacts

gws people people connections list --params '{
  "resourceName": "people/me",
  "personFields": "names,emailAddresses,phoneNumbers",
  "pageSize": 100
}'
​
connections
array
Array of person objects
​
resourceName
string
The person’s resource name
​
names
array
Person’s names
​
emailAddresses
array
Person’s email addresses

​
Create Contact

gws people people createContact --json '{
  "names": [{
    "givenName": "Alice",
    "familyName": "Smith"
  }],
  "emailAddresses": [{
    "value": "alice@example.com"
  }],
  "phoneNumbers": [{
    "value": "+1-555-123-4567",
    "type": "work"
  }]
}'

​
Update Contact

gws people people updateContact \
  --params '{
    "resourceName": "people/c1234567890",
    "updatePersonFields": "phoneNumbers"
  }' \
  --json '{
    "phoneNumbers": [{
      "value": "+1-555-999-8888",
      "type": "mobile"
    }]
  }'

​
Delete Contact

gws people people deleteContact --params '{
  "resourceName": "people/c1234567890"
}'

​
Contact Group Operations

gws people contactGroups list

​
Batch Operations

gws people people getBatchGet --params '{
  "resourceNames": ["people/c123", "people/c456"],
  "personFields": "names,emailAddresses"
}'

​
Response Format

Get person response: 
{
  "resourceName": "people/c1234567890",
  "etag": "abc123",
  "names": [
    {
      "displayName": "Alice Smith",
      "givenName": "Alice",
      "familyName": "Smith"
    }
  ],
  "emailAddresses": [
    {
      "value": "alice@example.com",
      "type": "work"
    }
  ],
  "phoneNumbers": [
    {
      "value": "+1-555-123-4567",
      "type": "work"
    }
  ]
}
List contacts response: 
{
  "connections": [
    {
      "resourceName": "people/c123",
      "names": [{"displayName": "Alice Smith"}],
      "emailAddresses": [{"value": "alice@example.com"}]
    }
  ],
  "nextPageToken": "xyz789...",
  "totalItems": 152
}

​
Key Resources

  • people - Access person information and contacts
  • people.connections - List user’s contacts
  • contactGroups - Manage contact groups
  • otherContacts - Access auto-created contacts

​
Available Person Fields

When requesting person data, specify which fields to return:
  • names - Person’s names
  • emailAddresses - Email addresses
  • phoneNumbers - Phone numbers
  • addresses - Physical addresses
  • birthdays - Birthdays
  • organizations - Organizations and jobs
  • urls - Websites
  • photos - Profile photos
  • biographies - About/bio text
  • metadata - Metadata about the person

​
Directory People

Access domain directory information (requires domain-wide delegation): 
# List directory people
gws people people listDirectoryPeople --params '{
  "readMask": "names,emailAddresses",
  "pageSize": 100
}'

# Search directory
gws people people searchDirectoryPeople --params '{
  "query": "alice",
  "readMask": "names,emailAddresses"
}'

​
Learn More

​
Schema Inspection

Before calling any method, inspect its schema: 
gws schema people.people.get
gws schema people.people.createContact