Building a multi-provider contact picker or address-book sync means handling the Google People API, Microsoft Graph, EWS, hosted IMAP behavior, and CardDAV for iCloud and Yahoo. The field names, authentication, pagination, groups, and change models differ. The Nylas Contacts API collapses them into one endpoint and schema.
This page maps out what you can build, how provider behavior differs, and where to find a recipe for each Contact task.
What the Contacts API does
Section titled “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, phone, source, group, or indexed metadata. - 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/groupsto surface explicit provider-backed Contact Groups.
That’s 6 endpoints total. For the full field reference, see Manage contacts with the Contacts API.
Supported contact providers
Section titled “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.
| Grant type | Underlying API or model | Auth | Notes |
|---|---|---|---|
| People API | OAuth 2.0 scopes | Unified schema with Google source and polling behavior. | |
| Microsoft | Microsoft Graph | OAuth 2.0 scopes | Unified schema with Microsoft source, folder, and field limits. |
| Exchange (EWS) | EWS Contacts | Basic auth or OAuth | No group filter or inbox source. |
| Native iCloud | CardDAV | App-specific password | Full native address-book CRUD, explicit groups, and polled Contact events. |
| Native Yahoo | CardDAV | Native Yahoo bearer grant | Full native address-book CRUD and explicit groups; no Contact notifications. |
| Generic hosted IMAP | Hosted IMAP model | Username and app password | No native iCloud or Yahoo CardDAV support. |
Filter support varies by provider: the group filter isn’t available on Exchange (EWS), recurse is Microsoft-only, and phone_number filtering covers Google, hosted IMAP, native iCloud, native Yahoo, and EWS. Native iCloud and Yahoo don’t support profile-picture retrieval. Their address_book source uses CardDAV, while their separately gated inbox source stays read-only.
Contact metadata is Nylas-managed and works across all six grant types in the table. It belongs to Contact objects only, never Contact Groups, and is never written to provider records or vCard data.
How contacts differ between Google and Microsoft
Section titled “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 automatically 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.
- Automatically collected contacts. Google’s “other contacts” pool holds people you’ve emailed but never saved. Reaching it needs the
contacts.other.readonlyscope and maps to theinboxsource. Microsoft surfaces correspondents throughPeople.Read. - Email address limits. Microsoft Graph caps a contact at 3 email addresses and leaves the email
typeasnull, so don’t rely onworkorhomelabels for Outlook contacts. Google doesn’t impose the same cap. - Writable sources. Both providers let you create and update saved contacts. The automatically 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 guides, see List Google contacts and List Microsoft contacts.
How native iCloud and Yahoo CardDAV differ
Section titled “How native iCloud and Yahoo CardDAV differ”Native CardDAV Contact IDs start with carddav_v1_, and group IDs start with carddav_group_v1_. Both are opaque, derived from an href, and grant-bound. Ordinary updates keep an ID while the href remains stable. A provider-side move can change the ID, so persist the latest value.
Both providers expose explicit group vCard records through GET /contacts/groups and Contact groups. Address-book collections and combined views such as iCloud All Contacts don’t appear in the response, and the API doesn’t create, rename, or delete group resources. iCloud supports a filtered group query. Yahoo rejects it, so Nylas uses a bounded inventory and addressbook-multiget fallback.
iCloud can emit polled contact.updated and contact.deleted notifications after a silent initial baseline. Its feed is best effort and can contain duplicates. Yahoo emits no Contact notifications, including for API writes.
Contacts recipes
Section titled “Contacts recipes”Each recipe below covers one Contact task end to end.
- List Google contacts reads a Gmail or Google Workspace address book and covers People API scopes, groups, and the “other contacts” pool.
- List Microsoft contacts reads an Outlook or Microsoft 365 address book and covers Graph permissions, contact folders, and categories.
- List iCloud contacts covers native CardDAV CRUD, IDs, groups, metadata, pagination, and notifications.
- List Yahoo contacts covers native CardDAV CRUD, groups, field limits, and the notification limitation.
- Create and update contacts writes new contacts and edits existing ones with the unified schema across providers.
- Search contacts narrows an address book by email, name, or group so you return only the contacts a query needs.
- Recipient autocomplete powers a contact picker from the
inboxsource so suggestions include real correspondents, not just saved contacts. - Contact groups lists explicit groups, filters membership, and updates the Contact
groupsfield. - List and sync contacts explains provider-specific Contact notifications and reconciliation.
What’s next
Section titled “What’s next”- Contacts API reference for the endpoint definitions, query parameters, and response schemas.
- Connect user accounts with OAuth to authorize contact access before you read or write an address book.
- Get started with Nylas to set up an application and API key if you’re new to the platform.