Multiple API reference docs

Admin API
1

Hi,

I am researching on the APIs to get users on an account but I could see multiple API docs for the same API with some variations. I wanted to check, which API document is correct and which API should I look into if I need to get Job Title, emailId, Name, phone number and presence for all the users on an account?

Thanks,
Tanvi

2

Hi Tanvi!

The documentation for the Admin API can be confusing, given all the variations of “GET Users” available (we’re working on it). They do have different functionality, though. For example, this just returns a list of users that you have permissions to see based on your user role:

GET https://admin.dev.api.mitel.io/2017-09-01/accounts/{account_id}/users

This call does the same thing, but it expands the tags associated with the users:

GET https://admin.dev.api.mitel.io/2017-09-01/accounts/{account_id}/users/tags

To get the information that you’re looking for, you will want to use the first call above to retrieve the basic user info (Documentation).

From there, we need to lookup presence using a “principalid”. How we get that depends on what you’re trying to do. Are you looking for just user presence, chat presence, presence of a device associated with them on a PBX(i.e. an extension), or something else?

To just get the user presence, you can use this call, using the UserID from GET Users as the PrincipalID the GET a Presentity call asks for:

GET https://presence.us.dev.api.mitel.io/2017-09-01/presentities/{userID}

You can also get Presence for all users with the following call, although it only returns 10 records at a time by default:

GET https://presence.us.dev.api.mitel.io/2017-09-01/presentities/

It’s worth noting that the PrincipalID is a GUID without dashes, whereas the UserID which you will use as the PrincipalID is a GUID with dashes…so in certain cases you may need to account for that.

3

Moved this topic to the General category.

4

Hi Budd,

Thanks for pointing me to the correct APIs. I did take a look at the APIs and could find most of the fields needed, however, I did not find any field related to Job Title and Department. Could you please let me know if I can get this information from any of the APIs?
Also, I see “role” field, could you please let me know what is the intent of this field?

5

Hi Tanvi!

That information isn’t part of the schema for users. If you log into https://accounts.dev.mitel.io, you’ll see that the user information is really very limited. As for the roles, the possible values are:

USER
ACCOUNT_ADMIN
PARTNER_ADMIN
GLOBAL_ADMIN

You should never see a GLOBAL_ADMIN, but you will always see the first two and I believe in some cases you’ll see PARTNER_ADMIN, such as running GET Users for your partner account or using one of the global GET Users (e.g. https://admin.dev.api.mitel.io/2017-09-01/users).

6

@tanvi.sachdeva - To provide some further information:

When you’re integrating CloudLink with Azure AD (via SCIM) for the purpose of user provisioning, information that we consider extraneous such as “Job Title” and “Department” are not populated into the CloudLink User object. As such, you won’t be able to access it through any GET User calls to the Admin API. If you need that additional information, you will need to query Azure AD for it directly.

I know you had asked what format the data is in (JSON), however you won’t actually see that data unless you setup your own SCIM integration with Azure AD.