# Method: people.connections.list

- [HTTP request](https://developers.google.com/people/api/rest/v1/people.connections/list#body.HTTP_TEMPLATE)
- [Path parameters](https://developers.google.com/people/api/rest/v1/people.connections/list#body.PATH_PARAMETERS)
- [Query parameters](https://developers.google.com/people/api/rest/v1/people.connections/list#body.QUERY_PARAMETERS)
- [Request body](https://developers.google.com/people/api/rest/v1/people.connections/list#body.request_body)
- [Response body](https://developers.google.com/people/api/rest/v1/people.connections/list#body.response_body)
  - [JSON representation](https://developers.google.com/people/api/rest/v1/people.connections/list#body.ListConnectionsResponse.SCHEMA_REPRESENTATION)
- [Authorization scopes](https://developers.google.com/people/api/rest/v1/people.connections/list#body.aspect)
- [SortOrder](https://developers.google.com/people/api/rest/v1/people.connections/list#SortOrder)
- [Try it!](https://developers.google.com/people/api/rest/v1/people.connections/list#try-it)

Provides a list of the authenticated user's contacts.

Sync tokens expire 7 days after the full sync. A request with an expired sync token will get an error with an [google.rpc.ErrorInfo](https://cloud.google.com/apis/design/errors#error_info) with reason "EXPIRED_SYNC_TOKEN". In the case of such an error clients should make a full sync request without a `https://developers.google.com/people/api/rest/v1/people.connections/list#body.QUERY_PARAMETERS.sync_token`.

The first page of a full sync request has an additional quota. If the quota is exceeded, a 429 error will be returned. This quota is fixed and can not be increased.

When the `https://developers.google.com/people/api/rest/v1/people.connections/list#body.QUERY_PARAMETERS.sync_token` is specified, resources deleted since the last sync will be returned as a person with `https://developers.google.com/people/api/rest/v1/people#Person.PersonMetadata.FIELDS.deleted` set to true.

When the `https://developers.google.com/people/api/rest/v1/people.connections/list#body.QUERY_PARAMETERS.page_token` or `https://developers.google.com/people/api/rest/v1/people.connections/list#body.QUERY_PARAMETERS.sync_token` is specified, all other request parameters must match the first call.

Writes may have a propagation delay of several minutes for sync requests. Incremental syncs are not intended for read-after-write use cases.

See example usage at [List the user's contacts that have changed](https://developers.google.com/people/v1/contacts#list_the_users_contacts_that_have_changed).

### HTTP request

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

The URL uses [gRPC Transcoding](https://google.aip.dev/127) 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 response `https://developers.google.com/people/api/rest/v1/people.connections/list#body.ListConnectionsResponse.FIELDS.next_page_token`. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to `https://developers.google.com/people/api/rest/v1/people.connections/list#google.people.v1.PeopleService.ListConnections` must match the first 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 (`https://developers.google.com/people/api/rest/v1/people.connections/list#SortOrder`)`` Optional. The order in which the connections should be sorted. Defaults to `LAST_MODIFIED_ASCENDING`. |
| `requestSyncToken` | `boolean` Optional. Whether the response should return `https://developers.google.com/people/api/rest/v1/people.connections/list#body.ListConnectionsResponse.FIELDS.next_sync_token` on the last page of results. It can be used to get incremental changes since the last request by setting it on the request `https://developers.google.com/people/api/rest/v1/people.connections/list#body.QUERY_PARAMETERS.sync_token`. More details about sync behavior at `https://developers.google.com/people/api/rest/v1/people.connections/list#google.people.v1.PeopleService.ListConnections`. |
| `syncToken` | `string` Optional. A sync token, received from a previous response `https://developers.google.com/people/api/rest/v1/people.connections/list#body.ListConnectionsResponse.FIELDS.next_sync_token` Provide this to retrieve only the resources changed since the last request. When syncing, all other parameters provided to `https://developers.google.com/people/api/rest/v1/people.connections/list#google.people.v1.PeopleService.ListConnections` must match the first call that provided the sync token. More details about sync behavior at `https://developers.google.com/people/api/rest/v1/people.connections/list#google.people.v1.PeopleService.ListConnections`. |
| `requestMask (deprecated)` | ``object (`https://developers.google.com/people/api/rest/v1/RequestMask`)`` Optional. **DEPRECATED** (Please use `personFields` instead) A mask to restrict results to a subset of person fields. |
| `personFields` | ``string (`https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#google.protobuf.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 (`https://developers.google.com/people/api/rest/v1/ReadSourceType`)`` Optional. A mask of what source types to return. Defaults to `https://developers.google.com/people/api/rest/v1/ReadSourceType#ENUM_VALUES.READ_SOURCE_TYPE_CONTACT` and `https://developers.google.com/people/api/rest/v1/ReadSourceType#ENUM_VALUES.READ_SOURCE_TYPE_PROFILE` if not set. |

### Request body

The request body must be empty.

### Response body

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

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

| JSON representation |
|---|
| ``` { "connections": [ { object (`https://developers.google.com/people/api/rest/v1/people#Person`) } ], "nextPageToken": string, "nextSyncToken": string, "totalPeople": integer, "totalItems": integer } ``` |

| Fields ||
|---|---|
| `connections[]` | ``object (`https://developers.google.com/people/api/rest/v1/people#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` > [!WARNING] > This item is deprecated! **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](https://developers.google.com/workspace/guides/configure-oauth-consent).

## 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. |