Skip to content
Skip to main content

Contacts

The Nylas Contacts API allows you to create and manage contacts, and organize them into contact groups. Nylas uses the same commands to manage contacts across providers, and can refer to a specific contact using the provider's contact_id.

Contacts scopes

The table below lists the Contacts endpoints and which scopes they require. The table shortens the full scope URI for space reasons, so add the prefix for the provider when requesting scopes.

The ☑️ in each column indicates the most restrictive scope you can request for each provider and still use that API. More permissive scopes appear under the minimum option. If you're already using one of the permissive scopes, you don't need to add the more restrictive scope.

Endpoint Google Scopes
https://www.googleapis.com/auth/...		 Microsoft Scopes
https://graph.microsoft.com/...
GET /contacts
GET /contacts/<CONTACT_ID>
GET /contact_groups		 /contacts.readonly ☑️
/contacts.other.readonly ☑️
/directory.readonly* ☑️		 Contacts.Read ☑️
People.Read* ☑️
POST /contacts
PUT /contacts/<CONTACT_ID>
DELETE /contacts/<CONTACT_ID>		 /contacts ☑️ Contacts.ReadWrite ☑️
📝 Note: To access Contacts with the inbox source, you must use the contacts.other.readonly Google scope and the People.Read Microsoft scope. For Contacts with the domain source, you must use the directory.readonly Google scope and the People.Read Microsoft scope.

For more information about scopes, see Using scopes to request user data.

Contacts notifications

You can subscribe to the following triggers so Nylas notifies you about changes to your users' data:

  • contact.updated
  • contact.deleted

For more information, see the Contact notification schemas.

Endpoints

6
GET
Return all contacts
GET /v3/grants/{grant_id}/contacts

Return all contacts in a user's address book.

POST
Create contact
POST /v3/grants/{grant_id}/contacts

Create a contact in a user's address book.

GET
Return a contact
GET /v3/grants/{grant_id}/contacts/{contact_id}

Return a contact by ID.

PUT
Update a contact
PUT /v3/grants/{grant_id}/contacts/{contact_id}

Updates the specified contact from the user's address book. When you make a PUT request, Nylas replaces all data in the nested object with the information included in your request. For more informatio...

DELETE
Delete a contact
DELETE /v3/grants/{grant_id}/contacts/{contact_id}

Delete a contact from the user's address book.

GET
Return all Contact Groups
GET /v3/grants/{grant_id}/contacts/groups

(Not supported for EWS) Return a list of all Contact Groups associated with a grant.