Quickstart: Contacts API

The Nylas Contacts API gives you access to a user’s address book across Gmail, Outlook, Exchange, and iCloud — all through a single API. List contacts, look up people by email, and create new entries without building separate integrations for each provider.

This quickstart walks you through listing, searching, and creating contacts on behalf of a connected user.

Before you begin

You need two things from Nylas to make API calls:

1. An API key — authenticates your application. You’ll pass it as a Bearer token.
2. A grant ID — identifies which user’s contacts to access. You get one when you connect an account to Nylas.

If you don’t have these yet, follow one of the setup guides first:

• Get started with the CLI — run nylas init to create an account, generate an API key, and connect a test account in one command.
• Get started with the Dashboard — do the same steps through the web UI.

Then install the Nylas SDK for your language:

Node.jsPythonRuby

npm install nylas

pip install nylas

gem install nylas

For Java and Kotlin, see the Kotlin/Java SDK setup guide.

List a user’s contacts

Retrieve contacts from a user’s address book. Replace <NYLAS_GRANT_ID> and <NYLAS_API_KEY> with your values.

curlNode.jsPythonRubyJavaKotlin

curl --request GET \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/contacts?limit=10' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>'

import Nylas from "nylas";

const nylas = new Nylas({ apiKey: process.env.NYLAS_API_KEY });

const contacts = await nylas.contacts.list({
  identifier: process.env.NYLAS_GRANT_ID,
  queryParams: { limit: 10 },
});

contacts.data.forEach((contact) => {
  console.log(`${contact.givenName} ${contact.surname} -- ${contact.emails?.[0]?.email}`);
});

import os
from nylas import Client

nylas = Client(os.environ["NYLAS_API_KEY"])

contacts = nylas.contacts.list(
    os.environ["NYLAS_GRANT_ID"],
    query_params={"limit": 10},
)

for contact in contacts.data:
    email = contact.emails[0].email if contact.emails else "no email"
    print(f"{contact.given_name} {contact.surname} -- {email}")

require 'nylas'

nylas = Nylas::Client.new(api_key: ENV['NYLAS_API_KEY'])

contacts, _ = nylas.contacts.list(
  identifier: ENV['NYLAS_GRANT_ID'],
  query_params: { limit: 10 }
)

contacts.each do |contact|
  email = contact[:emails]&.first&.dig(:email) || 'no email'
  puts "#{contact[:given_name]} #{contact[:surname]} -- #{email}"
end

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

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

    ListContactsQueryParams queryParams = new ListContactsQueryParams.Builder().limit(10).build();
    ListResponse<Contact> contacts = nylas.contacts().list("<NYLAS_GRANT_ID>", queryParams);

    for (Contact contact : contacts.getData()) {
      System.out.println(contact.getGivenName() + " " + contact.getSurname());
    }
  }
}

import com.nylas.NylasClient
import com.nylas.models.*

fun main() {
    val nylas = NylasClient(apiKey = "<NYLAS_API_KEY>")

    val queryParams = ListContactsQueryParams(limit = 10)
    val contacts = nylas.contacts().list("<NYLAS_GRANT_ID>", queryParams).data

    for (contact in contacts) {
        println("${contact.givenName} ${contact.surname}")
    }
}

Search for a contact

Find contacts by email address. Useful for looking up a sender’s details before replying, or checking if a contact exists before creating one.

curlNode.jsPythonRubyJavaKotlin

curl --request GET \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/[email protected]' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>'

const results = await nylas.contacts.list({
  identifier: process.env.NYLAS_GRANT_ID,
  queryParams: { email: "[email protected]" },
});

console.log(`Found ${results.data.length} contacts`);

results = nylas.contacts.list(
    os.environ["NYLAS_GRANT_ID"],
    query_params={"email": "[email protected]"},
)

print(f"Found {len(results.data)} contacts")

results, _ = nylas.contacts.list(
  identifier: ENV['NYLAS_GRANT_ID'],
  query_params: { email: '[email protected]' }
)

puts "Found #{results.length} contacts"

ListContactsQueryParams searchParams = new ListContactsQueryParams.Builder()
    .email("[email protected]")
    .build();

ListResponse<Contact> results = nylas.contacts().list("<NYLAS_GRANT_ID>", searchParams);
System.out.println("Found " + results.getData().size() + " contacts");

val searchParams = ListContactsQueryParams(email = "[email protected]")
val results = nylas.contacts().list("<NYLAS_GRANT_ID>", searchParams).data

println("Found ${results.size} contacts")

Create a contact

Add a new contact to a user’s address book.

curlNode.jsPythonRubyJavaKotlin

curl --request POST \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/contacts' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "given_name": "Alice",
    "surname": "Smith",
    "company_name": "Acme Corp",
    "job_title": "Engineering Manager",
    "emails": [{ "email": "[email protected]", "type": "work" }],
    "phone_numbers": [{ "number": "+1-555-555-1234", "type": "work" }]
  }'

const contact = await nylas.contacts.create({
  identifier: process.env.NYLAS_GRANT_ID,
  requestBody: {
    givenName: "Alice",
    surname: "Smith",
    companyName: "Acme Corp",
    jobTitle: "Engineering Manager",
    emails: [{ email: "[email protected]", type: "work" }],
    phoneNumbers: [{ number: "+1-555-555-1234", type: "work" }],
  },
});

console.log("Created contact:", contact.data.id);

contact = nylas.contacts.create(
    os.environ["NYLAS_GRANT_ID"],
    request_body={
        "given_name": "Alice",
        "surname": "Smith",
        "company_name": "Acme Corp",
        "job_title": "Engineering Manager",
        "emails": [{"email": "[email protected]", "type": "work"}],
        "phone_numbers": [{"number": "+1-555-555-1234", "type": "work"}],
    },
)

print("Created contact:", contact.data.id)

contact, _ = nylas.contacts.create(
  identifier: ENV['NYLAS_GRANT_ID'],
  request_body: {
    given_name: 'Alice',
    surname: 'Smith',
    company_name: 'Acme Corp',
    job_title: 'Engineering Manager',
    emails: [{ email: '[email protected]', type: 'work' }],
    phone_numbers: [{ number: '+1-555-555-1234', type: 'work' }]
  }
)

puts "Created contact: #{contact[:id]}"

import com.nylas.NylasClient;
import com.nylas.models.*;
import java.util.List;

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

    CreateContactRequest requestBody = new CreateContactRequest.Builder()
        .givenName("Alice")
        .surname("Smith")
        .companyName("Acme Corp")
        .jobTitle("Engineering Manager")
        .emails(List.of(new ContactEmail("[email protected]", "work")))
        .phoneNumbers(List.of(new ContactPhoneNumber("+1-555-555-1234", "work")))
        .build();

    Response<Contact> contact = nylas.contacts().create("<NYLAS_GRANT_ID>", requestBody);
    System.out.println("Created contact: " + contact.getData().getId());
  }
}

import com.nylas.NylasClient
import com.nylas.models.*

fun main() {
    val nylas = NylasClient(apiKey = "<NYLAS_API_KEY>")

    val requestBody = CreateContactRequest(
        givenName = "Alice",
        surname = "Smith",
        companyName = "Acme Corp",
        jobTitle = "Engineering Manager",
        emails = listOf(ContactEmail("[email protected]", "work")),
        phoneNumbers = listOf(ContactPhoneNumber("+1-555-555-1234", "work"))
    )

    val contact = nylas.contacts().create("<NYLAS_GRANT_ID>", requestBody)
    println("Created contact: ${contact.data.id}")
}

What’s next

• Authentication — set up OAuth so your users can connect their accounts
• Email API quickstart — send and read email
• Webhooks — get notified when contacts are created or updated
• Contacts API reference — full endpoint documentation