Get list of devices¶

GET/devices

Get list of devices.

Required permissionmobile.device:read

Parameters¶

Name	In	Type	Required	Description
`X-Tenant-ID`	header	string (uuid)	Yes	Tenant ID.
`fields`	query	array of string	No	The fields to return in a partial response.
`view`	query	string	No	Type of view to be returned in response. Must be one of: `basic`, `summary`, `full`.
`ids`	query	array of string (uuid)	No	List of IDs.
`operatingSystemIds`	query	array of string (uuid)	No	List of operating system IDs. Must contain at most 100 items.
`sort`	query	array of string	No	Defines how to sort the data. Each item must match the pattern `(^[^:]+$)\|(^[^:]+:(asc\|desc)$)`.
`page`	query	integer	No	The page number to fetch, starting with 1.
`pageSize`	query	integer	No	The size of the page requested.
`pageTotal`	query	boolean	No	Whether the number of pages should be calculated and returned in the response.
`search`	query	string	No	Term to search for in the specified search fields. Must be at most 200 characters long.
`searchFields`	query	array of string	No	List of fields to search in. Defaults to all applicable fields. Each item must be one of: `name`, `modelName`, `osName`.
`platform`	query	array of string (enum)	No	Filter objects by platform. Each item must be one of: `iOS`, `macOS`, `android`, `chrome`, `windows`.
`managementType`	query	array of string	No	Filter objects by management type. Each item must be at most 100 characters long.
`managedState`	query	array of string (enum)	No	Filter objects by management status. Each item must be one of: `notManaged`, `managed`, `decommissioned`, `checkedOut`, `wiped`, `enrolling`.
`compliant`	query	boolean	No	Filter objects by compliance status.
`violationSeverity`	query	array of string (enum)	No	Filter objects by compliance violation severity. Each item must be one of: `low`, `medium`, `high`.
`healthState`	query	array of string (enum)	No	Filter objects by health status. Each item must be one of: `green`, `amber`, `red`.
`ownershipType`	query	array of string (enum)	No	Filter objects by device owner. Each item must be one of: `corporate`, `employee`.
`createdBefore`	query	string	No	Find devices created before the given date and time (UTC) or within a time interval relative to the current date and time (exclusive).
`createdAfter`	query	string	No	Find devices created after the given date and time (UTC) or within a time interval relative to the current date and time (inclusive).
`lastSeenBefore`	query	string	No	Find devices last seen before the given date and time (UTC) or within a time interval relative to the current date and time (exclusive).
`lastSeenAfter`	query	string	No	Find devices last seen after the given date and time (UTC) or within a time interval relative to the current date and time (inclusive).
`deviceGroupIds`	query	array of string (uuid)	No	List of device group IDs.
`assignedPersonIds`	query	array of string (uuid)	No	Filter mobile devices by the assigned users' IDs. Must contain at most 100 items.

Request samples¶

cURLPythonPowerShellGoJavaScript

curl -X GET "https://api-<data-region>.central.sophos.com/mobile/v1/devices" -H "Authorization: Bearer <access-token>" -H "X-Tenant-ID: <tenant-id>"

import requests

response = requests.get(
    "https://api-<data-region>.central.sophos.com/mobile/v1/devices",
    headers={
        "Authorization": "Bearer <access-token>",
        "X-Tenant-ID": "<tenant-id>",
    },
)
print(response.json())

$headers = @{
    "Authorization" = "Bearer <access-token>"
    "X-Tenant-ID" = "<tenant-id>"
}
Invoke-RestMethod -Method GET -Uri "https://api-<data-region>.central.sophos.com/mobile/v1/devices" -Headers $headers

package main

import (
    "fmt"
    "io"
    "net/http"
)

func main() {
    req, err := http.NewRequest("GET", "https://api-<data-region>.central.sophos.com/mobile/v1/devices", nil)
    if err != nil {
        panic(err)
    }
    req.Header.Set("Authorization", "Bearer <access-token>")
    req.Header.Set("X-Tenant-ID", "<tenant-id>")

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}

const response = await fetch("https://api-<data-region>.central.sophos.com/mobile/v1/devices", {
  method: "GET",
  headers: {
    "Authorization": "Bearer <access-token>",
    "X-Tenant-ID": "<tenant-id>",
  },
});
const data = await response.json();
console.log(data);

Responses¶

`200` — List of mobile devices.¶

Response fields

itemsarray of objectrequired

List of mobile devices.

Mobile device response.

Show child attributesHide child attributes

idstring (uuid)required

ID of the mobile device.

tenantobjectrequired

Tenant this resource belongs to.

Show child attributesHide child attributes

idstring (uuid)required

namestring

availableActionsarray of string

List of actions that can be performed for the mobile device.

namestring

Name of the mobile device.
Must be at most 255 characters long.

descriptionstring

Description of the mobile device.
Must be at most 500 characters long.

phoneNumberstring

Phone number of the user assigned to the mobile device.
Must match the pattern ^(\+?\d+|.{0})$. Must be at most 50 characters long.

emailstring

The email address assigned to the device if there's no user assigned.
Must be at most 255 characters long.

assignedPersonobject

Assigned user to a mobile device.

Show child attributesHide child attributes

idstring (uuid)required

The user's ID in Sophos Central.

namestring

The user's name.
Must be at most 255 characters long.

emailstring

The user's email address.
Must be at most 255 characters long.

healthStateobject

Health status of a mobile device.

Show child attributesHide child attributes

statestring (enum)

The health status of a mobile device.
Must be one of: green, amber, red.

modestring (enum)

The health status mode.
Must be one of: automatic, manual.

ownershipTypestring (enum)

The ownership type of the mobile device.
Must be one of: corporate, employee.

createdByobject

Principal reference.

Show child attributesHide child attributes

idstring (uuid)

Principal ID.

typestring (enum)required

Principal type.
Must be one of: user, service, system.

accountIdstring (uuid)

Account ID.

accountTypestring (enum)

Account type.
Must be one of: partner, tenant, organization.

namestring

Principal name or email.

updatedByobject

Principal reference.

Show child attributesHide child attributes

idstring (uuid)

Principal ID.

typestring (enum)required

Principal type.
Must be one of: user, service, system.

accountIdstring (uuid)

Account ID.

accountTypestring (enum)

Account type.
Must be one of: partner, tenant, organization.

namestring

Principal name or email.

createdAtstring (date-time)

The time when the device was created.

updatedAtstring (date-time)

The time when the device was last updated.

lastSeenAtstring (date-time)

The last time the device contacted Sophos Mobile.

smcAppLastSeenAtstring (date-time)

The last sync time of the Sophos Mobile Control app.

ixmAppLastSeenAtstring (date-time)

The last sync time of the Intercept X for Mobile app.

complianceobject

Mobile device compliance status.

Show child attributesHide child attributes

compliantbooleanrequired

Whether the device is compliant.

severitystring (enum)

The highest severity of a compliance violation.
Must be one of: low, medium, high.

modelNamestring

Model name of the mobile device.
Must be at most 255 characters long.

externalIdstring

External ID of the mobile device.
Must be at most 255 characters long.

managementTypestring

The management type of the mobile device.
Must be at most 255 characters long.

supervisedboolean

Whether the device is supervised.

managedStatestring (enum)

The management status of a mobile device.
Must be one of: notManaged, managed, decommissioned, checkedOut, wiped, enrolling.

logLevelstring (enum)

The verbosity of the Sophos Mobile app logging.
Must be one of: error, warn, info, debug, trace.

osobject

Mobile operating system object.

Show child attributesHide child attributes

idstring (uuid)required

ID of the operating system.

versionstringrequired

The operating system version.

namestringrequired

The name of the operating system.

platformstring (enum)required

The device platform, i.e. the operating system.
Must be one of: iOS, macOS, android, chrome, windows.

majorVersionstring

OS major version.

minorVersionstring

OS minor version.

patchVersionstring

OS patch version.

deviceGroupobject

A device group reference.

Show child attributesHide child attributes

idstring (uuid)required

Unique ID of the device group.

namestring

The device group name.

scanResultSummaryobject

Overview of IXM scan results.

Show child attributesHide child attributes

lastScannedAtstring (date-time)

The time of the scan.

suspiciousCountinteger

The number of suspicious elements.

maliciousCountinteger

The number of malicious elements.

puaCountinteger

The number of potentially unwanted elements.

lowReputationCountinteger

The number of low reputation elements.

pagesobjectrequired

Show child attributesHide child attributes

currentintegerrequired

The 1-based page number being returned.

sizeintegerrequired

The size of the page being returned.

totalinteger

(Optional) The total number of pages that exist, if pageTotal=true in the request.

itemsinteger

(Optional) The total number of items across all pages.

maxSizeintegerrequired

The maximum page size that can be requested.

Errors¶

Status	Meaning
`400`	Invalid request.
`401`	Unauthorized.
`403`	Forbidden.
`429`	Too many requests. See Retry-After header.
`500`	Internal server error.

All error responses share the same shape — see the error response object.

Response examples¶

`200`¶

{
  "items": [
    {
      "id": "c9c9b03c-5cf7-4fe1-93bb-246afc9044d2",
      "tenant": {
        "id": "b8a75c7d-7492-4009-9f95-8c815551dc55",
        "name": "The name of the tenant"
      },
      "availableActions": [
        "unenroll",
        "sync",
        "get-logs",
        "send-message"
      ],
      "assignedPerson": {
        "id": "9f059011-84c7-4849-ae2e-d0563743e485",
        "internalId": "670e793648a7e63f0443ba93",
        "name": "Peter Smith",
        "email": "peter.smith@example.org"
      },
      "name": "My device",
      "compliance": {
        "compliant": false,
        "severity": "high"
      },
      "managedState": "managed",
      "ownershipType": "corporate",
      "healthState": {
        "state": "amber",
        "mode": "automatic"
      },
      "managementType": "ixm",
      "os": {
        "id": "c9c9b03c-5cf7-4fe1-93bb-246afc9044d2",
        "version": "12.0.1",
        "name": "iOS 12.0.1",
        "platform": "ios",
        "majorVersion": 12,
        "minorVersion": 0,
        "patchVersion": 1
      }
    },
    {
      "id": "c9c9b03c-5cf7-4fe1-93bb-246afc9044d4",
      "tenant": {
        "id": "b8a75c7d-7492-4009-9f95-8c815551dc55",
        "name": "The name of the tenant"
      },
      "name": "Example Android",
      "email": "somebody@example.com",
      "compliance": {
        "compliant": false,
        "severity": "high"
      },
      "managementType": "notManaged",
      "managedState": "notManaged",
      "os": {
        "id": "c9c9b03c-5cf7-4fe1-93bb-246afc9044d2",
        "version": "12.0.1",
        "name": "iOS 12.0.1",
        "platform": "ios",
        "majorVersion": 12,
        "minorVersion": 0,
        "patchVersion": 1
      }
    }
  ],
  "pages": {
    "current": 1,
    "size": 50,
    "maxSize": 500
  }
}

See the guide for a narrative walkthrough of this API.

Get list of devices¶

Parameters¶

Request samples¶

Responses¶

200 — List of mobile devices.¶

Errors¶

Response examples¶

200¶

`200` — List of mobile devices.¶

`200`¶