# Quickstart: Contacts API

Source: https://developer.nylas.com/docs/v3/getting-started/contacts/

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](/docs/v3/getting-started/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](/docs/v3/getting-started/dashboard/)** -- do the same steps through the web UI.

Then install the Nylas SDK for your language:

```bash [installSdk-Node.js]
npm install nylas
```

```bash
pip install nylas
```

```bash
gem install nylas
```

For Java and Kotlin, see the [Kotlin/Java SDK setup guide](/docs/v3/sdks/kotlin-java/).

## List a user's contacts

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

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

```js [listContacts-Node.js]


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}`);
});
```

```python
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}")
```

```ruby
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
```

```java
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());
    }
  }
}
```

```kt
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}")
    }
}
```

```bash
nylas contacts list --limit 10
```

## 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.

```bash
curl --request GET \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/contacts?email=alice@example.com' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>'
```

```js [searchContacts-Node.js]
const results = await nylas.contacts.list({
  identifier: process.env.NYLAS_GRANT_ID,
  queryParams: { email: "alice@example.com" },
});

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

```python
results = nylas.contacts.list(
    os.environ["NYLAS_GRANT_ID"],
    query_params={"email": "alice@example.com"},
)

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

```ruby
results, _ = nylas.contacts.list(
  identifier: ENV['NYLAS_GRANT_ID'],
  query_params: { email: 'alice@example.com' }
)

puts "Found #{results.length} contacts"
```

```java
ListContactsQueryParams searchParams = new ListContactsQueryParams.Builder()
    .email("alice@example.com")
    .build();

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

```kt
val searchParams = ListContactsQueryParams(email = "alice@example.com")
val results = nylas.contacts().list("<NYLAS_GRANT_ID>", searchParams).data

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

```bash
nylas contacts search --email alice@example.com
```

## Create a contact

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

```bash
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": "alice@example.com", "type": "work" }],
    "phone_numbers": [{ "number": "+1-555-555-1234", "type": "work" }]
  }'
```

```js [createContact-Node.js]
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: "alice@example.com", type: "work" }],
    phoneNumbers: [{ number: "+1-555-555-1234", type: "work" }],
  },
});

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

```python
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": "alice@example.com", "type": "work"}],
        "phone_numbers": [{"number": "+1-555-555-1234", "type": "work"}],
    },
)

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

```ruby
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: 'alice@example.com', type: 'work' }],
    phone_numbers: [{ number: '+1-555-555-1234', type: 'work' }]
  }
)

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

```java
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("alice@example.com", "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());
  }
}
```

```kt
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("alice@example.com", "work")),
        phoneNumbers = listOf(ContactPhoneNumber("+1-555-555-1234", "work"))
    )

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

```bash
nylas contacts create \
  --first-name "Alice" \
  --last-name "Smith" \
  --email alice@example.com \
  --phone "+1-555-555-1234" \
  --company "Acme Corp" \
  --job-title "Engineering Manager"
```

## What's next

- **[Authentication](/docs/v3/auth/)** -- set up OAuth so your users can connect their accounts
- **[Email API quickstart](/docs/v3/getting-started/email/)** -- send and read email
- **[Webhooks](/docs/v3/notifications/)** -- get notified when contacts are created or updated
- **[Contacts API reference](/docs/reference/api/contacts/list-contact/)** -- full endpoint documentation