Microsoft Entra synchronization API overview
Namespace: microsoft.graph
Important
APIs under the /beta version in Microsoft Graph are subject to change. Use of these APIs in production applications is not supported. To determine whether an API is available in v1.0, use the Version selector.
Microsoft Entra identity synchronization (also called "provisioning") allows you to automate the provisioning (creation, maintenance) and de-provisioning (removal) of identities from any of the following:
- Active Directory to Microsoft Entra ID
- Workday to Microsoft Entra ID
- Microsoft Entra ID to cloud applications such as Dropbox, Salesforce, ServiceNow, and more
You can use the synchronization APIs in Microsoft Graph to manage identity synchronization programmatically, including:
- Create, start, and stop synchronization jobs
- Make changes to the synchronization schema for jobs
- Verify the current synchronization status
For more information about synchronization in Microsoft Entra ID, see:
- Automate user provisioning and deprovisioning to SaaS applications with Microsoft Entra ID
- Managing user account provisioning for enterprise apps in the Microsoft Entra admin center
You can also try the API in the Graph Explorer in a sample tenant or your own tenant.
Synchronization job
Synchronization jobs perform synchronization by periodically running in the background, polling for changes in one directory, and pushing them to another directory. The synchronization job is always specific to a particular instance of an application in your tenant. As part of the synchronization job setup, you need to give authorization to read and write objects in your target directory, and customize the job's synchronization schema.
For more information, see synchronization job.
Synchronization schema
The synchronization schema defines what objects will be synchronized and how they will be synchronized. The synchronization schema contains most of the setup information for a particular synchronization job. Typically, you will customize some of the attribute mappings, or add a scoping filter to synchronize only objects that satisfy a certain condition.
The synchronization schema includes the following components:
- Directory definitions
- Synchronization rules
- Object mappings
For more information, see synchronization schema.
Synchronization template
The synchronization template provides pre-configured synchronization settings for a particular application. These settings (most importantly, synchronization schema) will be used by default for any synchronization job that is based on the template. Templates are specified by the application developer.
For more information, see synchronization template.
Working with the synchronization API
Working with synchronization API primarily involves accessing the synchronizationJob and synchronizationSchema resources. To find your synchronizationJob resource, you need to know the ID of the service principal object that the synchronization job belongs to. The following examples show you how to work with the synchronizationJob and synchronizationSchema resources.
Authorization
To work with the Microsoft Entra synchronization APIs, Microsoft Graph supports the following granular permissions:
- Synchronization.Read.All
- Synchronization.ReadWrite.All
- Application.ReadWrite.OwnedBy
- Application.Read.All
- Application.ReadWrite.All
And the following least privileged Microsoft Entra directory roles:
- Application Administrator
- Cloud Application Administrator
- Hybrid Identity Administrator
For more information about the privileges you need to call each API, visit the respective API reference documentation.
Find the service principal object by display name
The following example shows how to find service principal object by display name.
Request
GET https://graph.microsoft.com/beta/servicePrincipals?$select=id,appId,displayName&$filter=startswith(displayName, 'salesforce')
Response
HTTP/1.1 200 OK
{
"value":[
{
"id":"bc0dc311-87df-48ac-91b1-259bd2c3a31c",
"appId":"f7808c5e-cb57-4e37-8094-406d302c0f8d",
"displayName":"Salesforce"
},
{
"id":"d813d7d7-0f41-4edc-b284-d0dfaf399d15",
"appId":"219561ee-1480-4c67-9aa6-63d861fae3ef",
"displayName":"salesforce 3"
}
]
}
Find the service principal object by app ID
The following example shows how to find the service principal object by app ID.
Request
GET https://graph.microsoft.com/beta/servicePrincipals?$select=id,appId,displayName&$filter=AppId eq '219561ee-1480-4c67-9aa6-63d861fae3ef'
Response
HTTP/1.1 200 OK
{
"value": [
{
"id": "d813d7d7-0f41-4edc-b284-d0dfaf399d15",
"appId": "219561ee-1480-4c67-9aa6-63d861fae3ef",
"displayName": "salesforce 3"
}
]
}
List existing synchronization jobs
The following example shows you how to list existing synchronization jobs.
Request
GET https://graph.microsoft.com/beta/servicePrincipals/{id}/synchronization/jobs
GET https://graph.microsoft.com/beta/servicePrincipals/60443998-8cf7-4e61-b05c-a53b658cb5e1/synchronization/jobs
Response
HTTP/1.1 200 OK
{
"value": [
{
"id": "SfSandboxOutDelta.e4bbf44533ea4eabb17027f3a92e92aa",
"templateId": "SfSandboxOutDelta",
"schedule": {
"expiration": null,
"interval": "PT20M",
"state": "Active"
},
"status": {}
}
]
}
Get synchronization job status
The following example shows you how to get the status of a synchronization job.
Request
GET https://graph.microsoft.com/beta/servicePrincipals/{id}/synchronization/jobs/{jobId}
GET https://graph.microsoft.com/beta/servicePrincipals/60443998-8cf7-4e61-b05c-a53b658cb5e1/synchronization/jobs/SfSandboxOutDelta.e4bbf44533ea4eabb17027f3a92e92aa
Response
HTTP/1.1 200 OK
{
"id": "SfSandboxOutDelta.e4bbf44533ea4eabb17027f3a92e92aa",
"templateId": "SfSandboxOutDelta",
"schedule": {
"expiration": null,
"interval": "PT20M",
"state": "Active"
},
"status": {}
}
Get synchronization schema
The following example shows you how to get the synchronization schema.
Request
GET https://graph.microsoft.com/beta/servicePrincipals/{id}/synchronization/jobs/{jobId}/schema
Response
HTTP/1.1 200 OK
{
"directories": [],
"synchronizationRules": []
}