# Organize contacts with groups

Source: https://developer.nylas.com/docs/cookbook/contacts/contact-groups/

A user's contacts are rarely a flat list. They've sorted people into groups: a "Team" group in Gmail, categories in Outlook, a "Clients" label. If your app shows or syncs contacts, respecting those groups makes the experience feel native instead of dumping every contact into one bucket.

The Nylas Contacts API exposes those groups and lets you scope a contact query to one of them, so you can build a group picker or sync a single segment without pulling the whole address book.

## How do I list a user's contact groups?

Send a `GET /v3/grants/{grant_id}/contacts/groups` request. Nylas returns each group with an `id` and a `name`, mapping the contact groups and categories from 2 providers (Gmail and Outlook) into one shape. You use the group `id` to filter contacts, so this call is the first step before scoping a query. It returns the same structure regardless of provider.

The request below lists the contact groups on an account.

```bash
curl --compressed --request GET \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/contacts/groups' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json'

```

## How do I filter contacts by group?

Add the `group` query parameter to a `GET /v3/grants/{grant_id}/contacts` request, set to the group `id` from the groups call. Nylas returns only the contacts in that group, which is how you sync or display one segment at a time. The `group` parameter is supported on 5 of the 6 providers, every one except Exchange (EWS).

The request below returns only the contacts in one group.

```bash
curl --request GET \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/contacts?group=<GROUP_ID>' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>'
```

## Things to know about contact groups

Provider differences shape what you get back. Gmail exposes user-created contact groups and system groups like "starred", while Outlook uses categories, and Nylas surfaces both through the same groups endpoint. Group filtering works on 5 of the 6 providers and is unavailable only on Exchange (EWS), so build a fallback for EWS accounts rather than assuming the `group` parameter always applies.

The groups endpoint is read-only here: you list groups and filter by them, but you manage group membership through each contact's own `groups` field. See [the Contacts API](/docs/v3/email/contacts/#organize-contacts-with-contact-groups) for membership details.

## What's next

- [List and sync contacts from Google and Outlook](/docs/cookbook/contacts/list-and-sync-contacts/) for the base contact list and filters
- [The Contacts API](/docs/v3/email/contacts/) for group membership and the full contact schema
- [Contacts API scopes](/docs/dev-guide/scopes/#contacts-api-scopes) for the scopes group access needs
- [Get real-time updates with webhooks](/docs/cookbook/use-cases/build/realtime-webhooks/) for contact.updated notifications