Left ArrowReturn to Mitel.com
Header Logo

Developer Portal

CloudLink Account

In order to utilize the CloudLink API, you must:

  • Have a CloudLink account.

  • Have an account administrator user that can be used to obtain authorization token

  • If you are utilizing an integration with a Mitel product such as a PBX, MiCollab, or MiContact Center, and wish to make use of that integration with the API, the user used to access the API must be associated with the account where the integrations are configured.                

If you do not have a CloudLink account, login to MiAccess and click ‘CloudLink Accounts Console’ on the navigation menu to automatically create your account. For more information on creating CloudLink accounts and users, please see the CloudLink Accounts documentation found here.

If you are not an existing Mitel Authorized Partner, you can apply to join the Mitel Solutions Alliance Program which offers access to the CloudLink platform for third-party developers.

REST Basics

While this guide will walk you through how to use the CloudLink API and explain at a high level the basic concepts of REST, it is recommended that you read a more comprehensive guide such as this one here or obtain formal training.

They key concepts that you'll need to know for REST are:

Client

This is the person or application using the API. This could be your web browser, your custom built application, or a dedicated API tool such as Postman.

Resource

Any object that the API can interact with. In the Mitel world, this can be something like a user, a voice call, a chat conversation, or even a single unique message. Resources are typically accessed using 'endpoints', formatted as a URL. For example, the full resource path for a Mitel chat conversation would follow the format of https://chat.api.mitel.io/2017-09-01/conversations/{conversationId} where:

https://chat.api.mitel.io = The host

/2017-09-01 = The base path

/conversations = The resource path

/{conversationId} = The unique identifier for the specific resource being accessed

Operation

This is the action being performed on the resource (create, read, update, delete). REST works over HTTP and uses HTTP methods or 'verbs' like:

  • GET - Used when you are requesting information

  • POST - Indicates you are providing information, typically to create a new object

  • PUT - Typically indicates you are updating information for a pre-existing object

  • DELETE - Used when you are deleting an object

There are other HTTP methods, however those are the most common and with very few exceptions, the only HTTP methods that the Mitel API uses.

An example to return a list of users with their various properties would be: GET https://admin.api.mitel.io/2017-09-01/users

Query Parameters

Query parameters can be used with certain GET operations and allow you to provide additional instructions regarding what kind of data you need. The available query parameters for a GET operation are outlined in the API Documentation, however a few examples are:

  • $search - An open text based search

  • $filter - Allows filtering for specific values in a specified property

  • $expand - Lets you expand an attribute that would have otherwise been closed

  • $orderby - Lets you indicate how you wish the returned data to be sorted

  • $top - The number of items to include in the returned data

These parameters will typically support OData operators like eq, ne, gt, lt, ge, and le (equal, not equal, greater than, less than, greater than or equal to, less than or equal to). An example to return a list of users with a specific email address would be: GET https://admin.api.mitel.io/2017-09-01/users/$filter=email eq 'bob@email.com'

Headers & Bodies

Note: This information is covered in more detail below.

Headers include additional information about the API call, such as the format of the data being sent and expected in response, and in Mitel's case it also includes the authentication token and information to identify the application making the API call.

A Request Body is the data being sent with the API call, typically for POST (create) and PUT (update) operations. A Response Body is the data that is returned from the API call, which can be a simple HTTP status code (e.g. HTTP 200 Success) or in the case of a GET operation, the properties of the object you requested. In the Mitel world, request and response bodies (from GET operations) use the JSON format, though there are a small number of exceptions.

API Call Structure

A very useful tool for designing and testing API calls is Postman, for which we have a library of API calls you can download. To successfully make a call to the CloudLink API, your call will need several things:     

  • Authentication Token - A unique, time sensitive token generated by the Authentication API and used to make most API calls.

  • Endpoint – The destination for the API call, formatted as a URL.

  • Method - Also known as the 'HTTP Verb', this determines if you are creating(POST), reading(GET), updating(PUT), or deleting(DELETE) something.

  • Headers – Additional instructions for the API call, typically containing information required by the server receiving the call:

    • Authorization – Used to send the authentication token

    • X-Mitel-App – A custom header that identifies the application that is making the API call

    • Content-Type – Outlines the data format expected in the response from the API, and while a good practice to always include, it’s not always strictly required by every endpoint.

  • Request Body – Contains the data that you are sending to the API (in JSON format).

Authentication

Any application or integration built using CloudLink APIs must obtain an authentication token and refresh this token periodically.  Applications/integrations built without this token will be rejected/blocked from using the platform.

IMPORTANT: All custom applications and integrations that require user authentication MUST use the OpenID Connect Flow which is elaborated on in the Authentication API Guide and for which sample code is available. The simple OAuth 2.0 grant method is described below which is useful for authenticating clients (See Admin API Guide) and testing the APIs using tools such as Postman.

Getting a Token (OAuth 2.0)

In order to obtain a token, a request must be made to the Authentication route as shown in the example below. Once a token has been obtained, this token must be used in the Authorization header for all subsequent calls into the other CloudLink REST APIs. Clients must obtain an authentication token to submit requests to the CloudLink Platform REST APIs.

The following is an example of a request to create a new authentication token:

Request: POST https://authentication.dev.api.mitel.io/2017-09-01/token Headers: Content-Type: application/x-www-form-urlencoded Body : grant_type  : password Username    : <Cloudlink Username> Password    : <Cloudlink Password> account_id  : <Account Id Associated with the Cloudlink User>

Response: HTTP 201 (Success) Body : “token_type’       : “bearer” “expires_in”       : 4090, “access_token”     : “eyJhY2NvdW50SWQiOiIxMDU5OTAwNDUiLCJiZWFyZXJUb2tlbiI6I…”, “refresh_token     : “eyJhY2NvdW50SWQiOiIxMDU5OTAwNDUiLCJiZWFyZXJUb2tlbiI6Im…”, “scope”           : “read write”

For more information on different ways to create a token please read the auth API section.

Refreshing a token

Since authentication tokens expire after a set period, they will need to be refreshed periodically. Unlike the initial token, you have the option of using the ‘refresh_token’ provided with the most recent ‘access_token’ to obtain a new token without requiring user credentials. To do this, use the same API call as above with some changes to the request body. Here’s an example: 

Request:  POST https://authentication.dev.api.mitel.io/2017-09-01/token  Headers:  Content-Type: application/x-www-form-urlencoded   Body :  grant_type: refresh_token  refesh_token: “eyJhY2NvdW50SWQiOiIxMDU5OTAwNDUiLCJiZWFyZXJUb2tlbiI6Im…” 

While you can set your workflow to attempt a refresh after the appropriate time has passed, Mitel’s recommended practices for the CloudLink API are: 

  • Initiate the token refresh after receiving an HTTP 401 error on an API call 

  • Retry the failed call and then resume normal function 

  • Include an exit condition in your code to avoid a stuck retry loop if the above continues to fail after a reasonable number of re-attempts. 

    • This is important as Mitel may temporarily disable your CloudLink account if your application makes too many re-attempts! 

Headers

Headers contain important meta-data about your API request, such as what type of data you're sending and receiving, as well as authentication information. While there are variety of headers involved with the various calls to the CloudLink APIs which you can find documented in the official API Documentation, the following headers are typically required for all CloudLink API calls:

Authorization

The authorization header contains the bearer token obtained through the Authentication API, the process for which is described here and again in the Authentication API Guide.

X-Mitel-App

Any application or integration built using CloudLink APIs must contain a unique header that identifies the application to the platform, labelled "X-Mitel-App". Applications or integrations built without this information will be rejected/blocked from using the platform.

The header must follow the following format for all REST API requests:

x-mitel-app: app={appName}/{appVersion};platfom={os}/{osVersion};session={session-id};

  • appName should use a pattern of “app-flavor” in all lower case where:

    • App - Name of the application.

    • Flavor - Values like web, desktop, android, ios, etc.

  • appVersion should use what makes sense for the release or build nomenclature. The suggestion is to follow Semantic Versioning (SemVer) where possible.

  • platform will consist of “os/osVersion” where:

    • os - The platform where the app resides (e.g. windows, android, azure, etc.)

    • osVersion = exact version of the platform (e.g. 10.0.19041)

note: wherever possible, this should be dynamically detected by your app.

  • session will consist of an automatically generated 128-bit GUID for the session ID (e.g. e769f6ec-ceb6-4b98-bab5-2dc0e720426c) that is unique to the specific instance of the application (e.g. a process in a browser, or an app on a desktop), and is immutable for the lifetime of that instance.

Important: The entire header string must be lower case.

The following is an example of this header:

x-mitel-app: app=meetings-desktop/1.0.4/;platform=windows/10;session-id=b49d5f6c-1d31-4816-9c77-3d991c335220;

Content-Type

The content-type is the format of the data being provided in the request body of the API call (often called a MIME type). With the Mitel CloudLink API this will typically be “application/json” however there are exceptions to this rule (e.g. GET Token uses “x-www-form-urlencoded") and it’s not always strictly required. Always refer to the API Documentation for details.

In some cases you may see two references to content-type/contentType, where one is a header indicating the data format of the request body, and the other is included in the request body itself and refers to the data format of a particular object. For example, when creating a chat message you will need to indicate in the Content-Type header that the request body is “application/JSON”, but also indicate in the request body that the chat message is “text/plain”.

Endpoints

An endpoint is the ‘end’ of a communication channel, such as an application making a request or the server that the request is being sent to. In the context of Mitel’s REST API, the endpoint is the URL for the API call that you wish to make. For example, the endpoint for chat conversations is:

https://chat.api.mitel.io/2017-09-01/conversations

This URL consists of three different components:

Host URL - https://chat.api.mitel.com

Base Path - /2017-09-01

Path - /conversations

In some cases you can also include additional query parameters such as filtering, ordering, and explicitly defining which properties you wish to return.

Methods

HTTP Methods, also referred to as HTTP Verbs, indicate what kind of operation you are performing. While there are 8 methods within the REST model, there are only four methods that you will use with the CloudLink API:

GET - Used when 'reading' information about an existing resource. Typically does not require a request body, but usually allows you to use query parameters to search, filter, or otherwise control the data that is returned.

POST - Used when 'creating' a new resource. Typically requires a request body.

PUT - Used when updating an existing resource. Typically requires a request body.

DELETE - Used when deleting an existing resource. Typically does not require a request body.

Request Body

The request body can generally be considered as the content of the API call that you’re making. The request body must follow a set format which is defined in the API Documentation for each endpoint/API call. Here’s an example JSON request body for the “Create Message” endpoint:

{ "body": "Hello World.", "contentType": "text/plain"   "fallbackText": "Something went wrong", }

Some API calls do not require a request body, in which case the information that’s needed to make the API call is included entirely within the HTTP request itself. A good example is when you use the GET Users API call, where you wish to order the results by a last name:

https://admin.api.mitel.io/2017-09-01/accounts/{accountId}/users?$orderby=lastname

When combined with the headers, this is sufficient to complete the API call and no request body is needed.