Skip to content
Skip to main content

Contacts

The Nylas Contacts API lets you create and manage contacts and organize them into Contact Groups. Nylas uses the same endpoints across providers and refers to a specific contact using the provider's contact_id.

For provider-specific source and ID behavior, see Work with Contacts. For group behavior, see Work with Contact Groups. For Contact metadata, see Metadata.

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 contacts from a user's selected source. See Contact sources for provider-specific behavior. Results include Nylas-managed Contact metadata. When metadata pair is present, you can't also use ema...

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

Create a contact in a user's address book. New contacts use source=address book. See Contact sources for provider-specific behavior. You can attach Nylas-managed metadata to the Contact object. Nylas...

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 and clean up its Nylas-managed metadata. See Contact sources for source-specific behavior.

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

Return the Contact Groups associated with a grant. This endpoint is not supported for EWS. See Work with Contact Groups for provider-specific behavior.