Skip to content
Nylas Docs

Using the Contacts API

The Nylas Contacts API provides a secure and reliable connection to your end users’ contacts. This enables you to perform bi-directional sync with full CRUD (Create, Read, Update, Delete) capabilities for Google and Microsoft accounts. The API provides a REST interface that allows you to do the following tasks:

  • Read contact information, including names, email addresses, phone numbers, and more.
  • Organize contacts using contact groups.

Contact sources

By default, Nylas only looks for contacts in the end user’s address book when you make a Get Contacts request. To fetch contacts from either the domain or the end user’s inbox, add the ?source=domain or ?source=inbox query parameter to your request.

To get contact information from an end user’s inbox, you must also have requested the following scopes:

  • Google: contacts.other.readonly
  • Microsoft: People.Read

For more information, see the Contacts scopes documentation.

Before you begin

To follow along with the samples on this page, you first need to sign up for a Nylas developer account, which gets you a free Nylas application and API key.

For a guided introduction, you can follow the Getting started guide to set up a Nylas account and Sandbox application. When you have those, you can connect an account from a calendar provider (such as Google, Microsoft, or iCloud) and use your API key with the sample API calls on this page to access that account’s data.

View all contacts

The simplest way to view information about your end users’ contacts is to make a Get Contacts request. By default, the endpoint returns 30 results. For the purpose of this guide, queries use the limit parameter to return a maximum of five contacts. For more information about limits and offsets, see the pagination reference documentation.

The following examples show how to use the Contacts API and the Nylas SDKs to view contact information.

Terminal window
!!!include(v3_code_samples/contacts/GET/curl.sh)!!!
!!!include(v3_code_samples/contacts/GET/node.js)!!!
!!!include(v3_code_samples/contacts/GET/ruby.rb)!!!
!!!include(v3_code_samples/contacts/GET/java.java)!!!
!!!include(v3_code_samples/contacts/GET/kotlin.kt)!!!

View a contact

To get information about a specific contact, make a Get Contact request with the contact’s ID, as in the example below.

Terminal window
!!!include(v3_code_samples/contacts-id/GET/curl.sh)!!!

To learn more about the information a Contact object contains, see the Contacts reference documentation.

You can also use the Nylas SDKs to return information about a specific contact, as in the examples below.

!!!include(v3_code_samples/contacts-id/GET/node.js)!!!
!!!include(v3_code_samples/contacts-id/GET/python.py)!!!
!!!include(v3_code_samples/contacts-id/GET/ruby.rb)!!!
!!!include(v3_code_samples/contacts-id/GET/java.java)!!!
!!!include(v3_code_samples/contacts-id/GET/kotlin.kt)!!!

Download contact profile images

Many service providers allow end users to assign a photo to a contact’s profile. You can access contact profile images in Nylas v3 by including the ?profile_picture=true query parameter in a Get Contact request.

Nylas returns a Base64-encoded data blob that represents the profile image. To save or display the image, you must redirect the response to an appropriate file.

Create a contact

To create a contact, make a POST /v3/grants/<NYLAS_GRANT_ID>/contacts request. Include the contact’s profile information, as in the following example.

Terminal window
!!!include(v3_code_samples/contacts/POST/curl.sh)!!!

You can also use the Nylas SDKs to create contacts, as in the examples below.

!!!include(v3_code_samples/contacts/POST/node.js)!!!
!!!include(v3_code_samples/contacts/POST/python.py)!!!
!!!include(v3_code_samples/contacts/POST/ruby.rb)!!!
!!!include(v3_code_samples/contacts/POST/java.java)!!!
!!!include(v3_code_samples/contacts/POST/kotlin.kt)!!!

Modify a contact

When you create a contact, Nylas responds with an id that represents the contact record, along with other information about the contact. You can use this id to modify a specific contact, as in the examples below.

Terminal window
!!!include(v3_code_samples/contacts-id/PUT/curl.sh)!!!
!!!include(v3_code_samples/contacts-id/PUT/node.js)!!!
!!!include(v3_code_samples/contacts-id/PUT/python.py)!!!
!!!include(v3_code_samples/contacts-id/PUT/ruby.rb)!!!
!!!include(v3_code_samples/contacts-id/PUT/java.java)!!!
!!!include(v3_code_samples/contacts-id/PUT/kotlin.kt)!!!

For more information, see the Update Contact reference documentation.

Delete a contact

To delete a contact, make a Delete Contact request with the contact’s id, or use the Nylas SDKs.

Terminal window
!!!include(v3_code_samples/contacts-id/DELETE/curl.sh)!!!
!!!include(v3_code_samples/contacts-id/DELETE/node.js)!!!
!!!include(v3_code_samples/contacts-id/DELETE/python.py)!!!
!!!include(v3_code_samples/contacts-id/DELETE/ruby.rb)!!!
!!!include(v3_code_samples/contacts-id/DELETE/java.java)!!!
!!!include(v3_code_samples/contacts-id/DELETE/kotlin.kt)!!!

Organize contacts with contact groups

Contact groups allow your end users to organize their contacts. You can get a full list of an end user’s contact groups by making a Get Contact Groups request, or by using the Nylas SDKs.

Terminal window
!!!include(v3_code_samples/contacts-groups/GET/curl.sh)!!!
!!!include(v3_code_samples/contacts-groups/GET/node.js)!!!
!!!include(v3_code_samples/contacts-groups/GET/python.py)!!!
!!!include(v3_code_samples/contacts-groups/GET/ruby.rb)!!!
!!!include(v3_code_samples/contacts-groups/GET/java.java)!!!
!!!include(v3_code_samples/contacts-groups/GET/kotlin.kt)!!!

Limitations of the Contacts API

The following sections describe some limitations you should keep in mind when working with the Nylas Contacts API.

Microsoft Exchange limitations

Because of the way the Microsoft Exchange protocol works, Nylas applies the following limitations to Exchange contacts:

  • Phone numbers must have a non-null type. Exchange does not accept phone numbers of the other type.
  • Contacts can have a maximum of two home and business phone numbers.
    • Labels such as business are not supported.
  • Contacts can have a maximum of three email addresses.
    • Email addresses must have their type set to null by default. You can manually change them to be personal or work.
  • Contacts can have a maximum of three instant messenger (IM) addresses.
    • IM addresses have their type set to null by default.
  • Exchange contacts support only the work, home, and other labels for the postal_address.
  • Exchange contacts don’t support the other, other fax, callback, telex, and tty/tdd phone types.

Google limitations

Nylas applies the following limitations to Google contacts:

  • Google contacts don’t support the Google Voice phone type, or custom phone types.

Historical sync for Google contacts

Nylas syncs a maximum of 100,000 contacts when an end user authenticates or re-authenticates their Google account. There is no limit to the number of contacts that Nylas syncs, as long as the account remains connected to your Nylas application.

Polling interval for Google contacts

Google doesn’t have a modern push notification API to enable real-time notifications of changes to contacts. Because of this, Nylas polls for changes every 60 seconds.

What’s next?

Now that you know how to work with the Nylas Contacts API, you can read the following blog posts to dive deeper: