Google People

Google People API

Provides access to Google Contacts data including creating, reading, updating, and deleting contacts and contact groups, searching contacts, and accessing profile information.

GitHub OpenAPI

Documentation

📖
Documentation
https://developers.google.com/people/api/rest
📖
Authentication
https://developers.google.com/people/v1/how-tos/authorizing
📖
GettingStarted
https://developers.google.com/people/v1/getting-started

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/google-people/refs/heads/main/openapi/openapi.yml

Schemas & Data

📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/google-people/refs/heads/main/json-schema/Person.json

Other Resources

🔗
NaftikoCapability
https://raw.githubusercontent.com/api-evangelist/google-people/refs/heads/main/capabilities/openapi-people.yaml
🔗
NaftikoCapability
https://raw.githubusercontent.com/api-evangelist/google-people/refs/heads/main/capabilities/openapi-contactgroups.yaml
🔗
NaftikoCapability
https://raw.githubusercontent.com/api-evangelist/google-people/refs/heads/main/capabilities/openapi-people-batchget.yaml
🔗
NaftikoCapability
https://raw.githubusercontent.com/api-evangelist/google-people/refs/heads/main/capabilities/openapi-people-createcontact.yaml
🔗
NaftikoCapability
https://raw.githubusercontent.com/api-evangelist/google-people/refs/heads/main/capabilities/openapi-people-searchcontacts.yaml

OpenAPI Specification

openapi.yml Raw ↑ 
openapi: 3.1.0
info:
  title: Google People API
  description: >-
    The Google People API provides access to information about profiles and
    contacts. It enables reading and managing the authenticated user's contacts
    and accessing profile information for authenticated users across Google
    services.
  version: 1.0.0
  contact:
    name: Google
    url: https://developers.google.com/people
servers:
  - url: https://people.googleapis.com/v1
paths:
  /people/{resourceName}:
    get:
      operationId: getPerson
      summary: Google People Get Person
      description: Provides information about a person by specifying a resource name.
      parameters:
        - name: resourceName
          in: path
          required: true
          description: The resource name of the person (e.g., people/me).
          schema:
            type: string
        - name: personFields
          in: query
          required: true
          description: >-
            A field mask to restrict which fields on the person are returned.
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Person'
      tags:
        - People
  /people:batchGet:
    get:
      operationId: batchGetPeople
      summary: Google People Batch Get People
      description: Provides information about a list of specific people.
      parameters:
        - name: resourceNames
          in: query
          required: true
          schema:
            type: array
            items:
              type: string
        - name: personFields
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
      tags:
        - people:batchGet
  /people:searchContacts:
    get:
      operationId: searchContacts
      summary: Google People Search Contacts
      description: Provides a list of contacts in the user's contact groups that match a query.
      parameters:
        - name: query
          in: query
          required: true
          schema:
            type: string
        - name: readMask
          in: query
          required: true
          schema:
            type: string
        - name: pageSize
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: Successful response
      tags:
        - people:searchContacts
  /people:createContact:
    post:
      operationId: createContact
      summary: Google People Create Contact
      description: Create a new contact and return the person resource for that contact.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Person'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Person'
      tags:
        - people:createContact
  /people/{resourceName}:deleteContact:
    delete:
      operationId: deleteContact
      summary: Google People Delete Contact
      description: Delete a contact person.
      parameters:
        - name: resourceName
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
      tags:
        - People
  /people/{resourceName}:updateContact:
    patch:
      operationId: updateContact
      summary: Google People Update Contact
      description: Update contact data for an existing contact person.
      parameters:
        - name: resourceName
          in: path
          required: true
          schema:
            type: string
        - name: updatePersonFields
          in: query
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Person'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Person'
      tags:
        - People
  /people/me/connections:
    get:
      operationId: listConnections
      summary: Google People List Connections
      description: Provides a list of the authenticated user's contacts.
      parameters:
        - name: personFields
          in: query
          required: true
          schema:
            type: string
        - name: pageSize
          in: query
          schema:
            type: integer
        - name: pageToken
          in: query
          schema:
            type: string
        - name: sortOrder
          in: query
          schema:
            type: string
            enum:
              - LAST_MODIFIED_ASCENDING
              - LAST_MODIFIED_DESCENDING
              - FIRST_NAME_ASCENDING
              - LAST_NAME_ASCENDING
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListConnectionsResponse'
      tags:
        - People
  /contactGroups:
    get:
      operationId: listContactGroups
      summary: Google People List Contact Groups
      description: List all contact groups owned by the authenticated user.
      parameters:
        - name: pageSize
          in: query
          schema:
            type: integer
        - name: pageToken
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Successful response
      tags:
        - contactGroups
    post:
      operationId: createContactGroup
      summary: Google People Create Contact Group
      description: Create a new contact group.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactGroup'
      responses:
        '200':
          description: Successful response
      tags:
        - contactGroups
  /contactGroups/{resourceName}:
    get:
      operationId: getContactGroup
      summary: Google People Get Contact Group
      description: Get a specific contact group.
      parameters:
        - name: resourceName
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactGroup'
      tags:
        - contactGroups
    put:
      operationId: updateContactGroup
      summary: Google People Update Contact Group
      description: Update the name of an existing contact group.
      parameters:
        - name: resourceName
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactGroup'
      responses:
        '200':
          description: Successful response
      tags:
        - contactGroups
    delete:
      operationId: deleteContactGroup
      summary: Google People Delete Contact Group
      description: Delete an existing contact group.
      parameters:
        - name: resourceName
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
      tags:
        - contactGroups
components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://accounts.google.com/o/oauth2/auth
          tokenUrl: https://oauth2.googleapis.com/token
          scopes:
            https://www.googleapis.com/auth/contacts: Manage contacts
            https://www.googleapis.com/auth/contacts.readonly: View contacts
  schemas:
    Person:
      type: object
      properties:
        resourceName:
          type: string
        etag:
          type: string
        names:
          type: array
          items:
            type: object
            properties:
              displayName:
                type: string
              familyName:
                type: string
              givenName:
                type: string
              middleName:
                type: string
        emailAddresses:
          type: array
          items:
            type: object
            properties:
              value:
                type: string
              type:
                type: string
        phoneNumbers:
          type: array
          items:
            type: object
            properties:
              value:
                type: string
              type:
                type: string
        addresses:
          type: array
          items:
            type: object
            properties:
              formattedValue:
                type: string
              type:
                type: string
              streetAddress:
                type: string
              city:
                type: string
              region:
                type: string
              postalCode:
                type: string
              country:
                type: string
        organizations:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              title:
                type: string
        photos:
          type: array
          items:
            type: object
            properties:
              url:
                type: string
        birthdays:
          type: array
          items:
            type: object
            properties:
              date:
                type: object
                properties:
                  year:
                    type: integer
                  month:
                    type: integer
                  day:
                    type: integer
        biographies:
          type: array
          items:
            type: object
            properties:
              value:
                type: string
        urls:
          type: array
          items:
            type: object
            properties:
              value:
                type: string
              type:
                type: string
    ContactGroup:
      type: object
      properties:
        resourceName:
          type: string
        etag:
          type: string
        name:
          type: string
        formattedName:
          type: string
        memberCount:
          type: integer
        groupType:
          type: string
    ListConnectionsResponse:
      type: object
      properties:
        connections:
          type: array
          items:
            $ref: '#/components/schemas/Person'
        nextPageToken:
          type: string
        totalPeople:
          type: integer
        totalItems:
          type: integer
security:
  - OAuth2: []
tags:
  - name: contactGroups
  - name: People
  - name: people:batchGet
  - name: people:createContact
  - name: people:searchContacts