Only show these results:

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.

How the Contacts API works

When an end user authenticates with your Nylas application, the Nylas sync engine starts pulling all of the data it has access to for their account. After that, Nylas polls the end user's provider every five minutes. For more information about Nylas' sync process, see the Platform 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_OR_ACCESS_TOKEN>' \
--header 'Content-Type: application/json'
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_OR_ACCESS_TOKEN>' \
--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.

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/{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_OR_ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
"birthday": "1960-12-31",
"company_name": "Nylas",
"emails": [
{
"email": "[email protected]",
"type": "work"
},
{
"email": "[email protected]",
"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"
}
],
"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.

require 'nylas'	

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

request_body = {
given_name: "My",
middle_name: "Nylas",
surname: "Friend",
emails: [{email: "[email protected]", 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("[email protected]", "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("[email protected]", "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_OR_ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
"birthday": "1960-12-31",
"company_name": "Nylas",
"emails": [
{
"email": "[email protected]",
"type": "work"
},
{
"email": "[email protected]",
"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"
}
],
"suffix": "Jr.",
"surname": "Doe",
"web_pages": [
{
"type": "work",
"url": "http://www.linkedin.com/in/johndoe"
},
{
"type": "home",
"url": "http://www.johndoe.com"
}
]
}'
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_OR_ACCESS_TOKEN>' \
--header 'Content-Type: application/json'
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_OR_ACCESS_TOKEN>' \
--header 'Content-Type: application/json'
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.

Parsed versus synced contacts

Nylas creates two types of contacts: parsed and synced.

Parsed contacts are created from end users' email messages and are assigned the source: "inbox" value. Nylas excludes many values from JSON responses for parsed contacts, as in the example below.

{
"account_id": "<ACCOUNT_ID>",
"birthday": null,
"company_name": null,
"emails": [{
"email": "[email protected]",
"type": null
}],
"given_name": "Nylas",
"groups": [],
"id": "<CONTACT_ID>",
"im_addresses": [],
"job_title": null,
"manager_name": null,
"middle_name": null,
"nickname": null,
"notes": null,
"object": "contact",
"office_location": null,
"phone_numbers": [],
"physical_addresses": [],
"picture_url": null,
"source": "inbox",
"suffix": null,
"surname": "Tips",
"web_pages": []
}

Synced contacts are created from end users' address books and are assigned the source: "address_book" value. Nylas includes more information about synced contacts than parsed contacts in its JSON responses.

{
"account_id": "<ACCOUNT_ID>",
"birthday": "1930-01-19",
"company_name": "Prime Time Primates",
"emails": [{
"email": "[email protected]",
"type": "work"
}],
"given_name": "Tippi",
"groups": [{
"account_id": "<ACCOUNT_ID>",
"id": "<GROUP_ID>",
"name": "System Group: My Contacts",
"object": "contact_group",
"path": "System Group: My Contacts"
}],
"id": "<CONTACT_ID>",
"im_addresses": [],
"job_title": "Zoologist",
"manager_name": null,
"middle_name": null,
"nickname": null,
"notes": null,
"object": "contact",
"office_location": null,
"phone_numbers": [{
"number": "(218) 301-2284",
"type": "mobile"
}],
"physical_addresses": [{
"address": "Duluth, MN 55811\nUS",
"format": "unstructured",
"type": null
}],
"picture_url": "https://api.nylas.com/contacts/<CONTACT_ID>/picture",
"source": "address_book",
"suffix": null,
"surname": "Hedren",
"web_pages": []
}

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?