# Nylas Contacts API guide

Source: https://developer.nylas.com/docs/cookbook/contacts/contacts-api-guide/

Building a contact picker or an address-book sync usually means wiring up two separate integrations: Google's People API with `people.connections.list` and its own OAuth scopes, and Microsoft Graph with `GET /me/contacts` and a different permission model. The field names don't line up, the paging differs, and neither one reads the other's data. The Nylas Contacts API collapses both into a single endpoint with one schema, so the code you write for a Gmail address book also reads an Outlook one without a provider branch.

This page maps out what you can build, which providers are covered, where Google and Microsoft diverge, and links to a recipe for every contact task.

## What the Contacts API does

The Contacts API gives you a single REST interface over a user's address book across every provider Nylas connects, returning one contact object whether the account is Google, Microsoft, iCloud, Yahoo, IMAP, or Exchange. Each contact carries the same fields (`emails`, `phone_numbers`, `job_title`, `company_name`, `groups`, and more), so one parser handles every account type you connect.

The core operations cover the full lifecycle of a contact:

- **List** contacts with `GET /v3/grants/{grant_id}/contacts`, filtered by email, source, or group.
- **Get** a single contact with `GET /v3/grants/{grant_id}/contacts/{contact_id}`.
- **Create** a contact with `POST /v3/grants/{grant_id}/contacts`.
- **Update** a contact with `PUT /v3/grants/{grant_id}/contacts/{contact_id}`.
- **Delete** a contact with `DELETE /v3/grants/{grant_id}/contacts/{contact_id}`.
- **List groups** with `GET /v3/grants/{grant_id}/contacts/groups` to surface a user's Gmail groups or Outlook categories.

That's 6 endpoints total. For the full field reference, see [Manage contacts with the Contacts API](/docs/v3/email/contacts/).

## Supported contact providers

The Contacts API spans the same providers Nylas connects for email: Google, Microsoft, iCloud, Yahoo, IMAP, and Exchange (EWS). Each one stores contacts behind a different native protocol with its own auth model, and **the API normalizes all of them into one contact object and one set of endpoints** so your integration doesn't change when a user signs in with a different account.

The table maps each provider to what sits underneath the unified call.

| Provider          | Underlying API      | Auth                   | Notes                                                          |
| ----------------- | ------------------- | ---------------------- | ------------------------------------------------------------- |
| Google            | People API          | OAuth 2.0 scopes       | **Returned through the unified Nylas contact schema**         |
| Microsoft         | Microsoft Graph     | OAuth 2.0 scopes       | **Returned through the same unified contact schema**          |
| Exchange (EWS)    | EWS contacts        | Basic or OAuth         | **Same schema, with a few field and group limits**            |
| iCloud, Yahoo, IMAP | CardDAV / IMAP    | App password or OAuth  | **Same schema; some filters are provider-specific**           |

Filter support varies by provider: the `group` filter isn't available on Exchange (EWS), `recurse` is Microsoft-only, and `phone_number` filtering covers Google, IMAP, iCloud, Yahoo, and EWS. The unified schema is the same everywhere, but Google and Microsoft offer the richest group and profile-photo support, so lean on them when those features matter.

## How contacts differ between Google and Microsoft

The two providers organize contacts in genuinely different ways, and a few of those differences leak through the unified schema. Google groups contacts with labels and auto-collects everyone you've emailed into an "other contacts" pool, while Microsoft uses contact folders plus categories. Across both, Nylas reads from 3 contact sources: `address_book`, `domain`, and `inbox`.

Here are the concrete differences worth planning for:

- **Grouping model.** Google exposes user-created contact groups and system groups like "starred". Microsoft uses categories on contacts and organizes them into contact folders. Both surface through the same [groups endpoint](/docs/cookbook/contacts/contact-groups/).
- **Auto-collected contacts.** Google's "other contacts" pool holds people you've emailed but never saved. Reaching it needs the `contacts.other.readonly` scope and maps to the `inbox` source. Microsoft surfaces correspondents through `People.Read`.
- **Email address limits.** Microsoft Graph caps a contact at 3 email addresses and leaves the email `type` as `null`, so don't rely on `work` or `home` labels for Outlook contacts. Google doesn't impose the same cap.
- **Writable sources.** Both providers let you create and update saved contacts. The auto-collected and directory sources are read-only on both.
- **Sync timing.** Google has no push API for contacts, so Nylas polls every 5 minutes. Microsoft delivers changes faster.

For the provider-specific walkthroughs, see [List Google contacts](/docs/cookbook/contacts/list-contacts-google/) and [List Microsoft contacts](/docs/cookbook/contacts/list-contacts-microsoft/).

## Contacts recipes

Each recipe below covers one contact task end to end. Together they span all 7 of the section's how-to guides, from reading an address book to keeping it in sync.

- [List Google contacts](/docs/cookbook/contacts/list-contacts-google/) reads a Gmail or Google Workspace address book and covers People API scopes, groups, and the "other contacts" pool.
- [List Microsoft contacts](/docs/cookbook/contacts/list-contacts-microsoft/) reads an Outlook or Microsoft 365 address book and covers Graph permissions, contact folders, and categories.
- [Create and update contacts](/docs/cookbook/contacts/create-and-update-contacts/) writes new contacts and edits existing ones with the unified schema across providers.
- [Search contacts](/docs/cookbook/contacts/search-contacts/) narrows an address book by email, name, or group so you return only the contacts a query needs.
- [Recipient autocomplete](/docs/cookbook/contacts/recipient-autocomplete/) powers a contact picker from the `inbox` source so suggestions include real correspondents, not just saved contacts.
- [Contact groups](/docs/cookbook/contacts/contact-groups/) lists a user's Gmail groups or Outlook categories and scopes a contact query to one group.
- [List and sync contacts](/docs/cookbook/contacts/list-and-sync-contacts/) fetches contacts from Google and Outlook in one call and keeps them current with `contact.updated` and `contact.deleted` webhooks.

## What's next

- [Contacts API reference](/docs/reference/api/) for the endpoint definitions, query parameters, and response schemas.
- [Connect user accounts with OAuth](/docs/v3/auth/) to authorize contact access before you read or write an address book.
- [Get started with Nylas](/docs/v3/getting-started/) to set up an application and API key if you're new to the platform.