List contacts
Namespace: microsoft.graph
Get a contact collection from the default contacts folder of the signed-in user.
There are two scenarios where an app can get contacts in another user's contact folder:
- If the app has application permissions, or,
- If the app has the appropriate delegated permissions from one user, and another user has shared a contact folder with that user, or, has given delegated access to that user. See details and an example.
This API is supported in the following national cloud deployments.
Global service | US Government L4 | US Government L5 (DOD) | China operated by 21Vianet |
---|---|---|---|
✅ | ✅ | ✅ | ✅ |
Permissions
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Permissions.
Permission type | Permissions (from least to most privileged) |
---|---|
Delegated (work or school account) | Contacts.Read, Contacts.ReadWrite |
Delegated (personal Microsoft account) | Contacts.Read, Contacts.ReadWrite |
Application | Contacts.Read, Contacts.ReadWrite |
HTTP request
To get all the contacts in a user's default Contacts folder:
GET /me/contacts
GET /users/{id | userPrincipalName}/contacts
To get contacts in a specific folder in the user's mailbox:
GET /me/contactfolders/{Id}/contacts
GET /users/{id | userPrincipalName}/contactfolders/{id}/contacts
GET /me/contactFolders/{id}/childFolders/{id}/.../contacts
GET /users/{id | userPrincipalName}/contactFolders/{id}/childFolders/{id}/contacts
Optional query parameters
You can use the $filter
query parameter to filter contacts based on their email addresses:
GET https://graph.microsoft.com/v1.0/me/contacts?$filter=emailAddresses/any(a:a/address eq 'garth@contoso.com')
You can use $filter
, any
, and the eq
operator on only the address sub-property of instances in an emailAddresses collection. That is, you can't filter on the name or any other sub-property of an instance of emailAddresses, nor can you apply any other operator or function with filter
, such as ne
, le
, and startswith()
.
For general information on the $filter
query parameter, see OData query parameters.
Request headers
Header | Value |
---|---|
Authorization | Bearer {token}. Required. |
Request body
Don't supply a request body for this method.
Response
If successful, this method returns a 200 OK
response code and a collection of contact objects in the response body.
Example
Request
Here's an example of the request.
GET https://graph.microsoft.com/v1.0/me/contacts
Response
Here's an example of the response.
Note: The response object shown here might be shortened for readability.
HTTP/1.1 200 OK
Content-type: application/json
{
"value": [
{
"parentFolderId": "parentFolderId-value",
"birthday": "datetime-value",
"fileAs": "fileAs-value",
"displayName": "displayName-value",
"givenName": "givenName-value",
"initials": "initials-value"
}
]
}
Feedback
Submit and view feedback for