Version:
Only show these results:

Upgrade a v2 project to use v3 Contacts APIs

This page explains how to upgrade your Nylas v2.x project to use the v3 Contacts API.

✨ Want a version of this guide tailored to your project? Check out Nylas Migration Station!

Before you begin

Before you upgrade your Contacts API components, make sure you have already...

  • Upgraded your authentication systems from v2.x to v3.
  • Upgraded your webhooks from v2.x to v3.

To start, note any places in your code where you accept and parse v2 Contact objects. In Nylas API v3, Contacts are returned as JSON objects instead of a list of comma-separated values.

New scopes for specific contacts sources

If you use the Contacts APIs and want to use domain-level or inbox contacts you may need to add scopes. If you only use address book contacts, no changes are required.

To access Contacts parsed from the user's email inbox, use the inbox source, and request the contacts.other.readonly Google scope and the People.Read Microsoft scope.

To use Contacts from the user's domain address book, use the domain source, and request the directory.readonly Google scope and the People.Read Microsoft scope.

Upgrade to v3 Contacts API

💡 Nylas recommends you test these changes in a non-production environment first. This helps to identify and troubleshoot any issues without impacting your end users or production environment.

There are three changes you need to make to upgrade to the v3 Contacts API:

Update endpoint references for v3

To update your application's endpoint references, find all instances of the v2 /contacts endpoints and change them to the appropriate v3 endpoints:

  • GET /contacts → GET /v3/grants/{grant_id}/contacts
  • POST /contacts → POST /v3/grants/{grant_id}/contacts
  • GET /contacts/<id> → GET /v3/grants/{grant_id}/contacts/{contact_id}
  • PUT /contacts/<id> → PUT /v3/grants/{grant_id}/contacts/{contact_id}
  • DELETE /contacts/<id> → DELETE /v3/grants/{grant_id}/contacts/{contact_id}
  • GET /contacts/groups → GET /v3/grants/{grant_id}/contacts/groups

The GET /contacts/{id}/picture endpoint has been deprecated in API v3. Instead, you include the ?profile_picture=true query parameter in a GET /v3/grants/{grant_id}/contacts/{contact_id} request to get the contact's profile picture.

Update webhook references for v3

Nylas API v3 supports the contact.updated and contact.deleted webhooks. These are unchanged from API v2. v3 does not support the contact.created webhook trigger. Be sure to keep this in mind as you update your webhook references.

Modify parsing methods for Contact objects

Because Nylas API v3 returns Contacts as JSON objects rather than lists of comma-separated values, you must update any code specifically intended to parse v2 Contacts. The following JSON sample is an example of a v3 Contact object that Nylas returns for a Get Contact request.

{
  "request_id": "5fa64c92-e840-4357-86b9-2aa364d35b88",
  "data": {
    "birthday": "1960-12-31",
    "company_name": "Nylas",
    "emails": [{
      "type": "home",
      "email": "john-home@example.com"
    }],
    "given_name": "John",
    "grant_id": "41009df5-bf11-4c97-aa18-b285b5f2e386",
    "groups": [{
      "id": "starred"
    }],
    "id": "5d3qmne77v32r8l4phyuksl2x",
    "im_addresses": [{
      "type": "jabber",
      "im_address": "myjabberaddress"
    }],
    "job_title": "Software Engineer",
    "manager_name": "Bill",
    "middle_name": "Jacob",
    "nickname": "JD",
    "notes": "Loves ramen",
    "object": "contact",
    "office_location": "123 Main Street",
    "phone_numbers": [{
      "type": "home",
      "number": "+1-555-555-5555"
    }],
    "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",
    "suffix": "Jr.",
    "surname": "Doe",
    "web_pages": [{
      "type": "home",
      "url": "https://www.example.com"
    }]
  }
}

For more information about contacts in Nylas API v3, see the Contacts reference documentation.

What's next?

You're nearly there! 🎉 If you haven't already, be sure to upgrade to the v3 Email and Calendar APIs. If you're done with the APIs, you can move on to upgrade any Nylas SDKs that your project uses.