Header Logo

Developer Portal

First Steps

Important: There are certification and training requirements for Mitel Partners using the CloudLink platform. Mitel customers Please see relevant information below.

Depending on what you are looking to do, and what role you play in your organization, where you start and what resources you need will vary. With that in mind, three "Getting Started Guides" are provided here, each targeted towards a different group.

Beginners - For those working in a technical capacity, but don't have much experience working with an API.

Developers - For those who sling code, know their way around an API, and are looking to get right into things.

Services & Sales - For those who need to know what the Mitel API is all about so they can understand how it can be used and the value it provides.

Training & Certification

Required Certifications

All developers who wish to work with Mitel's CloudLink platform must have successfully completed both PBX certification and CloudLink Onboarding certification for the PBX:

Recommended Training

While not strictly required in order to make use of the CloudLink APIs, when integrating with a Mitel CloudLink enabled application the following training is recommended:

Supporting Documentation

Documentation for all Mitel products and platforms can be found in the Mitel Document Center and contains a wealth of information on every aspect of Mitel's portfolio. When using the CloudLink platform, the following general purpose documentation may be useful:

Initial Setup

CloudLink Account

Mitel Partners must complete the certification requirements outlined above and have successfully deployed a PBX with connected CloudLink Gateway, during which process account details will be provided.

Mitel customers can obtain CloudLink account information through a Mitel Authorized Partner. To locate a Mitel Authorized Partner or service provider in your area click here.

Development Environments

Mitel recommends creating a dedicated development environment for any application or integration development on the CloudLink platform. Mitel Partners with a Mitel Partner CloudLink Account can create their own sub-accounts which can be configured as needed, including deploying a CloudLink Gateway and PBX.

Rookies

Regardless of what role you play in your organization, if you've never worked with an API before and want to know how to start using it, this is the place for you! There are several key concepts which we will briefly cover here, however the assumption is that you have an existing familiarity with certain fundamental technology concepts such as HTTP and the basic concept of an API.

Step 1 - Basics

Read through the Introduction & Overview article in the Guides & Resources section. This will give you a good idea of what an API is and what the different Mitel APIs can be used for.

Step 2 - REST Concepts

Familiarize yourself with the concepts of REST (Representational State Transfer). Mitel's APIs are RESTful, meaning that they follow the principles of REST . A quick internet search will uncover quite a few excellent introductions to REST, so we will just cover the high level concepts here. There are several key terms to understand when it comes to making a REST API call:

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 Documetation, 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 in Building an API Call.

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.

Step 3 - The Mitel APIs

To familiarize yourself with the details of the APIs you wish to use, you should do the following:

  • Check out the sample use cases documented in the Example Use Cases section

    • Look for more example use case in the SkunkWorks section of the community forum (login required)

  • Read through the Building an API Call section to expand your knowledge of REST further and understand how the Mitel API handles authentication with tokens.

  • Read through the guide for the API(s) that you wish to use in the API Guides section.

Step 4 - Get Rolling

At this stage you should be ready to either read through the Developers section of this article, or get right into things by:

  • Ensuring that you have a CloudLink account (review the 'CloudLink Account' section of Building an API Call) and a valid user login.

  • Checking out the tutorials

  • Downloading the Postman library

    • Once you've followed the instructions to download Postman and import the library, start by going into the Authentication collection and running the POST Token call. If your token expires (you get an "unauthorized" error somewhere) you can then use POST Refresh Token.

    • Once you have a valid token, you can try running other calls as you wish. The GET calls are a good place to start if you're not too sure what you're doing, as this only returns data and doesn't change anything.

Developers

If you're a developer who is familiar with the concept of REST web services and APIs in general, you can get started pretty quickly with developing on Mitel's API. To that end, here are the first steps you should take and the best resources to review:

Step 1 - Familiarization

  1. Check out list of the available APIs in the Overview section of the Introduction & Overview article in the Guides & Resources section.

  2. Ensure that you have a CloudLink account (review the 'CloudLink Account' section of Building an API Call) and a valid user login.

  3. Read through the Best Practices section of the Developing on the API article

  4. Verify that the Mitel product, platform, or application you wish to integrate with is supported by the Mitel API.

Step 2 - Preparation

  1. Review the Building an API Call article to:

    1. Learn how to obtain an authentication bearer token that has to be included in the header of your API calls

    2. Learn about the x-mitel-app header and the format for the data you must include within

  2. Download and import the Postman Library for the Mitel API.

  3. Review the appropriate API Guide(s) for the API(s) that you will be using.

Finally, you can also review the Tutorials if one exists for your use case.

Step 3 - Development

  1. Utilize the API Documentation for the API(s) and specific calls you will be using.

  2. Visit the Community Forum to ask questions, research solutions, and interact with your fellow developers and the Mitel team.

  3. Read the 'Performance Benchmarks' and 'Deployment Process' sections of the Developing on the API article to ensure your application meets Mitel's requirements and deploy your application into production when completed.

Services & Sales

If you are looking for high level, less technical information about the Mitel APIs, there are a few resources which will be useful to you:

Introduction & Overview - This article offers a brief explanation of APIs in general, an overview of the available Mitel APIs, and some examples of what you might use them for.

Use Cases Examples - This article explores several use cases in more detail, outlining at a high level how they could be implemented.

The SkunkWorks - This area of the community forum is where Mitel partners go to brainstorm and ask questions about the feasibility of interesting and unusual use cases. This area of the forum requires you to be logged in.

Product Compatibility - Check to see if the Mitel application or platform you wish to work with is supported by the Mitel APIs.

Postman Library - For those who are feeling a bit adventurous, or are supporting applications built on the Mitel APIs, install Postman and import Mitel's library of API calls. With the Postman library you can quickly and easily test most API calls without requiring any development/coding knowledge.