# Using the Contacts API

Source: https://developer.nylas.com/docs/v3/email/contacts/

> **Success:** 
> **Looking for the Contacts API references?** [You can find them here](/docs/reference/api/contacts/)!

The Nylas Contacts API provides a secure and reliable connection to your users' contacts. This enables you to perform bi-directional sync with full CRUD (Create, Read, Update, Delete) capabilities for users' accounts. The API provides a REST interface that lets you...

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

## Contact sources

> **Info:** 
> **Nylas recognizes three sources for contacts**: the user's address book (`address_book`), their organization's domain (`domain`), and the participants from messages in their inbox (`inbox`).

By default, Nylas only fetches contacts in a user's address book when you make a [Get all Contacts request](/docs/reference/api/contacts/list-contact/). To fetch contacts from either the domain or the user's inbox, add the `source` query parameter to your request and set it to either `domain` or `inbox`.

To get contact information from a user's inbox, you need the following [scopes](/docs/dev-guide/scopes/#contacts-api-scopes):

- **Google**: `contacts.other.readonly`
- **Microsoft**: `People.Read`

## Before you begin


To follow along with the samples on this page, you first need to [sign up for a Nylas developer account](https://dashboard-v3.nylas.com/register?utm_source=docs&utm_medium=devrel-surfaces&utm_campaign=&utm_content=using-apis), which gets you a free Nylas application and API key.

For a guided introduction, you can follow the [Getting started guide](/docs/v3/getting-started/) 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.


## Return all contacts

To get a list of your user's contacts, make a [Get all Contacts request](/docs/reference/api/contacts/list-contact/). By default, Nylas returns up to 30 results. The examples below use the `limit` parameter to set the maximum number of objects to 5. For more information about limits and offsets, see the [pagination references](#pagination).

```bash
curl --compressed --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'

```

```json [group_1-Response (JSON)]

{
  "request_id": "1",
  "data": [
    {
      "birthday": "1960-12-31",
      "company_name": "Nylas",
      "emails": [
        {
          "type": "work",
          "email": "leyah.miller@example.com"
        },
        {
          "type": "home",
          "email": "leyah@example.com"
        }
      ],
      "given_name": "Leyah",
      "grant_id": "<NYLAS_GRANT_ID>",
      "groups": [{ "id": "starred" }, { "id": "friends" }],
      "id": "<CONTACT_ID>",
      "im_addresses": [
        {
          "type": "jabber",
          "im_address": "jabber_at_leyah"
        },
        {
          "type": "msn",
          "im_address": "leyah.miller"
        }
      ],
      "job_title": "Software Engineer",
      "manager_name": "Nyla",
      "middle_name": "Allison",
      "nickname": "Allie",
      "notes": "Loves ramen",
      "object": "contact",
      "office_location": "123 Main Street",
      "phone_numbers": [
        {
          "type": "work",
          "number": "+1-555-555-5555"
        },
        {
          "type": "home",
          "number": "+1-555-555-5556"
        }
      ],
      "physical_addresses": [
        {
          "type": "work",
          "street_address": "123 Main Street",
          "postal_code": "94107",
          "state": "CA",
          "country": "US",
          "city": "San Francisco"
        },
        {
          "type": "home",
          "street_address": "123 Main Street",
          "postal_code": "94107",
          "state": "CA",
          "country": "US",
          "city": "San Francisco"
        }
      ],
      "picture_url": "https://example.com/picture.jpg",
      "source": "address_book",
      "surname": "Miller",
      "web_pages": [
        {
          "type": "work",
          "url": "<WEBPAGE_URL>"
        },
        {
          "type": "home",
          "url": "<WEBPAGE_URL>"
        }
      ]
    }
  ],
  "next_cursor": "2"
}


```

```js [group_1-Node.js SDK]

import Nylas from "nylas";

const nylas = new Nylas({
  apiKey: "<NYLAS_API_KEY>",
  apiUri: "<NYLAS_API_URI>",
});

async function fetchContacts() {
  try {
    const identifier = "<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();


```

```python [group_1-Python SDK]

from nylas import Client

nylas = Client(
    "<NYLAS_API_KEY>",
    "<NYLAS_API_URI>"
)

grant_id = "<NYLAS_GRANT_ID>"

contacts = nylas.contacts.list(
  grant_id,
)

print(contacts)

```

```ruby [group_1-Ruby SDK]

require 'nylas'	

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

contacts.each {|contact|
  puts "Name: #{contact[:given_name]} #{contact[:surname]} | " \
      "Email: #{contact[:emails][0][:email]} | ID: #{contact[:id]}"
}

```

```kt [group_1-Kotlin SDK]

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


```

```java [group_1-Java SDK]

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


```

## View a contact

To get information about a specific contact, make a [Get Contact request](/docs/reference/api/contacts/get-contact/) with the contact's ID.

```bash
curl --compressed --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'

```

```json [group_2-Response (JSON)]

{
  "request_id": "1",
  "data": {
    "birthday": "1960-12-31",
    "company_name": "Nylas",
    "emails": [
      {
        "type": "work",
        "email": "leyah.miller@example.com"
      },
      {
        "type": "home",
        "email": "leyah@example.com"
      }
    ],
    "given_name": "Leyah",
    "grant_id": "<NYLAS_GRANT_ID>",
    "groups": [{ "id": "starred" }, { "id": "friends" }],
    "id": "<CONTACT_ID>",
    "im_addresses": [
      {
        "type": "jabber",
        "im_address": "leyah_jabber"
      },
      {
        "type": "msn",
        "im_address": "leyah_msn"
      }
    ],
    "job_title": "Software Engineer",
    "manager_name": "Bill",
    "middle_name": "Allison",
    "nickname": "Allie",
    "notes": "Loves ramen",
    "object": "contact",
    "office_location": "123 Main Street",
    "phone_numbers": [
      {
        "type": "work",
        "number": "+1-555-555-5555"
      },
      {
        "type": "home",
        "number": "+1-555-555-5556"
      }
    ],
    "physical_addresses": [
      {
        "type": "work",
        "street_address": "123 Main Street",
        "postal_code": "94107",
        "state": "CA",
        "country": "US",
        "city": "San Francisco"
      },
      {
        "type": "home",
        "street_address": "123 Main Street",
        "postal_code": "94107",
        "state": "CA",
        "country": "US",
        "city": "San Francisco"
      }
    ],
    "picture_url": "https://example.com/picture.jpg",
    "source": "address_book",
    "surname": "Miller",
    "web_pages": [
      {
        "type": "work",
        "url": "<WEBPAGE_URL>"
      },
      {
        "type": "home",
        "url": "<WEBPAGE_URL>"
      }
    ]
  }
}


```

```js [group_2-Node.js SDK]

import Nylas from "nylas";

const nylas = new Nylas({
  apiKey: "<NYLAS_API_KEY>",
  apiUri: "<NYLAS_API_URI>",
});

async function fetchContactById() {
  try {
    const contact = await nylas.contacts.find({
      identifier: "<NYLAS_GRANT_ID>",
      contactId: "<CONTACT_ID>",
      queryParams: {},
    });

    console.log("contact:", contact);
  } catch (error) {
    console.error("Error fetching contact:", error);
  }
}

fetchContactById();


```

```python [group_2-Python SDK]

from nylas import Client

nylas = Client(
    "<NYLAS_API_KEY>",
    "<NYLAS_API_URI>"
)

grant_id = "<NYLAS_GRANT_ID>"
contact_id = "<CONTACT_ID>"

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

print(contact)

```

```ruby [group_2-Ruby SDK]

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

```

```kt [group_2-Kotlin SDK]

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


```

```java [group_2-Java SDK]

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


```

### Download contact profile image

Many providers let users assign a photo to a contact's profile. You can access contact profile images by including the `?profile_picture=true` query parameter in a [Get Contact request](/docs/reference/api/contacts/get-contact/).

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

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

```json {34-35} [group_3-Response (JSON)]
{
  "request_id": "1",
  "data": {
    "birthday": "1960-12-31",
    "emails": [
      {
        "type": "home",
        "email": "leyah@example.com"
      }
    ],
    "given_name": "Leyah",
    "grant_id": "<NYLAS_GRANT_ID>",
    "groups": [{ "id": "starred" }, { "id": "friends" }],
    "id": "<CONTACT_ID>",
    "middle_name": "Allison",
    "nickname": "Allie",
    "object": "contact",
    "phone_numbers": [
      {
        "type": "home",
        "number": "+1-555-555-5556"
      }
    ],
    "physical_addresses": [
      {
        "type": "home",
        "street_address": "123 Main Street",
        "postal_code": "94107",
        "state": "CA",
        "country": "US",
        "city": "San Francisco"
      }
    ],
    "picture_url": "https://example.com/picture.jpg",
    "picture": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/4QAqRXhpZgAASUkqAAgAAAABADEB...",
    "source": "address_book",
    "surname": "Miller"
  }
}
```

## Create a contact

To create a contact, make a [Create Contact request](/docs/reference/api/contacts/post-contact/) that includes the contact's profile information.

```bash
curl --compressed --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": "leyah.miller@example.com",
        "type": "work"
      },
      {
        "email": "leyah@example.com",
        "type": "home"
      }
    ],
    "given_name": "Leyah",
    "groups": [
      {
        "id": "starred"
      },
      {
        "id": "friends"
      }
    ],
    "im_addresses": [
      {
        "type": "jabber",
        "im_address": "leyah_jabber"
      },
      {
        "type": "msn",
        "im_address": "leyah_msn"
      }
    ],
    "job_title": "Software Engineer",
    "manager_name": "Bill",
    "middle_name": "Allison",
    "nickname": "Allie",
    "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",
    "surname": "Miller",
    "web_pages": [
      {
        "type": "work",
        "url": "<WEBPAGE_URL>"
      },
      {
        "type": "home",
        "url": "<WEBPAGE_URL>"
      }
    ]
  }'

```

```json [group_4-Response (JSON)]

{
  "request_id": "1",
  "data": {
    "birthday": "1960-12-31",
    "company_name": "Nylas",
    "emails": [
      {
        "type": "work",
        "email": "leyah.miller@example.com"
      },
      {
        "type": "home",
        "email": "leyah@example.com"
      }
    ],
    "given_name": "Leyah",
    "grant_id": "<NYLAS_GRANT_ID>",
    "groups": [{ "id": "starred" }, { "id": "friends" }],
    "id": "<CONTACT_ID>",
    "im_addresses": [
      {
        "type": "jabber",
        "im_address": "leyah_jabber"
      },
      {
        "type": "msn",
        "im_address": "leyah_msn"
      }
    ],
    "job_title": "Software Engineer",
    "manager_name": "Bill",
    "middle_name": "Allison",
    "nickname": "Allie",
    "notes": "Loves ramen",
    "object": "contact",
    "office_location": "123 Main Street",
    "phone_numbers": [
      {
        "type": "work",
        "number": "+1-555-555-5555"
      },
      {
        "type": "home",
        "number": "+1-555-555-5556"
      }
    ],
    "physical_addresses": [
      {
        "type": "work",
        "street_address": "123 Main Street",
        "postal_code": "94107",
        "state": "CA",
        "country": "US",
        "city": "San Francisco"
      },
      {
        "type": "home",
        "street_address": "321 Pleasant Drive",
        "postal_code": "94107",
        "state": "CA",
        "country": "US",
        "city": "San Francisco"
      }
    ],
    "picture_url": "https://example.com/picture.jpg",
    "source": "address_book",
    "surname": "Miller",
    "web_pages": [
      {
        "type": "work",
        "url": "<WEBPAGE_URL>"
      },
      {
        "type": "home",
        "url": "<WEBPAGE_URL>"
      }
    ]
  }
}


```

```js [group_4-Node.js SDK]

import Nylas from "nylas";

const nylas = new Nylas({
  apiKey: "<NYLAS_API_KEY>",
  apiUri: "<NYLAS_API_URI>",
});

async function createContact() {
  try {
    const contact = await nylas.contacts.create({
      identifier: "<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();


```

```python [group_4-Python SDK]

from nylas import Client

nylas = Client(
    "<NYLAS_API_KEY>",
    "<NYLAS_API_URI>"
)

grant_id = "<NYLAS_GRANT_ID>"

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

print(contact)

```

```ruby [group_4-Ruby SDK]

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

```

```kt [group_4-Kotlin SDK]

import com.nylas.NylasClient
import com.nylas.models.ContactEmail
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)
}


```

```java [group_4-Java SDK]

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


```

## Modify a contact

Make an [Update Contact request](/docs/reference/api/contacts/put-contact/) with the contact `id` to change a contact's details.

```bash
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 '{
    "job_title": "Senior Software Engineer"
  }'
```

```json [group_5-Response (JSON)]
{
  "request_id": "1",
  "data": {
    "birthday": "1960-12-31",
    "company_name": "Nylas",
    "emails": [
      {
        "type": "work",
        "email": "leyah.miller@example.com"
      },
      {
        "type": "home",
        "email": "leyah@example.com"
      }
    ],
    "given_name": "Leyah",
    "grant_id": "<NYLAS_GRANT_ID>",
    "groups": [{ "id": "starred" }, { "id": "friends" }],
    "id": "<CONTACT_ID>",
    "im_addresses": [
      {
        "type": "jabber",
        "im_address": "leyah_jabber"
      },
      {
        "type": "msn",
        "im_address": "leyah_msn"
      }
    ],
    "job_title": "Senior Software Engineer",
    "manager_name": "Bill",
    "middle_name": "Allison",
    "nickname": "Allie",
    "notes": "Loves ramen",
    "object": "contact",
    "office_location": "123 Main Street",
    "phone_numbers": [
      {
        "type": "work",
        "number": "+1-555-555-5555"
      },
      {
        "type": "home",
        "number": "+1-555-555-5556"
      }
    ],
    "physical_addresses": [
      {
        "type": "work",
        "street_address": "123 Main Street",
        "postal_code": "94107",
        "state": "CA",
        "country": "US",
        "city": "San Francisco"
      },
      {
        "type": "home",
        "street_address": "321 Pleasant Drive",
        "postal_code": "94107",
        "state": "CA",
        "country": "US",
        "city": "San Francisco"
      }
    ],
    "picture_url": "https://example.com/picture.jpg",
    "source": "address_book",
    "surname": "Miller",
    "web_pages": [
      {
        "type": "work",
        "url": "<WEBPAGE_URL>"
      },
      {
        "type": "home",
        "url": "<WEBPAGE_URL>"
      }
    ]
  }
}
```

```js [group_5-Node.js SDK]

import Nylas from "nylas";

const nylas = new Nylas({
  apiKey: "<NYLAS_API_KEY>",
  apiUri: "<NYLAS_API_URI>",
});

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

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

updateContact();


```

```python [group_5-Python SDK]

from nylas import Client

nylas = Client(
    "<NYLAS_API_KEY>",
    "<NYLAS_API_URI>"
)

grant_id = "<NYLAS_GRANT_ID>"
contact_id = "<CONTACT_ID>"

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

print(contact)

```

```ruby [group_5-Ruby SDK]

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

```

```ruby [group_5-Kotlin SDK]

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


```

```java [group_5-Java SDK]

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


```

## Delete a contact

To delete a contact, make a [Delete Contact request](/docs/reference/api/contacts/delete-contact/) with the contact's `id`.

```bash
curl --compressed --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'

```

```js [group_6-Node.js SDK]

import Nylas from "nylas";

const nylas = new Nylas({
  apiKey: "<NYLAS_API_KEY>",
  apiUri: "<NYLAS_API_URI>",
});
const identifier = "<NYLAS_GRANT_ID>";
const contactId = "<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();


```

```python [group_6-Python SDK]

from nylas import Client

nylas = Client(
    "<NYLAS_API_KEY>",
    "<NYLAS_API_URI>"
)

grant_id = "<NYLAS_GRANT_ID>"
contact_id = "<CONTACT_ID>"

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

print(request)

```

```ruby [group_6-Ruby SDK]

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

```

```kt [group_6-Kotlin SDK]

import com.nylas.NylasClient

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

  print(contact)
}

```

```java [group_6-Java SDK]

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


```

## Organize contacts with contact groups

Contact groups let your users organize their contacts. You can get a full list of a user's contact groups by making a [Get Contact Groups request](/docs/reference/api/contacts/list-contact-groups/).

```bash
curl --compressed --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'

```

```json [group_7-Response (JSON)]

{
  "request_id": "1",
  "data": [
    {
      "grant_id": "<NYLAS_GRANT_ID>",
      "group_type": "system",
      "id": "starred",
      "name": "starred",
      "object": "contact_group",
      "path": "parentId/starred"
    },
    {
      "grant_id": "<NYLAS_GRANT_ID>",
      "group_type": "user",
      "id": "friends",
      "name": "friends",
      "object": "contact_group",
      "path": "parentId/friends"
    }
  ],
  "next_cursor": "2"
}


```

```js [group_7-Node.js SDK]

import Nylas from "nylas";

const nylas = new Nylas({
  apiKey: "<NYLAS_API_KEY>",
  apiUri: "<NYLAS_API_URI>",
});

async function listContactGroups() {
  try {
    const groups = await nylas.contacts.groups({
      identifier: "<NYLAS_GRANT_ID>",
    });

    console.log("Contact groups:", groups);
  } catch (error) {
    console.error("Error listing contact groups:", error);
  }
}

listContactGroups();


```

```python [group_7-Python SDK]

from nylas import Client

nylas = Client(
    "<NYLAS_API_KEY>",
    "<NYLAS_API_URI>"
)

grant_id = "<NYLAS_GRANT_ID>"

contact_groups = nylas.contacts.list_groups(
  grant_id,
)

print(contact_groups)

```

```ruby [group_7-Ruby SDK]

require 'nylas'	

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

puts groups

```

```kt [group_7-Kotlin SDK]

import com.nylas.NylasClient

fun main(args: Array<String>) {

  val nylas: NylasClient = NylasClient(apiKey = "<NYLAS_API_KEY>")
  var groups = nylas.contacts().listGroups("<NYLAS_GRANT_ID>")

  print(groups)
}

```

```java [group_7-Java SDK]

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


```

## Contacts limitations

Keep the following limitations in mind as you work with the Contacts API.

### Google limitations

Google doesn't have a modern push notification API to handle real-time changes to contacts, so Nylas polls for changes every 5 minutes.

### Microsoft Graph limitations

- Microsoft doesn't support the `other` type for phone numbers.
- Contacts can have at most two `home` phone numbers, two `work` phone numbers, and one `mobile` phone number.
- Contacts can have at most one `home` physical address, one `work` physical address, and one `other` physical address.
- Contacts can have up to three email addresses.
  - Email addresses have their `type` set to `null` by default.
- Contacts can have a maximum of three instant messenger (IM) addresses.
- Contacts can have only one `work` webpage.

### Microsoft Exchange (EWS) limitations

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

- Contacts can have at most two `home` phone numbers, two `work` phone numbers, one `mobile` phone number, and one `other` phone number.
- Contacts can have at most one `home` physical address, one `work` physical address, and one `other` physical address.
- Contacts can have a maximum of three instant messenger (IM) addresses.
  - IM addresses have their `type` set to `null` by default.
- Microsoft Exchange doesn't support adding contacts on Microsoft Exchange accounts to contact groups.
- Microsoft Exchange doesn't support the `suffix` property on Exchange contacts.
- Contacts can have up to three email addresses.
  - Email addresses have their `type` set to `null` by default.
- Contacts can have a maximum of three instant messenger (IM) addresses.
  - IM addresses have their `type` set to `null` by default.
- Contacts can have only one `work` webpage.