Empire Telecom · Mitel
How to integrate with Mitel phone systems: the CloudLink cloud APIs (authentication, admin, call control, presence, chat, notifications), the on-premise MiVoice Business gateway, MiCollab, MiContact Center, and what changed after Mitel's 2025 restructuring.
Mitel makes business phone systems that are mostly installed on site or in a private cloud: MiVoice Business, MiVoice MX-ONE, MiVoice Office 400, MiVoice 5000 and the older MiVoice Connect (ShoreTel), plus MiCollab for unified communications and MiContact Center Business for contact centers. Verdict: Mitel's modern public API is CloudLink, a set of REST APIs at *.api.mitel.io with open documentation and a Postman library. It works with any PBX connected through a CloudLink Gateway (MiVoice Business is the main one). Access requires a CloudLink account from a Mitel partner and approval of your app, so it is open documentation with a gated door. The older on-premise interfaces (MiVoice Business Open Integration Gateway, MiContact Center SDK) exist but are licensed and aimed at Mitel's developer partners.
Important: Mitel cloud phone customers (MiCloud Connect) were moved to RingCentral. If your Mitel service is actually MiCloud Connect, see the RingCentral API specification instead.
| Date | Change | What it means for you |
|---|---|---|
| 2021 | RingCentral became the preferred partner for Mitel customers moving to the cloud | New cloud UC goes to RingCentral |
| Q2 2024 | RingCentral took over the MiCloud Connect and Sky UCaaS customer relationships; the partnership became non-exclusive in August 2024 | MiCloud Connect integrations now use RingCentral's APIs |
| 6 July 2024 | MiVoice Connect (formerly ShoreTel) stopped being sold to new systems | No new MiVoice Connect APIs; plan a move |
| 9 March 2025 | Mitel agreed a financial restructuring with its lenders, carried out through Chapter 11 | Day-to-day service and support continued |
| 20 June 2025 | Mitel completed the restructuring: about $1.15 billion of debt removed, control moved from Searchlight Capital to its lenders, Mike Robinson later named CEO | Mitel continues as a going concern focused on on-premise and hybrid systems |
| 2025 | Mitel CX (AI contact center) became generally available (March), Mitel CX 2.0 announced (November); Zoom Workplace integration with Mitel telephony; Workflow Studio (no-code integration) | New contact center work is on Mitel CX |
| 31 Dec 2029 | End of Mitel technical support for MiVoice Connect | Mitel's upgrade path is MiVoice Business |
| Item | Detail |
|---|---|
| API type | CloudLink: REST over HTTPS, JSON. On-premise MiVoice Business OIG: SOAP/XML (call control) and REST/JSON (sessions, data access) |
| Base URLs (CloudLink) | https://authentication.api.mitel.io/2017-09-01, https://admin.api.mitel.io/2017-09-01, https://media.api.mitel.io/2017-09-01, https://presence.api.mitel.io/2017-09-01, https://chat.api.mitel.io/2017-09-01, https://notifications.api.mitel.io/2017-09-01, https://service-delivery.api.mitel.io/2022-01-30 |
| Authentication | OAuth 2.0 style bearer tokens: authorization code with PKCE (OpenID Connect) for user apps, client credentials for server apps, password grant for testing only, refresh tokens. SAML SSO through the Mitel Auth Portal |
| Required header | x-mitel-app: app=<name>/<version>;platform=<os>/<version>;session=<id>; (lower case) on every call |
| Format | JSON; token requests are application/x-www-form-urlencoded |
| Versioning | Date-stamped path segment (2017-09-01; Service Delivery 2022-01-30). Each API serves its own spec at /_spec |
| Query options | OData style: $top, $skip, $filter, $orderby, $search, $expand |
| Sandbox | No shared sandbox. Use a dedicated sub-account with its own CloudLink Gateway and PBX (partners), or join the Mitel Technology Network for lab access |
| Rate limits | No published numbers. Mitel warns it may temporarily disable a CloudLink account that retries too often |
| Webhooks/events | Notifications API: subscriptions delivered by webhook (signed) or WebSocket (MQTT) |
| SDKs | No official client SDKs. Official Postman library and Node.js code samples on GitHub |
| Developer portal | developer.mitel.io |
| Status page | status.mitel.io (CloudLink services by region: US, EU, AP) |
| How to get access | CloudLink account from a Mitel partner (customers) or partner CloudLink account (partners); app approved under the CloudLink API Terms of Use; Mitel Technology Network for on-premise interfaces |
| Product | What to use | Public? |
|---|---|---|
| MiVoice Business (on site or private cloud) | CloudLink APIs through a CloudLink Gateway; or the Open Integration Gateway (OIG) on the local network | CloudLink docs are public; OIG guides are downloadable but development requires MTN membership and Mitel licences |
| MiCollab | Connects to CloudLink for sign-in, user sync and chat, so the CloudLink Admin and Chat APIs apply once it is connected. MiCollab has no separate public API | Yes (via CloudLink) |
| MiVoice MX-ONE, MiVoice 5000, MiVoice Office 400 | CloudLink where a gateway is supported; otherwise CTI/TAPI-style interfaces through the Mitel Technology Network | Partner only for the native interfaces |
| MiVoice Connect (ShoreTel) | No CloudLink API path in Mitel's public material; legacy CTI only; end of support 2029 | Partner only |
| MiCloud Connect | Now RingCentral | See RingCentral |
| MiContact Center Business | MiCC SDK / Open Media REST API on the customer's own server (version 9.0 or later) | Not publicly documented; ask your Mitel partner |
| Mitel CX | Mitel's AI contact center; check with Mitel for its integration options | Check the provider's docs |
| 1 | Get a CloudLink account. Customers get one from their Mitel authorised partner. Partners get one after meeting Mitel's certification requirements and deploying a PBX with a connected CloudLink Gateway. Ask Empire Telecom to arrange this if Empire manages your Mitel system. |
| 2 | Connect the PBX. A CloudLink Gateway (with MiVoice Border Gateway for MiVoice Business) links the phone system to CloudLink. After onboarding, MiVoice Business is configured automatically. Without this, the call and presence APIs have nothing to control. |
| 3 | Join the developer forum. Create an account on the Mitel developer forum for CloudLink API support. |
| 4 | Set up a test account. Mitel recommends a dedicated development environment. Partners can create sub-accounts under their partner account. Third-party developers can join the Mitel Technology Network (MTN), which replaced the older Mitel Solutions Alliance and Unify programs, for CloudLink access and lab equipment. |
| 5 | Register your application. An application (client) has an applicationId (also called clientId), a name, an active flag and its allowed redirectUris. It is usually managed by a PARTNER_ADMIN. For server-to-server use, an account admin creates a client with POST /accounts/{accountId}/clients on the Admin API. |
| 6 | Accept the terms. The CloudLink API Terms of Use require a valid CloudLink account and token, Mitel's approval of your application at its discretion, and say the APIs are currently free. Direct competitors of Mitel may not use them. |
| 7 | Activate the app on the customer account. When you deploy, the app may need to be activated on the target account and its redirect URIs updated. |
| 8 | For on-premise OIG work, join MTN at the Developer Advanced level, register the application and request a certificate through MiAccess, and buy the OIG licences through Mitel's licensing system. A 60-day trial and hosted virtual lab are available. |
All token calls go to https://authentication.api.mitel.io/2017-09-01. Send the returned access_token as Authorization: Bearer <token> on every other API, together with the x-mitel-app header.
| POST /2017-09-01/token Content-Type: application/x-www-form-urlencoded grant_type=password&username=<user>&password=<pass>&account_id=<accountId> |
Response (HTTP 201) includes token_type (bearer), expires_in, access_token, refresh_token and scope. Mitel says user-facing apps must not use this; use OpenID Connect instead.
| 1 | Send the user to the Mitel Auth Portal: https://auth.mitel.io/authorize?client_id=<applicationId>&response_type=code&redirect_uri=<registered URI> (with a code_challenge and code_challenge_method=S256). Or call POST /authorize on the Authentication API directly with client_id, response_type, username, password, account_id, redirect_uri, code_challenge_method and code_challenge. |
| 2 | Exchange the code: |
| POST /2017-09-01/token grant_type=authorization_code&code=<code>&client_id=<applicationId>&code_verifier=<verifier> |
Accounts that use single sign-on (SAML; Mitel officially supports Microsoft Azure / Entra ID as the identity provider) must use the Auth Portal flow.
| POST /2017-09-01/token grant_type=client_credentials&client_id=<clientId>&client_secret=<secret>&account_id=<accountId> |
| Method | Path | What it does |
|---|---|---|
| POST | /token | grant_type=refresh_token&refresh_token=<token> gets a new access token |
| GET | /token | Verify the current token |
| POST | /guest/token | Guest token (principalId, accountId, name) for anonymous users |
| GET | /_spec | The API's own specification |
If a user belongs to more than one account and you leave out account_id, you get HTTP 409. Do not decode tokens yourself; Mitel says their format may change.
All paths below are relative to the base URL for that API (see At a glance). "My account" paths act on the token's own account; /accounts/{accountId}/... paths act on a named account (partner and admin use).
| Method | Path | What it does |
|---|---|---|
| GET | /accounts | List accounts you can see |
| GET | /accounts/{accountId} | One account |
| POST | /accounts | Create an account (partners; Mitel advises against creating accounts by API) |
| PUT | /accounts/{accountId} | Update an account |
| DELETE | /accounts/{accountId} | Delete an account |
| GET | /accounts/tags | Accounts with tags |
| Method | Path | What it does |
|---|---|---|
| GET | /users | Users in my account |
| GET | /accounts/{accountId}/users | Users in a named account |
| GET | /accounts/{accountId}/users/{userId} | One user |
| POST | /users | Create a user in my account |
| PUT | /users/{userId} | Update a user |
| DELETE | /users/{userId} | Delete a user |
| POST | /accounts/{accountId}/users/{userId}/welcome | Send the welcome email |
| PUT / DELETE | /users/{userId}/photo | Upload or remove a user photo |
| GET / POST | /contacts | List or create contacts (CORPORATE, PERSONAL_CONTACT, GUEST, admin types) |
| PUT / DELETE | /contacts/{contactId} | Update or delete a contact |
| GET / POST | /groups | List or create groups |
| PUT / DELETE | /groups/{groupId} | Update or delete a group |
User sync from the PBX is one way: changes made in CloudLink are not pushed back to the PBX.
| Method | Path | What it does |
|---|---|---|
| GET | /accounts/{accountId}/clients | List server clients |
| POST | /accounts/{accountId}/clients | Create a client (name, role such as ACCOUNT_ADMIN, active) |
| PUT | /accounts/{accountId}/clients/{clientId} | Update a client |
| DELETE | /accounts/{accountId}/clients/{clientId} | Delete a client |
Roles are PARTNER_ADMIN, ACCOUNT_ADMIN and USER.
An endpoint is a phone line (for example an extension) on the connected PBX. The device must support CTI.
| Method | Path | What it does |
|---|---|---|
| GET | /endpoints/{endpointId} | Line state |
| PUT | /endpoints/{endpointId} | Change line state: action dnd or messageWaiting, userAvailability (available, busy, dnd, away) |
| GET | /endpoints/{endpointId}/calls | Active calls on the line |
| POST | /endpoints/{endpointId}/calls | Make a call (to, optional from, fromName, timeoutMs) |
| GET | /endpoints/{endpointId}/calls/{callId} | State of one active call |
| PUT | /endpoints/{endpointId}/calls/{callId} | Act on a call (action, for example answer or redirect with a destination) |
| GET / PUT / DELETE | /endpoints/{endpointId}/forwardings | Read, set or clear call forwarding (action such as always, destination, enabled) |
Call states are ringing, connected and completed; causes include newCall, busy and callNotAnswer. You cannot play audio, collect keypad digits, control a softphone or change PBX configuration through CloudLink.
| Method | Path | What it does |
|---|---|---|
| GET | /calls/records | Call history (supports $top, $skip, $filter) |
| GET | /calls/{callId}/records | Records for one call |
| PUT | /calls/records or /calls/{callId}/records | Hide records ({"hide": true}) |
| GET | /recordings | All recordings in the account |
| GET | /recordings/{recordingId} | Recording metadata and file |
| PUT | /recordings/{recordingId} | Update recording label |
| DELETE | /recordings/{recordingId} | Delete a recording |
| GET / POST | /conferences | List or create conferences (type, lobbyPolicy, accessCodeLength) |
| GET / PUT / DELETE | /conferences/{conferenceId} | Read, update or delete a conference |
| POST | /conferences/{conferenceId} | Conference action, for example {"action":"end"} |
| GET / POST | /conferences/{conferenceId}/participants | List or add participants |
| GET | /users/{userId}/conferences | Conferences for a user |
The guides state recording start/stop is not available through the API.
| Method | Path | What it does |
|---|---|---|
| GET | /presentities | Presence for everyone you can see |
| GET | /presentities/{principalId} | Aggregate presence for one user or group |
| PUT | /presentities/{principalId} | Manual override (status, reason); set Available to go back to automatic |
| GET | /presentities/{principalId}/categories/{categoryId} | Sources in a category (phones, externalEngines, acd, calendar) |
| POST | /presentities/{principalId}/categories/{categoryId} | Add a presence source (sourceId, presence) |
| PUT | /presentities/{principalId}/categories/{categoryId}/{sourceId} | Update a source |
Statuses: Available, Busy, Away, DoNotDisturb, Offline, Unknown. Mitel recommends reading aggregate presence and updating sources rather than overriding.
| Method | Path | What it does |
|---|---|---|
| GET / POST | /conversations | List or create conversations (direct, group, or topic stream) |
| GET / PUT / DELETE | /conversations/{conversationId} | Read, update or delete |
| GET / POST | /conversations/{conversationId}/messages | Read or send messages (body, contentType, fallbackText) |
| PUT / DELETE | /conversations/{conversationId}/messages/{messageId} | Edit or delete a message |
| GET / POST | /conversations/{conversationId}/participants | List or add participants |
| POST | /conversations/{conversationId}/participants/{participantId}/typing | Typing indicator (START/STOP) |
| GET / PUT / DELETE | /conversations/{conversationId}/attachments/{attachmentId} | Attachments (up to 10 MB) |
| POST | /conversations/{conversationId}/transcripts | Create a transcript |
| GET | /users/{userId}/conversations | A user's conversations with unread counts (call once at start-up) |
Read-only today, based on TM Forum TMF637, for Mitel distributors.
| Method | Path | What it does |
|---|---|---|
| GET | /agreements and /agreements/{id} | Subscription agreements |
| GET | /products and /products/{id} | Products on agreements |
| GET | /organizations and /organizations/{id} | Parties |
Mitel has announced later phases (creating subscriptions, changing seats, orders, invoices) as planned and subject to change.
OIG is a web server on Mitel Standard Linux that fronts up to 250 MiVoice Business systems for up to 1,500 applications.
| Service | Protocol | Example path |
|---|---|---|
| Session management | SOAP/XML or REST/JSON | /mitel/oig/session/SessionService?wsdl, /mitel/oig/rest/resources/v1/sessions |
| Call control (standard and advanced) | SOAP/XML over HTTPS | /mitel/oig/cc/StandardCCService?wsdl |
| Data access | REST/JSON over HTTPS | /mitel/oig/rest/resources/v1/databases |
Login uses the company name, application name and application password from Mitel registration, plus a local password set on each OIG. Advanced services need a Mitel certificate. Sessions end unless kept alive within 10 minutes.
CloudLink's Notifications API (Notify) delivers changes from the other APIs.
| 1 | Create a subscription: POST https://notifications.api.mitel.io/2017-09-01/subscriptions with applicationId, transport (webhook or websocket), deviceId (your webhook URL, or the MQTT client ID for WebSocket), topic, and optional subjectFilter (regular expression on the resource path), methodFilter (POST, PUT, DELETE), publicationFilter (JSONPath on content) and expiryDateTime. |
| 2 | For WebSocket, call POST /connections with {"transport":"websocket"} to get the connection URL (MQTT). |
| 3 | Manage subscriptions with GET /subscriptions, GET/DELETE /subscriptions/{subscriptionId}. GET /notifications shows delivery history. |
| Topic | Events |
|---|---|
platform-api-media | Call ringing, connected, ended on watched endpoints |
platform-api-presence | Presence changes |
platform-api-conversations | New messages and conversation changes |
platform-api-admin | Users created (POST) or updated (PUT) |
Example subject filters from Mitel's guide: ^/2017-09-01/endpoints/100[0-5] (extensions 1000-1005) and ^/accounts/<accountId>/users with methodFilter: POST (new users).
Verify webhooks: every webhook carries an x-notify-signature header. Compute a SHA-256 HMAC of the body using your applicationId as the key and compare.
On-premise OIG applications poll for events or register an asynchronous callback; MiCC Business integrations use its own SDK.
| Code | Meaning |
|---|---|
| 200 / 201 | Success; token creation returns 201 |
| 401 | Token expired or invalid: refresh the token and retry once |
| 409 | User belongs to several accounts and account_id was not sent |
| 4xx / 5xx | Other errors: check the provider's docs and the /_spec for each API |
$top and $skip on lists such as /calls/records; filter with $filter.x-mitel-app, in lower case.| 1 | Get a token (client credentials for a server job). |
| 2 | GET https://media.api.mitel.io/2017-09-01/calls/records with $filter on the date range and $top for page size. |
| 3 | Repeat with $skip until fewer than $top rows return. |
| 1 | GET /recordings to find the recording (filter by date or call). |
| 2 | GET /recordings/{recordingId} to get its metadata and file. |
| 1 | Use OpenID Connect so each user signs in as themselves. |
| 2 | POST /endpoints/{endpointId}/calls with {"to":"<number>"}, where endpointId is the user's line. |
| 3 | Track the call with a platform-api-media subscription. |
| 1 | POST /subscriptions on Notify with transport: "webhook", deviceId: "<your https URL>", topic: "platform-api-media" and a subjectFilter for the extensions you care about. |
| 2 | Check x-notify-signature on each delivery. |
| 3 | Act on events whose call state is completed. |
| 1 | PUT /endpoints/{endpointId} with {"action":"dnd","enabled":true}. |
| 2 | Or PUT /endpoints/{endpointId}/forwardings with {"action":"always","enabled":true,"destination":"<number>"}. |
| 1 | GET /presentities for the starting state. |
| 2 | Subscribe to platform-api-presence by WebSocket and update tiles as events arrive. |
| 1 | POST /users (or /accounts/{accountId}/users) with name and email. |
| 2 | POST /accounts/{accountId}/users/{userId}/welcome to send the welcome email. |
| 3 | If the user comes from the PBX, add them on the PBX instead; sync is one way from PBX to CloudLink. |
Need a hand? Call Empire Telecom support at (732) 363-9898, email support@empiretelecomnj.com, or open a ticket in the customer portal.