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.

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.

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": "[email protected]"
    }],
    "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": "http://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.