CRUD operations with REST API
Documentation for the usage of the customer facing REST API for Database Contact insertion
Authentication
To access the API endpoints you need to acquire a Bearer token. The API uses Microsoft as an Identity Provider with Application permissions. Therefore the access can be managed similarily to the the access of the Microsoft Graph API.
Prerequisites
If you have used UnifiedContactsPS with version lower than 1.1.0 to install Unified Contacts, you first have to perform the additional steps explained here.
NOTE: If you have initially installed Unified Contacts Pro before version 1.5.0, this is very likely the case.
Permission Setup
Select an existing App Registration or create a new one that will be used to authenticate you when accessing the Unified Contacts REST API.
Navigate to API permissions > Add a permission > My APIs then select the Unified Contacts Admin AppRegistration. If you have not changed the default naming when deploying Unified Contacts via the ARM template the name will be in the following format:
admin-app-reg-uc-<13 random alphanumeric characters>Select Application permissions on the top and activate the checkbox next to Contacts.Database.ReadWrite.All. Finalize the assignment by clicking "Add permissions" on the bottom.
A Cloud Application-, Application-, or Global-Admin now has to Grant admin consent for the tenant. This is done by clicking the Grant admin consent for <Tenant> button and confirming the action by clicking on Yes.
After the Admin consent is granted the AppRegistration is ready for usage.
Acquiring a token
A detailed explanation on acquiring tokens against an AppRegistration can be found here (Microsoft docs).
In the following example we will configure Postman to acquire a valid token with an Application Secret. However we recommend the usage of a Managed Identity (when applicable) or with Certificates when creating a productive/regularly running process or sync.
More details on certificate authentication can be found here (Microsoft docs).
More details on Managed Identity authentication can be found here (Microsoft docs).
Open the AppRegistration from before. Navigate to Certificates & secrets > Client secrets > New client secret. Set a description and configure the Expiry date (max. 2 years). Finalize the process by clicking "Add".
Copy and store the freshly generated client secret somewhere secure (e.g. a credential manager). NOTE: Once you leave this page you will only be able to see a censored shortened version of the secret. So if you do not store the secret properly and forget it you'll need to create a new one
Navigate to the Overview tab of the AppRegistration. Copy the ClientId for later use. Click on Endpoints and copy the OAuth 2.0 token endpoint (v2) for later use.
Navigate to API permissions select the Contacts.Database.ReadWrite.All permission and Copy the scope for later use.
Create a new Postman Collection and navigate to the Authentication tab. There select OAuth 2.0 as Type
Fill out the Configure new token category
Token Name: Any custom Name
Grant Type: Client Credentials
Access Token URL: Paste the token URL copied in Step 3
Client ID: Paste the Client Id copied in Step 3
Client Secret: Paste Secret copied in Step 2
Scope: Paste scope copied in step 4. Replace Contacts.Database.ReadWrite.All with .default
Client Authentication: Send as Basic Auth header
Your result should look something like this:
If you have configured everything correctly, you can now scroll to the bottom and click on "Get New Access Token" to acquire a new access token. All requests within the Collection can now be authenticated with that token.
API Documentation
You can download a sample Postman Collection here:
Last updated
