Devices

Get devices, optionally narrowed by a filter

Return the devices of your company as a paginated JSON list of full device objects — use it to look up, filter or answer questions about the devices themselves. Send an empty body to list everything; add a filter to narrow it. Every filter entry is keyed by a key from getDeviceFilterCatalog (GET /devices/filters-options) and its value is always a clause { "operationType": "INCLUDE" | "EXCLUDE", "values": [...] } — there are no comparison operators (no eq, gt, contains) and never a bare value (illustrative clauses are on the filter parameter). An unknown key is rejected with 400 — the criterion is never silently ignored. Add matchAny: true for OR instead of AND. search is free text over name, serial number, IMEI, owner and custom field values. Device objects are large, so pages are small (max 100), and leave out imeis and macAddress: read them with getDevice, or with exportDevices for many devices. To count devices, one total or a breakdown of up to 20 filters, use countDevices instead. To extract the whole inventory as a CSV file (spreadsheet, download, report), use exportDevices instead, or exportInventory for a file of devices and the employees holding them, with no device code. Retired devices are left out unless the filter has an availableStatus clause: INCLUDE keeps only the statuses it lists, EXCLUDE every other status, retired ones included. apnsTopic (macOS, iOS, iPadOS) is the uuid of the APNs certificate topic the device enrolled under, null when the MDM is not on.

POST

devices

curl --request POST \
  --url https://api.getprimo.com/devices/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "filter": {},
  "matchAny": true,
  "search": "<string>",
  "page": 1,
  "perPage": 25
}
'

import requests

url = "https://api.getprimo.com/devices/search"

payload = {
    "filter": {},
    "matchAny": True,
    "search": "<string>",
    "page": 1,
    "perPage": 25
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({filter: {}, matchAny: true, search: '<string>', page: 1, perPage: 25})
};

fetch('https://api.getprimo.com/devices/search', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.getprimo.com/devices/search",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'filter' => [
        
    ],
    'matchAny' => true,
    'search' => '<string>',
    'page' => 1,
    'perPage' => 25
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://api.getprimo.com/devices/search"

	payload := strings.NewReader("{\n  \"filter\": {},\n  \"matchAny\": true,\n  \"search\": \"<string>\",\n  \"page\": 1,\n  \"perPage\": 25\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.getprimo.com/devices/search")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"filter\": {},\n  \"matchAny\": true,\n  \"search\": \"<string>\",\n  \"page\": 1,\n  \"perPage\": 25\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.getprimo.com/devices/search")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"filter\": {},\n  \"matchAny\": true,\n  \"search\": \"<string>\",\n  \"page\": 1,\n  \"perPage\": 25\n}"

response = http.request(request)
puts response.read_body

{
  "data": [
    {
      "id": "<string>",
      "tags": [
        "<string>"
      ],
      "isEnrolled": true,
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z",
      "ownerId": "<string>",
      "name": "<string>",
      "serialNumber": "<string>",
      "computerName": "<string>",
      "type": "LAPTOP",
      "condition": "BROKEN",
      "platform": "ANDROID",
      "brand": "<string>",
      "manufacturer": "<string>",
      "modelName": "<string>",
      "modelIdentifier": "<string>",
      "year": 123,
      "osVersion": "<string>",
      "osName": "<string>",
      "buildVersion": "<string>",
      "osUpdateStatus": "UP_TO_DATE",
      "enrolledAt": "2023-11-07T05:31:56Z",
      "disenrolledAt": "2023-11-07T05:31:56Z",
      "purchaseDate": "2023-11-07T05:31:56Z",
      "decommissioningDate": "2023-11-07T05:31:56Z",
      "purchasePriceNoVAT": 123,
      "lockWipeStatus": "LOCKED",
      "edrProvider": "SENTINELONE",
      "connectionStatus": "ONLINE",
      "lastSeenAt": "2023-11-07T05:31:56Z",
      "lastScannedAt": "2023-11-07T05:31:56Z",
      "lastRestartAt": "2023-11-07T05:31:56Z",
      "availableStatus": "IN_USE",
      "enrollmentType": "MANUAL",
      "assetId": "<string>",
      "privateIpAddress": "<string>",
      "publicIpAddress": "<string>",
      "ram": 123,
      "storage": 123,
      "processor": "<string>",
      "cpuType": "<string>",
      "cpuArchitecture": "ARM",
      "osFamily": "DEBIAN",
      "inchScreenSize": 123,
      "keyboardLayout": "FRENCH",
      "batteryHealth": "SERVICE_RECOMMENDED",
      "batteryCycleCount": 123,
      "diskSpaceAvailableStatus": "LOW",
      "percentDiskSpaceAvailable": 123,
      "encrypted": true,
      "encryptedAt": "2023-11-07T05:31:56Z",
      "bootstrapTokenEscrowed": true,
      "bootstrapTokenEscrowedAt": "2023-11-07T05:31:56Z",
      "apnsTopic": "<string>"
    }
  ],
  "pagination": {
    "totalElements": 4503599627370495,
    "totalPages": 4503599627370495,
    "page": 4503599627370496,
    "perPage": 50
  }
}

Key: Read Scope: Company

Authorizations

Authorization

string

header

required

Use your Primo API key in the Authorization header as Bearer <API_KEY>.

Body

application/json

filter

object

One entry per criterion, keyed by the key returned by the filter catalog (GET /devices/filters-options) — a native key such as platform, availableStatus, assigned or mdmStatuses.online, or a custom field id. Every value is a clause { operationType, values } — never a bare value, never an operator like eq. availableStatus takes only IN_USE, IN_STOCK, RETIRED. Whether a device has an owner is assigned (true or false), never a status. Enrollment is mdmStatus: MDM_ON is enrolled, MDM_OFF, MISSING_AGENT, READY_ZTD and MDM_ON_IN_ANOTHER_MDM are the other states. A device name, serial number or IMEI goes in search. The device type is not a criterion: read type on the returned devices. An unknown key is rejected with 400 rather than ignored. Illustrative filters: devices free to hand out → {"availableStatus":{"operationType":"INCLUDE","values":["IN_STOCK"]},"assigned":{"operationType":"INCLUDE","values":[false]}}; devices offline for a week or more → {"mdmStatuses.online":{"operationType":"INCLUDE","values":["INACTIVE"]}}; macOS in use → {"platform":{"operationType":"INCLUDE","values":["MACOS"]},"availableStatus":{"operationType":"INCLUDE","values":["IN_USE"]}}; devices in use to encrypt, as the company metrics count them → {"availableStatus":{"operationType":"INCLUDE","values":["IN_USE"]},"mdmStatuses.encryption":{"operationType":"INCLUDE","values":["NOT_ENCRYPTED"]},"withMdmIssue":{"operationType":"INCLUDE","values":[true]}} (encrypted is what the disk inventory reports, not the compliance verdict); a custom field value → {"<customFieldId>":{"operationType":"INCLUDE","values":["<optionId>"]}}.

Show child attributes

matchAny

boolean

When true, a device matching ANY clause is returned (OR). Omitted or false means every clause must match (AND).

string

Free-text search over device name, serial number, IMEI, owner and custom field values.

page

integer

default:1

Required range: 1 <= x <= 9007199254740991

perPage

integer

default:25

Devices per page (default 25, max 100). Device payloads are large — keep pages small.

Required range: 1 <= x <= 100

Response

default - application/json

data

object[]

required

Show child attributes

pagination

object

required

Show child attributes

Get devices, optionally narrowed by a filter

curl --request POST \
  --url https://api.getprimo.com/devices/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "filter": {},
  "matchAny": true,
  "search": "<string>",
  "page": 1,
  "perPage": 25
}
'

import requests

url = "https://api.getprimo.com/devices/search"

payload = {
    "filter": {},
    "matchAny": True,
    "search": "<string>",
    "page": 1,
    "perPage": 25
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({filter: {}, matchAny: true, search: '<string>', page: 1, perPage: 25})
};

fetch('https://api.getprimo.com/devices/search', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.getprimo.com/devices/search",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'filter' => [
        
    ],
    'matchAny' => true,
    'search' => '<string>',
    'page' => 1,
    'perPage' => 25
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://api.getprimo.com/devices/search"

	payload := strings.NewReader("{\n  \"filter\": {},\n  \"matchAny\": true,\n  \"search\": \"<string>\",\n  \"page\": 1,\n  \"perPage\": 25\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.getprimo.com/devices/search")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"filter\": {},\n  \"matchAny\": true,\n  \"search\": \"<string>\",\n  \"page\": 1,\n  \"perPage\": 25\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.getprimo.com/devices/search")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"filter\": {},\n  \"matchAny\": true,\n  \"search\": \"<string>\",\n  \"page\": 1,\n  \"perPage\": 25\n}"

response = http.request(request)
puts response.read_body

{
  "data": [
    {
      "id": "<string>",
      "tags": [
        "<string>"
      ],
      "isEnrolled": true,
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z",
      "ownerId": "<string>",
      "name": "<string>",
      "serialNumber": "<string>",
      "computerName": "<string>",
      "type": "LAPTOP",
      "condition": "BROKEN",
      "platform": "ANDROID",
      "brand": "<string>",
      "manufacturer": "<string>",
      "modelName": "<string>",
      "modelIdentifier": "<string>",
      "year": 123,
      "osVersion": "<string>",
      "osName": "<string>",
      "buildVersion": "<string>",
      "osUpdateStatus": "UP_TO_DATE",
      "enrolledAt": "2023-11-07T05:31:56Z",
      "disenrolledAt": "2023-11-07T05:31:56Z",
      "purchaseDate": "2023-11-07T05:31:56Z",
      "decommissioningDate": "2023-11-07T05:31:56Z",
      "purchasePriceNoVAT": 123,
      "lockWipeStatus": "LOCKED",
      "edrProvider": "SENTINELONE",
      "connectionStatus": "ONLINE",
      "lastSeenAt": "2023-11-07T05:31:56Z",
      "lastScannedAt": "2023-11-07T05:31:56Z",
      "lastRestartAt": "2023-11-07T05:31:56Z",
      "availableStatus": "IN_USE",
      "enrollmentType": "MANUAL",
      "assetId": "<string>",
      "privateIpAddress": "<string>",
      "publicIpAddress": "<string>",
      "ram": 123,
      "storage": 123,
      "processor": "<string>",
      "cpuType": "<string>",
      "cpuArchitecture": "ARM",
      "osFamily": "DEBIAN",
      "inchScreenSize": 123,
      "keyboardLayout": "FRENCH",
      "batteryHealth": "SERVICE_RECOMMENDED",
      "batteryCycleCount": 123,
      "diskSpaceAvailableStatus": "LOW",
      "percentDiskSpaceAvailable": 123,
      "encrypted": true,
      "encryptedAt": "2023-11-07T05:31:56Z",
      "bootstrapTokenEscrowed": true,
      "bootstrapTokenEscrowedAt": "2023-11-07T05:31:56Z",
      "apnsTopic": "<string>"
    }
  ],
  "pagination": {
    "totalElements": 4503599627370495,
    "totalPages": 4503599627370495,
    "page": 4503599627370496,
    "perPage": 50
  }
}

Get started

API Reference

Get devices, optionally narrowed by a filter

Authorizations

Body

Response