Skip to content
Skip to main content
GET
https://api.us.nylas.com/v3/grants/{grant_id}/contacts

Return all 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 email, phone_number, group, recurse, or a non-default source. You can use limit and page_token with metadata_pair. If a metadata record points to a contact that no longer exists at the provider, Nylas removes the stale record while resolving the query.

NYLAS API KEYACCESS TOKEN

Parameters

Path parameters

grant_id*string

ID of the grant to access. Use /me/ to refer to the grant associated with an access token.

Query parameters

limitinteger

The maximum number of objects to return. See Pagination for more information.

Default: 30
page_tokenstring

An identifier that specifies which page of data to return. You can get this value from the next_cursor response field. See Pagination for more information.

metadata_pairstring

Pass one indexed metadata key/value pair (for example, ?metadata_pair=key1:value) to search for objects. The key must be key1, key2, key3, key4, or key5. See Metadata for more information.

selectstring

Specify fields that you want Nylas to return, as a comma-separated list (for example, select=id,updated_at). This allows you to receive only the portion of object data that you're interested in. You can use select to optimize response size and reduce latency by limiting queries to only the information that you need.

emailstring

Returns the contacts containing the specified email address.

phone_numberstring

(Google, IMAP, iCloud, Yahoo, and EWS only) Returns contacts containing the specified phone number.

sourcestring

Returns contacts from the user's address book, domain, or contacts generated automatically from message participants. To filter for multiple sources, pass a comma-separated list (for example, source=address_book,inbox). See Contact sources for provider availability and behavior.

address_bookdomaininbox
Default: "address_book"
groupstring

(Not supported for EWS) Returns the contacts included in the specified Contact Group.

recursestring

(Microsoft Only) When true, returns the contacts in the specified Contact Group subgroups. The recursion goes only one level deep.

Responses

request_idstring

The request ID.

dataarray<object>
next_cursorstringnullable

A cursor pointing to the next page of results for the request.

GEThttps://api.us.nylas.com/v3/grants/{grant_id}/contacts?limit=30&source=address_book

Find your API key in the Nylas Dashboard under API Keys in your application settings.

grant_idrequiredstring

ID of the grant to access. Use /me/ to refer to the grant associated with an access token.