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

Path parameters

contactIdstringRequired

Id of the contact

Responses

200

Contact successfully found and returned

text/plainapplication/jsontext/json

404

Contact with id not found

get

HTTPcURLJavaScriptPython

GET /api/v1/contacts/{contactId} HTTP/1.1
Host: 
Accept: */*

{
  "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

Body

application/jsontext/jsonapplication/*+json

Model that contains meta information about a contact that are necessary for CRUD operations

displayNamestring | nullableOptional

DisplayName of the contact

Example: John Doe

jobTitlestring | nullableOptional

JobTitle of the contact

Example: Software Developer

departmentstring | nullableOptional

Department of the contact

Example: Development

companyNamestring | nullableOptional

Name of company assosiated with the contact

Example: Fantastic Company Inc.

mailAddressesstring[] | nullableOptional

Email addresses of the contact

Example: ["[e-mail]"]

imAddressesstring[] | nullableOptional

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.

Example: ["[e-mail]"]

mobilePhoneNumbersstring[] | nullableOptional

Mobile phone numbers of the contact

Example: ["[phone]"]

businessPhoneNumbersstring[] | nullableOptional

Business phone numbers of the contact

Example: ["[phone]"]

homePhoneNumbersstring[] | nullableOptional

Home phone numbers of the contact

Example: ["[phone]"]

addressFullStringstring | nullableOptional

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

addressStreetAddressstring | nullableOptional

Street address of the contact

Example: Any Street 1

addressPostalCodestring | nullableOptional

Postal code of the contact

Example: 12345

addressCitystring | nullableOptional

City of the contact

Example: Any City

addressCountrystring | nullableOptional

Country of the contact

Example: Any Country

sourcestring | nullableOptional

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

idstring | nullableOptional

Unique identifier of the contact

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

Responses

200

Success

text/plainapplication/jsontext/json

201

Contact was successfully created

409

Contact with id already exists

post

HTTPcURLJavaScriptPython

POST /api/v1/contacts HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 563

{
  "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": "sap_28648f3b-8a60-4ded-a2df-5f303a74a17a"
}

application/jsontext/jsonapplication/*+json

{
  "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

Path parameters

contactIdstringRequired

Id of the contact

Body

application/jsontext/jsonapplication/*+json

Model that contains meta information about a contact that are necessary for CRUD operations

displayNamestring | nullableOptional

DisplayName of the contact

Example: John Doe

jobTitlestring | nullableOptional

JobTitle of the contact

Example: Software Developer

departmentstring | nullableOptional

Department of the contact

Example: Development

companyNamestring | nullableOptional

Name of company assosiated with the contact

Example: Fantastic Company Inc.

mailAddressesstring[] | nullableOptional

Email addresses of the contact

Example: ["[e-mail]"]

imAddressesstring[] | nullableOptional

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.

Example: ["[e-mail]"]

mobilePhoneNumbersstring[] | nullableOptional

Mobile phone numbers of the contact

Example: ["[phone]"]

businessPhoneNumbersstring[] | nullableOptional

Business phone numbers of the contact

Example: ["[phone]"]

homePhoneNumbersstring[] | nullableOptional

Home phone numbers of the contact

Example: ["[phone]"]

addressFullStringstring | nullableOptional

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

addressStreetAddressstring | nullableOptional

Street address of the contact

Example: Any Street 1

addressPostalCodestring | nullableOptional

Postal code of the contact

Example: 12345

addressCitystring | nullableOptional

City of the contact

Example: Any City

addressCountrystring | nullableOptional

Country of the contact

Example: Any Country

sourcestring | nullableOptional

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

Responses

200

Contact was successfully updated - full contact info is returned

text/plainapplication/jsontext/json

404

Contact with id not found

put

HTTPcURLJavaScriptPython

PUT /api/v1/contacts/{contactId} HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 515

{
  "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"
}

application/jsontext/jsonapplication/*+json

{
  "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

Path parameters

contactIdstringRequired

Id of the contact

Body

application/jsontext/jsonapplication/*+json

Model that contains meta information about a contact that are necessary for CRUD operations

displayNamestring | nullableOptional

DisplayName of the contact

Example: John Doe

jobTitlestring | nullableOptional

JobTitle of the contact

Example: Software Developer

departmentstring | nullableOptional

Department of the contact

Example: Development

companyNamestring | nullableOptional

Name of company assosiated with the contact

Example: Fantastic Company Inc.

mailAddressesstring[] | nullableOptional

Email addresses of the contact

Example: ["[e-mail]"]

imAddressesstring[] | nullableOptional

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.

Example: ["[e-mail]"]

mobilePhoneNumbersstring[] | nullableOptional

Mobile phone numbers of the contact

Example: ["[phone]"]

businessPhoneNumbersstring[] | nullableOptional

Business phone numbers of the contact

Example: ["[phone]"]

homePhoneNumbersstring[] | nullableOptional

Home phone numbers of the contact

Example: ["[phone]"]

addressFullStringstring | nullableOptional

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

addressStreetAddressstring | nullableOptional

Street address of the contact

Example: Any Street 1

addressPostalCodestring | nullableOptional

Postal code of the contact

Example: 12345

addressCitystring | nullableOptional

City of the contact

Example: Any City

addressCountrystring | nullableOptional

Country of the contact

Example: Any Country

sourcestring | nullableOptional

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

Responses

200

Contact was successfully updated - full contact info is returned

text/plainapplication/jsontext/json

404

Contact with id not found

patch

HTTPcURLJavaScriptPython

PATCH /api/v1/contacts/{contactId} HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 515

{
  "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"
}

application/jsontext/jsonapplication/*+json

{
  "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

Path parameters

contactIdstringRequired

Id of the contact

Responses

200

Success

204

Contact was successfully deleted

404

Contact with id not found

delete

HTTPcURLJavaScriptPython

DELETE /api/v1/contacts/{contactId} HTTP/1.1
Host: 
Accept: */*

No content

You can download a sample Postman Collection here:

22KB

Unified Contacts Documentation.postman_collection.json