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

• Unified Contacts Pro setup completed with version 1.5.0 or later

• Cloud Application Administrator, Application Administrator or Global Admin privileges (used for the admin grant)

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

1. Select an existing App Registration or create a new one that will be used to authenticate you when accessing the Unified Contacts REST API.

2. 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>

   
3. 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.

   
4. 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.

   
5. 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).

1. 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".

   
2. 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

   
3. 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.

   
4. Navigate to API permissions select the Contacts.Database.ReadWrite.All permission and Copy the scope for later use.

   
5. Create a new Postman Collection and navigate to the Authentication tab. There select OAuth 2.0 as Type

   
6. 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

7. Your result should look something like this:

   
8. 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

Gets a contact with all meta data that is stored in the database

GET/api/v1/contacts/{contactId}

Path parameters

contactId*string

Id of the contact

Response

200404

Contact successfully found and returned

Body

text/plainapplication/jsontext/json

displayNamenullable string

DisplayName of the contact

Example: "John Doe"

jobTitlenullable string

JobTitle of the contact

Example: "Software Developer"

departmentnullable string

Department of the contact

Example: "Development"

companyNamenullable string

Name of company assosiated with the contact

Example: "Fantastic Company Inc."

mailAddressesnullable array of string

Email addresses of the contact

imAddressesnullable array of string

Instant messaging addresses of the contact. Used for initiating a chat in Teams. If multiple imAddresses provided, the first one is used for intite a chat. If not provided the first eMail address of the contact is used.

mobilePhoneNumbersnullable array of string

Mobile phone numbers of the contact

businessPhoneNumbersnullable array of string

Business phone numbers of the contact

homePhoneNumbersnullable array of string

Home phone numbers of the contact

addressFullStringnullable string

Full address of the contact. If this is set it is used for displaying the address in the contact card. If not set the address is build from the other address properties.

Example: "Any Street 1, 12345 Any City, Any Country"

addressStreetAddressnullable string

Street address of the contact

Example: "Any Street 1"

addressPostalCodenullable string

Postal code of the contact

Example: "12345"

addressCitynullable string

City of the contact

Example: "Any City"

addressCountrynullable string

Country of the contact

Example: "Any Country"

sourcenullable string

Sub source of the contact. This is used to identify the source of the contact if you are using multiple sources, that are synced into the database.

Example: "SAP"

idnullable string

Request

JavaScriptCurlPython

const response = await fetch('/api/v1/contacts/{contactId}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "displayName": "John Doe",
  "jobTitle": "Software Developer",
  "department": "Development",
  "companyName": "Fantastic Company Inc.",
  "mailAddresses": [
    "[e-mail]"
  ],
  "imAddresses": [
    "[e-mail]"
  ],
  "mobilePhoneNumbers": [
    "[phone]"
  ],
  "businessPhoneNumbers": [
    "[phone]"
  ],
  "homePhoneNumbers": [
    "[phone]"
  ],
  "addressFullString": "Any Street 1, 12345 Any City, Any Country",
  "addressStreetAddress": "Any Street 1",
  "addressPostalCode": "12345",
  "addressCity": "Any City",
  "addressCountry": "Any Country",
  "source": "SAP",
  "id": "text"
}

Creates a new contact

POST/api/v1/contacts

Body

application/jsontext/jsonapplication/*+json

Request body

displayNamenullable string

DisplayName of the contact

Example: "John Doe"

jobTitlenullable string

JobTitle of the contact

Example: "Software Developer"

departmentnullable string

Department of the contact

Example: "Development"

companyNamenullable string

Name of company assosiated with the contact

Example: "Fantastic Company Inc."

mailAddressesnullable array of string

Email addresses of the contact

imAddressesnullable array of string

Instant messaging addresses of the contact. Used for initiating a chat in Teams. If multiple imAddresses provided, the first one is used for intite a chat. If not provided the first eMail address of the contact is used.

mobilePhoneNumbersnullable array of string

Mobile phone numbers of the contact

businessPhoneNumbersnullable array of string

Business phone numbers of the contact

homePhoneNumbersnullable array of string

Home phone numbers of the contact

addressFullStringnullable string

Full address of the contact. If this is set it is used for displaying the address in the contact card. If not set the address is build from the other address properties.

Example: "Any Street 1, 12345 Any City, Any Country"

addressStreetAddressnullable string

Street address of the contact

Example: "Any Street 1"

addressPostalCodenullable string

Postal code of the contact

Example: "12345"

addressCitynullable string

City of the contact

Example: "Any City"

addressCountrynullable string

Country of the contact

Example: "Any Country"

sourcenullable string

Sub source of the contact. This is used to identify the source of the contact if you are using multiple sources, that are synced into the database.

Example: "SAP"

idnullable string

Unique identifier of the contact

Example: "sap_28648f3b-8a60-4ded-a2df-5f303a74a17a"

Response

200201409

Success

Body

text/plainapplication/jsontext/json

displayNamenullable string

DisplayName of the contact

Example: "John Doe"

jobTitlenullable string

JobTitle of the contact

Example: "Software Developer"

departmentnullable string

Department of the contact

Example: "Development"

companyNamenullable string

Name of company assosiated with the contact

Example: "Fantastic Company Inc."

mailAddressesnullable array of string

Email addresses of the contact

imAddressesnullable array of string

Instant messaging addresses of the contact. Used for initiating a chat in Teams. If multiple imAddresses provided, the first one is used for intite a chat. If not provided the first eMail address of the contact is used.

mobilePhoneNumbersnullable array of string

Mobile phone numbers of the contact

businessPhoneNumbersnullable array of string

Business phone numbers of the contact

homePhoneNumbersnullable array of string

Home phone numbers of the contact

addressFullStringnullable string

Full address of the contact. If this is set it is used for displaying the address in the contact card. If not set the address is build from the other address properties.

Example: "Any Street 1, 12345 Any City, Any Country"

addressStreetAddressnullable string

Street address of the contact

Example: "Any Street 1"

addressPostalCodenullable string

Postal code of the contact

Example: "12345"

addressCitynullable string

City of the contact

Example: "Any City"

addressCountrynullable string

Country of the contact

Example: "Any Country"

sourcenullable string

Sub source of the contact. This is used to identify the source of the contact if you are using multiple sources, that are synced into the database.

Example: "SAP"

idnullable string

Request

JavaScriptCurlPython

const response = await fetch('/api/v1/contacts', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

200

{
  "displayName": "John Doe",
  "jobTitle": "Software Developer",
  "department": "Development",
  "companyName": "Fantastic Company Inc.",
  "mailAddresses": [
    "[e-mail]"
  ],
  "imAddresses": [
    "[e-mail]"
  ],
  "mobilePhoneNumbers": [
    "[phone]"
  ],
  "businessPhoneNumbers": [
    "[phone]"
  ],
  "homePhoneNumbers": [
    "[phone]"
  ],
  "addressFullString": "Any Street 1, 12345 Any City, Any Country",
  "addressStreetAddress": "Any Street 1",
  "addressPostalCode": "12345",
  "addressCity": "Any City",
  "addressCountry": "Any Country",
  "source": "SAP",
  "id": "text"
}

Overwrites the meta information of an existing contact

PUT/api/v1/contacts/{contactId}

Path parameters

contactId*string

Id of the contact

Body

application/jsontext/jsonapplication/*+json

Request body

displayNamenullable string

DisplayName of the contact

Example: "John Doe"

jobTitlenullable string

JobTitle of the contact

Example: "Software Developer"

departmentnullable string

Department of the contact

Example: "Development"

companyNamenullable string

Name of company assosiated with the contact

Example: "Fantastic Company Inc."

mailAddressesnullable array of string

Email addresses of the contact

imAddressesnullable array of string

Instant messaging addresses of the contact. Used for initiating a chat in Teams. If multiple imAddresses provided, the first one is used for intite a chat. If not provided the first eMail address of the contact is used.

mobilePhoneNumbersnullable array of string

Mobile phone numbers of the contact

businessPhoneNumbersnullable array of string

Business phone numbers of the contact

homePhoneNumbersnullable array of string

Home phone numbers of the contact

addressFullStringnullable string

Full address of the contact. If this is set it is used for displaying the address in the contact card. If not set the address is build from the other address properties.

Example: "Any Street 1, 12345 Any City, Any Country"

addressStreetAddressnullable string

Street address of the contact

Example: "Any Street 1"

addressPostalCodenullable string

Postal code of the contact

Example: "12345"

addressCitynullable string

City of the contact

Example: "Any City"

addressCountrynullable string

Country of the contact

Example: "Any Country"

sourcenullable string

Sub source of the contact. This is used to identify the source of the contact if you are using multiple sources, that are synced into the database.

Example: "SAP"

Response

200404

Contact was successfully updated - full contact info is returned

Body

text/plainapplication/jsontext/json

displayNamenullable string

DisplayName of the contact

Example: "John Doe"

jobTitlenullable string

JobTitle of the contact

Example: "Software Developer"

departmentnullable string

Department of the contact

Example: "Development"

companyNamenullable string

Name of company assosiated with the contact

Example: "Fantastic Company Inc."

mailAddressesnullable array of string

Email addresses of the contact

imAddressesnullable array of string

Instant messaging addresses of the contact. Used for initiating a chat in Teams. If multiple imAddresses provided, the first one is used for intite a chat. If not provided the first eMail address of the contact is used.

mobilePhoneNumbersnullable array of string

Mobile phone numbers of the contact

businessPhoneNumbersnullable array of string

Business phone numbers of the contact

homePhoneNumbersnullable array of string

Home phone numbers of the contact

addressFullStringnullable string

Full address of the contact. If this is set it is used for displaying the address in the contact card. If not set the address is build from the other address properties.

Example: "Any Street 1, 12345 Any City, Any Country"

addressStreetAddressnullable string

Street address of the contact

Example: "Any Street 1"

addressPostalCodenullable string

Postal code of the contact

Example: "12345"

addressCitynullable string

City of the contact

Example: "Any City"

addressCountrynullable string

Country of the contact

Example: "Any Country"

sourcenullable string

Sub source of the contact. This is used to identify the source of the contact if you are using multiple sources, that are synced into the database.

Example: "SAP"

idnullable string

Request

JavaScriptCurlPython

const response = await fetch('/api/v1/contacts/{contactId}', {
    method: 'PUT',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

200

{
  "displayName": "John Doe",
  "jobTitle": "Software Developer",
  "department": "Development",
  "companyName": "Fantastic Company Inc.",
  "mailAddresses": [
    "[e-mail]"
  ],
  "imAddresses": [
    "[e-mail]"
  ],
  "mobilePhoneNumbers": [
    "[phone]"
  ],
  "businessPhoneNumbers": [
    "[phone]"
  ],
  "homePhoneNumbers": [
    "[phone]"
  ],
  "addressFullString": "Any Street 1, 12345 Any City, Any Country",
  "addressStreetAddress": "Any Street 1",
  "addressPostalCode": "12345",
  "addressCity": "Any City",
  "addressCountry": "Any Country",
  "source": "SAP",
  "id": "text"
}

Updates provided meta information of an existing contact

PATCH/api/v1/contacts/{contactId}

Path parameters

contactId*string

Id of the contact

Body

application/jsontext/jsonapplication/*+json

Request body

displayNamenullable string

DisplayName of the contact

Example: "John Doe"

jobTitlenullable string

JobTitle of the contact

Example: "Software Developer"

departmentnullable string

Department of the contact

Example: "Development"

companyNamenullable string

Name of company assosiated with the contact

Example: "Fantastic Company Inc."

mailAddressesnullable array of string

Email addresses of the contact

imAddressesnullable array of string

Instant messaging addresses of the contact. Used for initiating a chat in Teams. If multiple imAddresses provided, the first one is used for intite a chat. If not provided the first eMail address of the contact is used.

mobilePhoneNumbersnullable array of string

Mobile phone numbers of the contact

businessPhoneNumbersnullable array of string

Business phone numbers of the contact

homePhoneNumbersnullable array of string

Home phone numbers of the contact

addressFullStringnullable string

Full address of the contact. If this is set it is used for displaying the address in the contact card. If not set the address is build from the other address properties.

Example: "Any Street 1, 12345 Any City, Any Country"

addressStreetAddressnullable string

Street address of the contact

Example: "Any Street 1"

addressPostalCodenullable string

Postal code of the contact

Example: "12345"

addressCitynullable string

City of the contact

Example: "Any City"

addressCountrynullable string

Country of the contact

Example: "Any Country"

sourcenullable string

Sub source of the contact. This is used to identify the source of the contact if you are using multiple sources, that are synced into the database.

Example: "SAP"

Response

200404

Contact was successfully updated - full contact info is returned

Body

text/plainapplication/jsontext/json

displayNamenullable string

DisplayName of the contact

Example: "John Doe"

jobTitlenullable string

JobTitle of the contact

Example: "Software Developer"

departmentnullable string

Department of the contact

Example: "Development"

companyNamenullable string

Name of company assosiated with the contact

Example: "Fantastic Company Inc."

mailAddressesnullable array of string

Email addresses of the contact

imAddressesnullable array of string

Instant messaging addresses of the contact. Used for initiating a chat in Teams. If multiple imAddresses provided, the first one is used for intite a chat. If not provided the first eMail address of the contact is used.

mobilePhoneNumbersnullable array of string

Mobile phone numbers of the contact

businessPhoneNumbersnullable array of string

Business phone numbers of the contact

homePhoneNumbersnullable array of string

Home phone numbers of the contact

addressFullStringnullable string

Full address of the contact. If this is set it is used for displaying the address in the contact card. If not set the address is build from the other address properties.

Example: "Any Street 1, 12345 Any City, Any Country"

addressStreetAddressnullable string

Street address of the contact

Example: "Any Street 1"

addressPostalCodenullable string

Postal code of the contact

Example: "12345"

addressCitynullable string

City of the contact

Example: "Any City"

addressCountrynullable string

Country of the contact

Example: "Any Country"

sourcenullable string

Sub source of the contact. This is used to identify the source of the contact if you are using multiple sources, that are synced into the database.

Example: "SAP"

idnullable string

Request

JavaScriptCurlPython

const response = await fetch('/api/v1/contacts/{contactId}', {
    method: 'PATCH',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

200

{
  "displayName": "John Doe",
  "jobTitle": "Software Developer",
  "department": "Development",
  "companyName": "Fantastic Company Inc.",
  "mailAddresses": [
    "[e-mail]"
  ],
  "imAddresses": [
    "[e-mail]"
  ],
  "mobilePhoneNumbers": [
    "[phone]"
  ],
  "businessPhoneNumbers": [
    "[phone]"
  ],
  "homePhoneNumbers": [
    "[phone]"
  ],
  "addressFullString": "Any Street 1, 12345 Any City, Any Country",
  "addressStreetAddress": "Any Street 1",
  "addressPostalCode": "12345",
  "addressCity": "Any City",
  "addressCountry": "Any Country",
  "source": "SAP",
  "id": "text"
}

Deletes an existing contact

DELETE/api/v1/contacts/{contactId}

Path parameters

contactId*string

Id of the contact

Response

200204404

Success

Request

JavaScriptCurlPython

const response = await fetch('/api/v1/contacts/{contactId}', {
    method: 'DELETE',
    headers: {},
});
const data = await response.json();

You can download a sample Postman Collection here:

22KB

Unified Contacts Documentation.postman_collection.json