Version:
Only show these results:

Using the Contacts API

💡 Looking for the Contacts API references? You can find them here!

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

🔍 There are three contacts sources: the end user's address book (address_book), their organization's domain (domain, for example, a Microsoft Active Directory contact list), and the participants from email messages in their inbox (inbox).

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.

curl --request GET \
  --url https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/contacts \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json'   
import 'dotenv/config'
import Nylas from 'nylas'

const NylasConfig = {
  apiKey: process.env.NYLAS_API_KEY,
  apiUri: process.env.NYLAS_API_URI,
}

const nylas = new Nylas(NylasConfig)

async function fetchContacts() {
  try {
    const identifier = process.env.NYLAS_GRANT_ID
    const contacts = await nylas.contacts.list({
      identifier,
      queryParams: {}, 
    })

    console.log('Recent Contacts:', contacts)
  } catch (error) {
    console.error('Error fetching drafts:', error)
  }
}

fetchContacts()   
require 'nylas'	

nylas = Nylas::Client.new(api_key: "<NYLAS_API_KEY>")
contacts, _ = nylas.contacts.list(identifier: ENV["NYLAS_GRANT_ID"])

contacts.each {|contact|
  puts "Name: #{contact[:given_name]} #{contact[:surname]} | " \
      "Email: #{contact[:emails][0][:email]} | ID: #{contact[:id]}"
}   
import com.nylas.NylasClient;
import com.nylas.models.*;

public class ReadAllContacts {
  public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
    NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
    ListResponse<Contact> contacts = nylas.contacts().list("<NYLAS_GRANT_ID>");

    for(Contact contact : contacts.getData()) {
      System.out.println(contact);
      System.out.println("\n");
    }
  }
}   
import com.nylas.NylasClient

fun main(args: Array<String>) {
  val nylas: NylasClient = NylasClient(apiKey = "<NYLAS_API_KEY>")
  val contacts = nylas.contacts().list("<NYLAS_GRANT_ID>")

  for(contact in contacts.data){
    println(contact)
  }
}

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.

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

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.

import 'dotenv/config'
import Nylas from 'nylas'

const NylasConfig = {
 apiKey: process.env.NYLAS_API_KEY,
 apiUri: process.env.NYLAS_API_URI,
}

const nylas = new Nylas(NylasConfig)

async function fetchContactById() { 
  try {
    const contact = await nylas.contacts.find({
      identifier: process.env.NYLAS_GRANT_ID,
      contactId: process.env.CONTACT_ID,
      queryParams: {},
    })
  
    console.log('contact:', contact)
  } catch (error) {
    console.error('Error fetching contact:', error)
  }
}

fetchContactById()   
from dotenv import load_dotenv
load_dotenv()

import os
import sys
from nylas import Client

nylas = Client(
    os.environ.get('NYLAS_API_KEY'),
    os.environ.get('NYLAS_API_URI')
)

grant_id = os.environ.get("NYLAS_GRANT_ID")
contact_id = os.environ.get("CONTACT_ID")

contact = nylas.contacts.find(
  grant_id,
  contact_id,
)

print(contact)   
require 'nylas'	

nylas = Nylas::Client.new(api_key: "<NYLAS_API_KEY>")
contact, _ = nylas.contacts.find(identifier: "<NYLAS_GRANT_ID>", contact_id: "<CONTACT_ID>")

puts contact   
import com.nylas.NylasClient;
import com.nylas.models.*;

public class ReturnAContact {
  public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
    NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
    Response<Contact> contact = nylas.contacts().find("<NYLAS_GRANT_ID>", "<CONTACT_ID>");

    System.out.println(contact);
  }
}   
import com.nylas.NylasClient

fun main(args: Array<String>) {
  val nylas: NylasClient = NylasClient(apiKey = "<NYLAS_API_KEY>")
  var contact = nylas.contacts().find("<NYLAS_GRANT_ID>", "<CONTACT_ID>")

  print(contact)
}

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.

curl --request POST \
  --url https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/contacts \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
  "birthday": "1960-12-31",
  "company_name": "Nylas",
  "emails": [
    {
      "email": "john-work@example.com",
      "type": "work"
    },
    {
      "email": "john-home@example.com",
      "type": "home"
    }
  ],
  "given_name": "John",
  "groups": [
    {
      "id": "starred"
    },
    {
      "id": "all"
    }
  ],
  "im_addresses": [
    {
      "type": "jabber",
      "im_address": "myjabberaddress"
    },
    {
      "type": "msn",
      "im_address": "mymsnaddress"
    }
  ],
  "job_title": "Software Engineer",
  "manager_name": "Bill",
  "middle_name": "Jacob",
  "nickname": "JD",
  "notes": "Loves Ramen",
  "office_location": "123 Main Street",
  "phone_numbers": [
    {
      "number": "+1-555-555-5555",
      "type": "work"
    },
    {
      "number": "+1-555-555-5556",
      "type": "home"
    }
  ],
  "physical_addresses": [
    {
      "type": "work",
      "street_address": "123 Main Street",
      "postal_code": "94107",
      "state": "CA",
      "country": "USA",
      "city": "San Francisco"
    },
    {
      "type": "home",
      "street_address": "456 Main Street",
      "postal_code": "94107",
      "state": "CA",
      "country": "USA",
      "city": "San Francisco"
    }
  ],
  "source": "address_book",
  "suffix": "Jr.",
  "surname": "Doe",
  "web_pages": [
    {
      "type": "work",
      "url": "http://www.linkedin.com/in/johndoe"
    },
    {
      "type": "home",
      "url": "http://www.johndoe.com"
    }
  ]
}'

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

import 'dotenv/config'
import Nylas from 'nylas'

const NylasConfig = {
 apiKey: process.env.NYLAS_API_KEY,
 apiUri: process.env.NYLAS_API_URI,
}

const nylas = new Nylas(NylasConfig)

async function createContact() {
  try {
    const contact = await nylas.contacts.create({
      identifier: process.env.NYLAS_GRANT_ID,
      requestBody: {
        givenName: "My",
        middleName: "Nylas",
        surname: "Friend",
        notes: "Make sure to keep in touch!",
        emails: [{type: 'work', email: 'swag@example.com'}],
        phoneNumbers: [{type: 'work', number: '(555) 555-5555'}],
        webPages: [{type: 'other', url: 'nylas.com'}]
      }
    })

    console.log('Contact:', JSON.stringify(contact))
  } catch (error) {
    console.error('Error to create contact:', error)
  }
}

createContact()   
from dotenv import load_dotenv
load_dotenv()

import os
import sys
from nylas import Client

nylas = Client(
    os.environ.get('NYLAS_API_KEY'),
    os.environ.get('NYLAS_API_URI')
)

grant_id = os.environ.get("NYLAS_GRANT_ID")

contact = nylas.contacts.create(
  grant_id,
  request_body={
    "middleName": "Nylas",
    "surname": "Friend",
    "notes": "Make sure to keep in touch!",
    "emails": [{"type": "work", "email": "swag@example.com"}],
    "phoneNumbers": [{"type": "work", "number": "(555) 555-5555"}],
    "webPages": [{"type": "other", "url": "nylas.com"}]
  }
)

print(contact)   
require 'nylas'	

nylas = Nylas::Client.new(api_key: "<NYLAS_API_KEY>")

request_body = {
  given_name: "My",
  middle_name: "Nylas",
  surname: "Friend",  
  emails: [{email: "nylas-friend@example.com", type: "work"}],
  notes: "Make sure to keep in touch!",
  phone_numbers: [{number: "555 555-5555", type: "business"}],
  web_pages: [{url: "https://www.nylas.com", type: "homepage"}]
}

contact, _ = nylas.contacts.create(identifier: "<NYLAS_GRANT_ID>", request_body: request_body)

puts contact   
import com.nylas.NylasClient;
import com.nylas.models.*;
import java.util.ArrayList;
import java.util.List;

public class CreateAContact {
    public static void main(String[] args) throws
            NylasSdkTimeoutError, NylasApiError {

        NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();

        List<ContactEmail> contactEmails = new ArrayList<>();
        contactEmails.add(new ContactEmail("swag@nylas.com", "work"));

        List<WebPage> contactWebpages = new ArrayList<>();
        contactWebpages.add(new WebPage("https://www.nylas.com", "work"));

        CreateContactRequest requestBody = new CreateContactRequest.Builder().
                emails(contactEmails).
                companyName("Nylas").
                givenName("Nylas' Swag").
                notes("This is good swag").
                webPages(contactWebpages).
                build();

        Response<Contact> contact = nylas.contacts().create("<NYLAS_GRANT_ID>", requestBody);

        System.out.println(contact);
    }
}   
import com.nylas.NylasClient
import com.nylas.models.ContactEmail
import com.nylas.models.ContactType
import com.nylas.models.CreateContactRequest
import com.nylas.models.WebPage

fun main(args: Array<String>) {
  val nylas: NylasClient = NylasClient(apiKey = "<NYLAS_API_KEY>")
  val emails : List<ContactEmail> = listOf(ContactEmail("swag@nylas.com", "work"))
  val webpage : List<WebPage> = listOf(WebPage("https://www.nylas.com", "work"))

  val contactRequest = CreateContactRequest.Builder().
      emails(emails).
      companyName("Nylas").
      givenName("Nylas' Swag").
      notes("This is good swag").
      webPages(webpage).
      build()

  val contact = nylas.contacts().create("<NYLAS_GRANT_ID>", contactRequest)

  print(contact.data)
}

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.

curl --request PUT \
  --url https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/contacts/<CONTACT_ID> \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
  "birthday": "1960-12-31",
  "company_name": "Nylas",
  "emails": [
    {
      "email": "john-work@example.com",
      "type": "work"
    },
    {
      "email": "john-home@example.com",
      "type": "home"
    }
  ],
  "given_name": "John",
  "groups": [
    {
      "id": "starred"
    },
    {
      "id": "all"
    }
  ],
  "im_addresses": [
    {
      "type": "jabber",
      "im_address": "myjabberaddress"
    },
    {
      "type": "msn",
      "im_address": "mymsnaddress"
    }
  ],
  "job_title": "Software Engineer",
  "manager_name": "Bill",
  "middle_name": "Jacob",
  "nickname": "JD",
  "notes": "Loves Ramen",
  "office_location": "123 Main Street",
  "phone_numbers": [
    {
      "number": "+1-555-555-5555",
      "type": "work"
    },
    {
      "number": "+1-555-555-5556",
      "type": "home"
    }
  ],
  "physical_addresses": [
    {
      "type": "work",
      "street_address": "123 Main Street",
      "postal_code": "94107",
      "state": "CA",
      "country": "USA",
      "city": "San Francisco"
    },
    {
      "type": "home",
      "street_address": "456 Main Street",
      "postal_code": "94107",
      "state": "CA",
      "country": "USA",
      "city": "San Francisco"
    }
  ],
  "source": "address_book",
  "suffix": "Jr.",
  "surname": "Doe",
  "web_pages": [
    {
      "type": "work",
      "url": "http://www.linkedin.com/in/johndoe"
    },
    {
      "type": "home",
      "url": "http://www.johndoe.com"
    }
  ]
}'   
import 'dotenv/config'
import Nylas from 'nylas'

const NylasConfig = {
 apiKey: process.env.NYLAS_API_KEY,
 apiUri: process.env.NYLAS_API_URI,
}

const nylas = new Nylas(NylasConfig)

async function updateContact() {
  try {
    const contact = await nylas.contacts.update({
      identifier: process.env.NYLAS_GRANT_ID,
      contactId: process.env.CONTACT_ID,
      requestBody: {
        givenName: "Nyla",
      }
    })

    console.log('Contact:', JSON.stringify(contact))
  } catch (error) {
    console.error('Error to create contact:', error)
  }
}

updateContact()   
from dotenv import load_dotenv
load_dotenv()

import os
import sys
from nylas import Client

nylas = Client(
    os.environ.get('NYLAS_API_KEY'),
    os.environ.get('NYLAS_API_URI')
)

grant_id = os.environ.get("NYLAS_GRANT_ID")
contact_id = os.environ.get("CONTACT_ID")

contact = nylas.contacts.update(
  grant_id,
  contact_id,
  request_body={
    "given_name": "Nyla",
  }
)

print(contact)   
require 'nylas'	

nylas = Nylas::Client.new(api_key: "<NYLAS_API_KEY>")

request_body = {
  notes: "This is *the best* swag",
}

contact, _ = nylas.contacts.update(identifier: "<NYLAS_GRANT_ID>", 
    contact_id: "<CONTACT_ID>", 
    request_body: request_body)

puts contact   
import com.nylas.NylasClient;
import com.nylas.models.*;

public class UpdateContact {
  public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
    NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();

    UpdateContactRequest requestBody = new UpdateContactRequest.
        Builder().
        notes("This is *the best* swag").
        build();

    Response<Contact> contact = nylas.contacts().update("<NYLAS_GRANT_ID>", "<CONTACT_ID>", requestBody);

    System.out.println(contact);
  }
}   
import com.nylas.NylasClient
import com.nylas.models.*

fun main(args: Array<String>) {
  val nylas: NylasClient = NylasClient(apiKey = "<NYLAS_API_KEY>")

  val updateRequest = UpdateContactRequest.Builder().
      notes("This is *the best* swag").
      build()

  val contact = nylas.contacts().update("<NYLAS_GRANT_ID>", "<CONTACT_ID>", updateRequest)

  print(contact.data)
}

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.

curl --request DELETE \
  --url https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/contacts/<CONTACT_ID> \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json'   
import 'dotenv/config'
import Nylas from 'nylas'

const NylasConfig = {
  apiKey: process.env.NYLAS_API_KEY,
  apiUri: process.env.NYLAS_API_URI,
}

const nylas = new Nylas(NylasConfig)
const identifier = process.env.NYLAS_GRANT_ID
const contactId = process.env.CONTACT_ID

const deleteContact = async () => {
  try {
    await nylas.contacts.destroy({ identifier, contactId })
    console.log(`Contact with ID ${contactId} deleted successfully.`)
  } catch (error) {
    console.error(`Error deleting contact with ID ${contactId}:`, error)
  }
}

deleteContact()   
from dotenv import load_dotenv
load_dotenv()

import os
import sys
from nylas import Client

nylas = Client(
    os.environ.get('NYLAS_API_KEY'),
    os.environ.get('NYLAS_API_URI')
)

grant_id = os.environ.get("NYLAS_GRANT_ID")
contact_id = os.environ.get("CONTACT_ID")

request = nylas.contacts.destroy(
  grant_id,
  contact_id,
)

print(request)   
require 'nylas'	

nylas = Nylas::Client.new(api_key: "<NYLAS_API_KEY>")
status, _ = nylas.contacts.destroy(identifier: "<NYLAS_GRANT_ID>", contact_id: "<CONTACT_ID>")

puts status   
import com.nylas.NylasClient;
import com.nylas.models.*;

public class DeleteAContact {
  public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
    NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
    DeleteResponse contact = nylas.contacts().destroy("<NYLAS_GRANT_ID>", "<CONTACT_ID>");

    System.out.println(contact);
  }
}   
import com.nylas.NylasClient
import io.github.cdimascio.dotenv.dotenv

fun main(args: Array<String>) {
  val dotenv = dotenv()
  val nylas: NylasClient = NylasClient(apiKey = dotenv["NYLAS_API_KEY"])
  var contact = nylas.contacts().destroy(dotenv["NYLAS_GRANT_ID"], "c5895840358462569130")

  print(contact)
}

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.

curl --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'   
import 'dotenv/config'
import Nylas from 'nylas'

const NylasConfig = {
  apiKey: process.env.NYLAS_API_KEY,
  apiUri: process.env.NYLAS_API_URI,
}

const nylas = new Nylas(NylasConfig)

async function fetchContactGroups() {
  try {
    const identifier = process.env.NYLAS_GRANT_ID
    const contactGroups = await nylas.contacts.groups({
      identifier,
    })

    console.log('Contacts Groups:', contactGroups)
  } catch (error) {
    console.error('Error fetching contact groups:', error)
  }
}

fetchContactGroups()   
from dotenv import load_dotenv
load_dotenv()

import os
import sys
from nylas import Client

nylas = Client(
    os.environ.get('NYLAS_API_KEY'),
    os.environ.get('NYLAS_API_URI')
)

grant_id = os.environ.get("NYLAS_GRANT_ID")

contact_groups = nylas.contacts.list_groups(
  grant_id,
)

print(contact_groups)   
require 'nylas'	

nylas = Nylas::Client.new(api_key: "<NYLAS_API_KEY>")
groups = nylas.contacts.list_groups(identifier: "<NYLAS_GRANT_ID>")

puts groups   
import com.nylas.NylasClient;
import com.nylas.models.*;

public class ReadContactGroups {
  public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
    NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
    ListResponse<ContactGroup> groups = nylas.contacts().listGroups("<NYLAS_GRANT_ID>");
    
    System.out.println(groups);
  }
}   
import com.nylas.NylasClient
import io.github.cdimascio.dotenv.dotenv

fun main(args: Array<String>) {
  val dotenv = dotenv()

  val nylas: NylasClient = NylasClient(apiKey = dotenv["NYLAS_API_KEY"])
  var groups = nylas.contacts().listGroups(dotenv["NYLAS_GRANT_ID"])

  print(groups)
}

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: