Method: people.connections.list

Provides a list of the authenticated user's contacts.

The request returns a 400 error if personFields is not specified. The request returns a 410 error if syncToken is specified and is expired. Sync tokens expire after 7 days to prevent data drift between clients and the server. To handle a sync token expired error, a request should be sent without syncToken to get all contacts.

HTTP request

GET https://people.googleapis.com/v1/{resourceName=people/*}/connections

The URL uses gRPC Transcoding syntax.

Path parameters

Parameters
resourceName
(deprecated)

string

Required. The resource name to return connections for. Only people/me is valid.

Query parameters

Parameters
pageToken

string

Optional. A page token, received from a previous connections.list call. Provide this to retrieve the subsequent page.

When paginating, all other parameters provided to connections.list must match the call that provided the page token.

pageSize

integer

Optional. The number of connections to include in the response. Valid values are between 1 and 1000, inclusive. Defaults to 100 if not set or set to 0.

sortOrder

enum (SortOrder)

Optional. The order in which the connections should be sorted. Defaults to LAST_MODIFIED_ASCENDING.

requestSyncToken

boolean

Optional. Whether the response should include nextSyncToken on the last page, which can be used to get all changes since the last request. For subsequent sync requests use the syncToken param instead. Initial full sync requests that specify requestSyncToken and do not specify syncToken have an additional rate limit per user. Each client should generally only be doing a full sync once every few days per user and so should not hit this limit.

syncToken

string

Optional. A sync token, received from a previous connections.list call. Provide this to retrieve only the resources changed since the last request.

When the syncToken is specified, resources deleted since the last sync will be returned as a person with PersonMetadata.deleted set to true.

When the syncToken is specified, all other parameters provided to connections.list except pageSize and pageToken must match the initial call that provided the sync token.

Sync tokens expire after seven days, after which a full sync request without a syncToken should be made.

requestMask
(deprecated)

object (RequestMask)

Optional. DEPRECATED (Please use personFields instead)

A mask to restrict results to a subset of person fields.

personFields

string (FieldMask format)

Required. A field mask to restrict which fields on each person are returned. Multiple fields can be specified by separating them with commas. Valid values are:

  • 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
sources[]

enum (ReadSourceType)

Optional. A mask of what source types to return. Defaults to READ_SOURCE_TYPE_CONTACT and READ_SOURCE_TYPE_PROFILE if not set.

Request body

The request body must be empty.

Response body

If successful, the response body contains data with the following structure:

The response to a request for the authenticated user's connections.

JSON representation
{
  "connections": [
    {
      object (Person)
    }
  ],
  "nextPageToken": string,
  "nextSyncToken": string,
  "totalPeople": integer,
  "totalItems": integer
}
Fields
connections[]

object (Person)

The list of people that the requestor is connected to.

nextPageToken

string

A token, which can be sent as pageToken to retrieve the next page. If this field is omitted, there are no subsequent pages.

nextSyncToken

string

A token, which can be sent as syncToken to retrieve changes since the last request. Request must set requestSyncToken to return the sync token. When the response is paginated, only the last page will contain nextSyncToken.

totalPeople
(deprecated)

integer

DEPRECATED (Please use totalItems) The total number of people in the list without pagination.

totalItems

integer

The total number of items in the list without pagination.

Authorization Scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/contacts
  • https://www.googleapis.com/auth/contacts.readonly

For more information, see the Authorization guide.

SortOrder

The order in which a list of connections should be sorted. This is only used if sync is not requested.

Enums
LAST_MODIFIED_ASCENDING Sort people by when they were changed; older entries first.
LAST_MODIFIED_DESCENDING Sort people by when they were changed; newer entries first.
FIRST_NAME_ASCENDING Sort people by first name.
LAST_NAME_ASCENDING Sort people by last name.