MobileIron Cloud API Basics

System Role

Your implementation of the MobileIron Cloud Integration API supports the following role:

Tenant Admin – Authorized to make calls related to the tenant owned by the admin, such as creating and updating accounts.

Authentication

The MobileIron Cloud Integration APIs use Basic Authentication to authorize API calls. You need to add an authentication header when using a REST tool such as Postman, and when making cURL calls directly. See the examples provided in the sections Getting Account Information and Creating a User in the chapter Making Your First API Calls for how to add authentication to your calls.

NOTE:

Some of the example calls in this guide do not illustrate an authentication component, however, you should add authentication to your actual calls.

GDPR Consideration

If the API user selected to authenticate API calls is associated with a GDPR profile, then MobileIron Cloud obfuscates the specified fields in the GDPR profile that API calls return.

Typical fields include:

•

User ID

•

Person name

•

Email address

•

Phone number

•

MEI

•

Serial Number

•

ICCID

•

MEID

•

esimIdentifier

•

ipAddress

API Limits

If you are using a MobileIron Cloud API call that is not described in this guide, then that call is unpublished and unsupported.

Rows Parameter Limit

MobileIron paginates the results of APIs and limits the maximum number of results returned to 500 per page to avoid performance issues that may occur when retrieving and transferring large data sets.

When making API calls:

Do not send a value greater than 500 for the rows parameter. MobileIron Cloud release 75 and later will return the following error response when encountering API calls that violate the 500 row limit:

400 Bad Request
 {
    "errors": {
        "globalErrors": null, 
        "fieldErrors": [
            {
                "code": "Range", 
                "message": "must be between 1 and 500", 
                "field": "rows"
            }
        ]
    }, 
    "result": null
}

Paginate your API returns. If you are using any published API that takes as input the rows parameter, but your code is not paginating the returned results, then you should change that code to enforce pagination, extracting objects one page at a time. You can change the number of results returned per page by using the rows parameter, and the set of results returned by using the start parameter. See Controlling Results for complete details and examples.

Controlling Results

Because of MobileIron Cloud APIs 500 row limit per page described in API Limits, you may need to use the following parameters to avoid hitting the API limit.

Parameter	Description
rows	Syntax: rows=n Limits the number of records retrieved. For example, `rows=100` returns 100 rows of records. Do not send a value larger than 500 with the rows parameter because the APIs do not permit a value of greater than 500.
start	Syntax: start=n Specifies the record on which to start the return. For example, if you have 200 devices, to get the last 40 devices, use `start=160`.

Parameter

Description

rows

Syntax: rows=n

Limits the number of records retrieved.

For example, rows=100 returns 100 rows of records.

Do not send a value larger than 500 with the rows parameter because the APIs do not permit a value of greater than 500.

start

Syntax: start=n

Specifies the record on which to start the return.

For example, if you have 200 devices, to get the last 40 devices, use start=160.

Examples

You have 12340 devices and you cannot retrieve them all at once because you need to chunk them up into rows of at most 500 to avoid the 500 row limit described in API Limits.

To get first 100 devices:

&rows=100&start=0

To get second 100 devices:

&rows=100&start=100

To get the last 40 devices from the list ;

&rows=100&start=12300

Sorting Results

You can use the sortFields[0].name and sortFields[0].order parameters to sort results. When sort order is not set for an API, the API returns the response sorted for the fastest response.

Parameter	Description
sortFields[0].name	Syntax: sortFields[0].name=field Specifies the field on which to sort. For example, `sortFields[0].name=emailAddress` sorts on the emailAddress field. Here it is URL encoded: `sortFields%5B0%5D.name=emailAddress`
sortFields[0].order	Syntax: sortFields[0].order=[ASC][DESC] Specifies ascending or descending sort order. For example, `sortFields[0].order=ASC` sorts in ascending order. Here it is URL encoded: `sortFields%5B0%5D.order=ASC`

Parameter

Description

sortFields[0].name

Syntax: sortFields[0].name=field

Specifies the field on which to sort.

For example, sortFields[0].name=emailAddress sorts on the emailAddress field.

Here it is URL encoded: sortFields%5B0%5D.name=emailAddress

sortFields[0].order

Syntax: sortFields[0].order=[ASC][DESC]

Specifies ascending or descending sort order.

For example, sortFields[0].order=ASC sorts in ascending order.

Here it is URL encoded: sortFields%5B0%5D.order=ASC

HTTP Response Codes

The API issues the codes listed below in its responses, and issues a “Success” message for successful calls. When a call fails, the API issues a descriptive error message.

200 OK - Success
400 Bad request - The request was invalid. The accompanying error message in the output explains the reason.
401 Unauthorized - Authentication to the API has failed. Authentication credentials are missing or wrong.
403 Forbidden – You are trying to access a resource that does not belong to you.
404 Not found - The requested resource is not found. The accompanying error message explains the reason.
500 Internal Server Error - An internal server error has occurred while processing the request.
502 Bad Gateway - The MobileIron server is not reachable.

Response Types

The API can return responses in JSON.

Common Response Objects

This section contains descriptions of the common response objects returned by the API.

Error

This object represents error response.

{
    "fieldErrors": [
      {
        object(FieldError
)
      }
    ],
    "globalErrors": [
      {
        object(GlobalError
)
      }
    ]
}

Field	Description
Field	Description
fieldErrors[]	object(FieldError ) A list of errors related to request parameters.
globalErrors[]	object(GlobalError ) A list of general errors.

Field

Description

Field

Description

fieldErrors[]

object(FieldError )

A list of errors related to request parameters.

globalErrors[]

object(GlobalError )

A list of general errors.

FieldError

This object represents errors related to request parameters.

{ "code": string, "field": string, "message": string }

Field	Description
code	string HTTP response error code as documented in the API guide.
field	string The request field that has an error.
message	string Localized description of the error message.

Field

Description

code

string

HTTP response error code as documented in the API guide.

field

string

The request field that has an error.

message

string

Localized description of the error message.

GlobalError

This object represents global errors.

{ "code": string, "message": string }

Field	Description
code	string HTTP response error code as documented in the API guide.
message	string Localized description of the error message.

Field

Description

code

string

HTTP response error code as documented in the API guide.

message

string

Localized description of the error message.

The Importance of the Device Space ID

The device space ID is an important value in MobileIron Cloud and is needed to make a variety of device-related API calls. You can get the default device space ID by examining the response of the GET Tenant Metadata call, described in the section, Get Device Enrollment Program (DEP) details by DEP profile ID. You can get a list of all device spaces in a tenant using the Get Device Spaces call. The device space ID appears as shown below in the Get Tenant Metadata call:

"defaultDmPartitionId": 23004,

Note: Device “spaces” were previously named device “partitions” in the MobileIron Cloud user interface, however, the term “partition” remains in API parameters and returns.