Microsoft Graph: Outlook Contacts and People
Manage a user's personal contacts and contact folders, and find the people most relevant to them. This listing is one area of Microsoft Graph, the single REST…
Productivity & workspace#openapi
Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.
Overview
Manage a user's personal contacts and contact folders, and find the people most relevant to them.
This listing is one area of Microsoft Graph, the single REST API for Microsoft 365, Outlook, OneDrive, Teams and Microsoft Entra ID. It holds 56 of the area's requests, the most direct ones first, generated from Microsoft's own OpenAPI description of Graph v1.0. The other areas (mail, calendar, files, Teams, users and more) are listed separately on the Microsoft page.
Get an access token
- Sign in to the Microsoft Entra admin center and open App registrations > New registration. For a quick test, the Graph Explorer signs you in and shows a token without registering anything.
- Under API permissions, add the Microsoft Graph permissions this area needs, for example:
Contacts.Read,Contacts.ReadWrite,People.Read. Delegated permissions act as the signed-in user; application permissions act as the app itself and need an administrator's consent. - Under Certificates & secrets, create a client secret (keep it out of shared collections).
- Get a token from
https://login.microsoftonline.com/ /oauth2/v2.0/token: the authorization-code flow for a user, orgrant_type=client_credentialswithscope=https://graph.microsoft.com/.defaultfor an app. Send it asAuthorization: Bearer.
Using these requests
- Base URL:
https://graph.microsoft.com/v1.0./me/...paths act on the signed-in user; with an application token use/users/{id or userPrincipalName}/...instead. - Shape responses with OData query parameters:
$select(fields),$filter,$orderby,$top,$expandand$search(some need theConsistencyLevel: eventualheader). Long lists are paged: follow@odata.nextLink. - Combine up to 20 requests in one call with
POST /$batch.
Common errors
| Status | Code | What to do |
|---|---|---|
| 401 | InvalidAuthenticationToken | The token is missing, expired or for another resource: get a new one for https://graph.microsoft.com. |
| 403 | Authorization_RequestDenied / ErrorAccessDenied | Add the permission listed in the request's docs and grant consent. |
| 404 | ResourceNotFound / itemNotFound | Check the id; ids from another user or tenant are not found. |
| 429 | TooManyRequests | Throttled: wait the Retry-After seconds, then retry. |
Docs: Outlook Contacts and People overview · Permissions reference · Throttling
Endpoints 56
Contacts
- GETList contacts
/me/contactsGet 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… - POSTCreate contact
/me/contactsAdd a contact to the root Contacts folder or to the contacts endpoint of another contact folder. - GETTrack changes to contacts (delta)
/me/contacts/delta()Get a set of contacts that have been added, deleted, or updated in a specified folder. A delta function call for contacts in a folder is similar to a GET… - GETGet contact
/me/contacts/:contact-idRetrieve the properties and relationships of a contact object. There are two scenarios where an app can get a contact in another user's contact folder: - DELETEDelete contact
/me/contacts/:contact-idDelete a contact. - PATCHUpdate contact
/me/contacts/:contact-idUpdate the properties of a contact object. - POSTPermanent delete (contact)
/me/contacts/:contact-id/permanentDelete
Contacts: photo
- GETGet photo
/me/contacts/:contact-id/photoOptional contact picture. You can get or set a photo for a contact. - PATCHUpdate photo
/me/contacts/:contact-id/photo - GETDownload contact content
/me/contacts/:contact-id/photo/$valueOptional contact picture. You can get or set a photo for a contact. - PUTUpload contact content
/me/contacts/:contact-id/photo/$valueOptional contact picture. You can get or set a photo for a contact. - DELETEUpload contact content
/me/contacts/:contact-id/photo/$valueOptional contact picture. You can get or set a photo for a contact.
Contacts: extensions
- GETList extensions
/me/contacts/:contact-id/extensionsThe collection of open extensions defined for the contact. Read-only. Nullable. - POSTCreate extension
/me/contacts/:contact-id/extensions - GETGet extension
/me/contacts/:contact-id/extensions/:extension-idThe collection of open extensions defined for the contact. Read-only. Nullable. - DELETEDelete extension
/me/contacts/:contact-id/extensions/:extension-id - PATCHUpdate extension
/me/contacts/:contact-id/extensions/:extension-id
People
- GETGet people
/me/peopleRetrieve a collection of person objects ordered by their relevance to the user, which is determined by the user's communication and collaboration patterns,… - GETGet people
/me/people/:person-idPeople that are relevant to the user. Read-only. Nullable.
Contact folders
- GETList contact folders
/me/contactFoldersGet the contact folder collection in the default Contacts folder of the signed-in user. - POSTCreate contact folder
/me/contactFoldersCreate a new contactFolder under the user's default contacts folder. You can also create a new contactfolder as a child of any specified contact folder. - GETTrack changes to contact folders (delta)
/me/contactFolders/delta()Get a set of contact folders that have been added, deleted, or removed from the user's mailbox. A delta function call for contact folders in a mailbox is… - GETGet contact folder
/me/contactFolders/:contactFolder-idGet a contact folder by using the contact folder ID. There are two scenarios where an app can get another user's contact folder: - DELETEDelete contact folder
/me/contactFolders/:contactFolder-idDelete contactFolder other than the default contactFolder. - PATCHUpdate contact folder
/me/contactFolders/:contactFolder-idUpdate the properties of contactfolder object. - POSTPermanent delete (contact folder)
/me/contactFolders/:contactFolder-id/permanentDelete
Contact folders: contacts
- GETList contacts
/me/contactFolders/:contactFolder-id/contactsGet a contact collection from the default Contacts folder of the signed-in user (.../me/contacts), or from the specified contact folder. - POSTCreate contact
/me/contactFolders/:contactFolder-id/contactsAdd a contact to the root Contacts folder or to the contacts endpoint of another contact folder. - GETTrack changes to contacts (delta)
/me/contactFolders/:contactFolder-id/contacts/delta()Get a set of contacts that have been added, deleted, or updated in a specified folder. A delta function call for contacts in a folder is similar to a GET… - GETGet contact
/me/contactFolders/:contactFolder-id/contacts/:contact-idThe contacts in the folder. Navigation property. Read-only. Nullable. - DELETEDelete contact
/me/contactFolders/:contactFolder-id/contacts/:contact-id - PATCHUpdate contact
/me/contactFolders/:contactFolder-id/contacts/:contact-id - GETGet photo
/me/contactFolders/:contactFolder-id/contacts/:contact-id/photoOptional contact picture. You can get or set a photo for a contact. - PATCHUpdate photo
/me/contactFolders/:contactFolder-id/contacts/:contact-id/photo - GETList extensions
/me/contactFolders/:contactFolder-id/contacts/:contact-id/extensionsThe collection of open extensions defined for the contact. Read-only. Nullable. - POSTCreate extension
/me/contactFolders/:contactFolder-id/contacts/:contact-id/extensions - POSTPermanent delete (contact)
/me/contactFolders/:contactFolder-id/contacts/:contact-id/permanentDelete - GETDownload contact content
/me/contactFolders/:contactFolder-id/contacts/:contact-id/photo/$valueOptional contact picture. You can get or set a photo for a contact. - PUTUpload contact content
/me/contactFolders/:contactFolder-id/contacts/:contact-id/photo/$valueOptional contact picture. You can get or set a photo for a contact. - DELETEUpload contact content
/me/contactFolders/:contactFolder-id/contacts/:contact-id/photo/$valueOptional contact picture. You can get or set a photo for a contact. - GETGet extension
/me/contactFolders/:contactFolder-id/contacts/:contact-id/extensions/:extension-idThe collection of open extensions defined for the contact. Read-only. Nullable. - DELETEDelete extension
/me/contactFolders/:contactFolder-id/contacts/:contact-id/extensions/:extension-id - PATCHUpdate extension
/me/contactFolders/:contactFolder-id/contacts/:contact-id/extensions/:extension-id
Contact folders: child folders
- GETList child folders
/me/contactFolders/:contactFolder-id/childFoldersGet a collection of child folders under the specified contact folder. - POSTCreate child folder
/me/contactFolders/:contactFolder-id/childFoldersCreate a new contactFolder as a child of a specified folder. You can also create a new contactFolder under the user's default contact folder. - GETTrack changes to child folders (delta)
/me/contactFolders/:contactFolder-id/childFolders/delta()Get a set of contact folders that have been added, deleted, or removed from the user's mailbox. A delta function call for contact folders in a mailbox is… - GETGet child folder
/me/contactFolders/:contactFolder-id/childFolders/:contactFolder-id1The collection of child folders in the folder. Navigation property. Read-only. Nullable. - DELETEDelete child folder
/me/contactFolders/:contactFolder-id/childFolders/:contactFolder-id1 - PATCHUpdate child folder
/me/contactFolders/:contactFolder-id/childFolders/:contactFolder-id1 - GETList contacts
/me/contactFolders/:contactFolder-id/childFolders/:contactFolder-id1/contactsThe contacts in the folder. Navigation property. Read-only. Nullable. - POSTCreate contact
/me/contactFolders/:contactFolder-id/childFolders/:contactFolder-id1/contacts - POSTPermanent delete (child folder)
/me/contactFolders/:contactFolder-id/childFolders/:contactFolder-id1/permanentDelete - GETTrack changes to contacts (delta)
/me/contactFolders/:contactFolder-id/childFolders/:contactFolder-id1/contacts/delta()Get a set of contacts that have been added, deleted, or updated in a specified folder. A delta function call for contacts in a folder is similar to a GET… - GETGet contact
/me/contactFolders/:contactFolder-id/childFolders/:contactFolder-id1/contacts/:contact-idThe contacts in the folder. Navigation property. Read-only. Nullable. - DELETEDelete contact
/me/contactFolders/:contactFolder-id/childFolders/:contactFolder-id1/contacts/:contact-id - PATCHUpdate contact
/me/contactFolders/:contactFolder-id/childFolders/:contactFolder-id1/contacts/:contact-id
API details
- Base URL
https://graph.microsoft.com/v1.0- Authentication
- OAuth 2.0 (authorization code, client credentials flows)
- Operations
- 56 operations on 29 pathsGET 25POST 11PATCH 9DELETE 9PUT 2
- Main resources
- Contact folders: contacts 17Contact folders: child folders 13Contact folders 7Contacts 7Contacts: extensions 5Contacts: photo 5People 2
- Description format
- OpenAPI 3.0.4, API version
v1.0 - Links
- Documentation · OpenAPI document
How to test the Microsoft Graph: Outlook Contacts and People in Swastik Codes
- Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
- Fork it into your workspaceChoose a workspace. You get your own copy of the Microsoft Graph: Outlook Contacts and People collection, without the publisher's secrets.
- Add your credentialsThis API uses OAuth 2.0 (authorization code, client credentials flows). Add yours in the collection's variables or an environment; the requests already reference it.
- Send a requestPick an endpoint, for example “List contacts” (GET /me/contacts), and press Send. Check the response, add tests and run the whole collection with the runner.
Frequently asked questions
What is the Microsoft Graph: Outlook Contacts and People?
Manage a user's personal contacts and contact folders, and find the people most relevant to them. This listing is one area of Microsoft Graph, the single REST… It is listed under Productivity & workspace and has 56 endpoints.
Who publishes the Microsoft Graph: Outlook Contacts and People?
It is listed from Microsoft's public API description (an OpenAPI document), not published by Microsoft on Swastik Codes. Anyone who controls microsoft.com can claim the profile by adding a DNS TXT record.
What is the base URL of the Microsoft Graph: Outlook Contacts and People?
Requests go to https://graph.microsoft.com/v1.0. Endpoint paths are added to this base URL.
How do I authenticate with the Microsoft Graph: Outlook Contacts and People?
With OAuth 2.0 (authorization code, client credentials flows).
How many endpoints does the Microsoft Graph: Outlook Contacts and People have?
56 operations on 29 paths (25 GET, 11 POST, 9 PATCH, 9 DELETE, 2 PUT). The largest groups are Contact folders: contacts, Contact folders: child folders, Contact folders, Contacts.
Is forking the Microsoft Graph: Outlook Contacts and People free?
Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.