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": "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.