{"info":{"_postman_id":"393b7dc9-e14b-4f7f-969e-1297f7fefafd","name":"Ensemble Device API","description":"

Introduction

This API offers the following features:

Find Device by IMEI
Get last known location for a device
Securely wipe a device
Suspend/Unsuspend device
Get whether a device has exceeded any data usage alerts

Overview

Things that the developers should know about

Base URL

All API calls should begin with the URL: https://api.ensemblemdm.com/v1

So, an example of calling our API should look like this:

GET https://api.ensemblemdm.com/v1/usage

Authentication

Interacting with the API requires sending an 'x-api-key' header with each request. To retrieve an API Key, please reach out to us at engineering@conversasolutions.com

header['x-api-key'] = API_KEY\n

NOTE API Keys are unavailable at the moment.

Status Codes

We use conventional HTTP response codes to indicate the success or failure of an API request.

2xx range: success
4xx range: error that failed given the information provided
5xx range: error with our servers (these are rare).

200 - OK

Everything worked as expected.

400 - Bad Request

The request was unacceptable, often due to missing a required parameter or if data you provided fails validation. Check our documentation to confirm that the data type you are sending matches what our server expects.

500, 502, 503, 504 - Server Errors

There was an error on our end. This should be rare, so please reach out to us if you continue to receive these status codes.

Rate limit

Yes. No more than 1000 requests every 100 seconds

\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[{"content":"Introduction","slug":"introduction"},{"content":"Overview","slug":"overview"},{"content":"Base URL","slug":"base-url"},{"content":"Authentication","slug":"authentication"},{"content":"Status Codes","slug":"status-codes"},{"content":"Rate limit","slug":"rate-limit"}],"owner":"6720412","collectionId":"393b7dc9-e14b-4f7f-969e-1297f7fefafd","publishedId":"TzsWrpCd","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"EF5B25"},"publishDate":"2021-07-19T21:07:59.000Z"},"item":[{"name":"/usage","id":"602090c0-efc4-42fa-8ddf-3597a2f15e7e","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"/usage?limit=10&page=2&sort='asc'&to='2021-07-18'&from='2021-07-18'","description":"

Get all the usage data for the API KEY specified in the request header x-api-key

\n","auth":{"type":"apikey","apikey":{"basicConfig":[]},"isInherited":true,"source":{"_postman_id":"393b7dc9-e14b-4f7f-969e-1297f7fefafd","id":"393b7dc9-e14b-4f7f-969e-1297f7fefafd","name":"Ensemble Device API","type":"collection"}},"urlObject":{"path":["usage"],"query":[{"description":{"content":"

Optional. Limits the number of usage objects returned per page. If not provided, a default (and maximum) of 100 items is used. Must be an integer from 1-100.

\n","type":"text/plain"},"key":"limit","value":"10"},{"description":{"content":"

Optional. Indicates which \"page\" of data to return. Must be an integer.

\n","type":"text/plain"},"key":"page","value":"2"},{"description":{"content":"

Optional. By default, 'desc' is the sort order: with the most recent usage at the beginning of the list. Only accepts \"asc\" (ascending) or \"desc\" (descending).

\n","type":"text/plain"},"key":"sort","value":"'asc'"},{"description":{"content":"

Optional. Must be a date string in ISO8601 format. If provided, no usage data that was captured after this date will be returned.

\n","type":"text/plain"},"key":"to","value":"'2021-07-18'"},{"description":{"content":"

Optional. Must be a date string in ISO8601 format. If provided, no usage data that was captured before this date will be returned.

\n","type":"text/plain"},"key":"from","value":"'2021-07-18'"}],"variable":[]}},"response":[{"id":"f15f9d2b-1074-478d-b383-32ad732f8e74","name":"Base request","originalRequest":{"method":"GET","header":[],"url":"/usage"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":null,"cookie":[],"responseTime":null,"body":"{\n \"success\": true,\n \"data\": {\n \"usage\": [\n {\n \"timestamp\": \"2021-07-19T20:37:30.208Z\",\n \"request\": {\n \"url\": \"/location/1234\",\n \"body\": null,\n \"complete\": true,\n \"userAgent\": \"Mozilla/5.0 (Windows NT 10.0)\",\n \"queryParams\": null,\n \"method\": \"GET\",\n \"ip\": \"127.0.0.1\"\n },\n \"response\": {\n \"statusCode\": 404,\n \"statusMessage\": \"Not Found\"\n }\n }\n ],\n \"total\": 1,\n \"page\": 1,\n \"totalPages\": 1\n }\n}"},{"id":"734d5800-1faa-4e7f-8ec2-ddcc1b2ceac8","name":"With query params","originalRequest":{"method":"GET","header":[],"url":{"raw":"/usage?limit=10&page=2&sort='asc'&to='2021-07-19'&from='2021-07-19'","path":["usage"],"query":[{"key":"limit","value":"10","description":"Optional. How much usage data to return. The default and maximum is 100."},{"key":"page","value":"2"},{"key":"sort","value":"'asc'"},{"key":"to","value":"'2021-07-19'"},{"key":"from","value":"'2021-07-19'"}]}},"_postman_previewlanguage":"json","header":null,"cookie":[],"responseTime":null,"body":"{\n \"success\": true,\n \"data\": {\n \"usage\": [\n {\n \"timestamp\": \"2021-07-19T20:37:30.208Z\",\n \"request\": {\n \"url\": \"/location/1234\",\n \"body\": null,\n \"complete\": true,\n \"userAgent\": \"Mozilla/5.0 (Windows NT 10.0)\",\n \"queryParams\": null,\n \"method\": \"GET\",\n \"ip\": \"127.0.0.1\"\n },\n \"response\": {\n \"statusCode\": 404,\n \"statusMessage\": \"Not Found\"\n }\n }\n ],\n \"total\": 1,\n \"page\": 1,\n \"totalPages\": 1\n }\n}"}],"_postman_id":"602090c0-efc4-42fa-8ddf-3597a2f15e7e"},{"name":"/location/:serial","id":"53ed0460-8eb9-4022-ac59-6d37f5b25c89","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"/location/:serial","description":"

Gets the last known location for the requested device.

NOTE After 90 days, we remove device location data from our servers.

This can be the device's 15-digit IMEI, the 14-digit hexadecimal MEID, the 18-digit decimal MEID, or an alphanumeric mechanical serial number.

\n","type":"text/plain"},"type":"any","value":"351756051523999","key":"serial"}]}},"response":[{"id":"dad622a1-c092-466c-af30-936fa6ce52a2","name":"200 Status Response","originalRequest":{"method":"GET","header":[],"url":{"raw":"/location/:serial","path":["location",":serial"],"variable":[{"key":"serial","value":"351756051523999","description":"This can be the device's 15-digit IMEI, the 14-digit hexadecimal MEID, the 18-digit decimal MEID, or an alphanumeric mechanical serial number."}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"success\": true,\n \"data\": {\n \"latitude\": 39.74926691875779,\n \"longitude\": -105.00781737670295,\n \"time\": 1626122282591\n }\n}"},{"id":"ac5df8fb-162f-4941-a8a9-ded28d5a6404","name":"404 Status Response","originalRequest":{"method":"GET","header":[],"url":{"raw":"/location/:serial","path":["location",":serial"],"variable":[{"key":"serial","value":"1234","description":"This can be the device's 15-digit IMEI, the 14-digit hexadecimal MEID, the 18-digit decimal MEID, or an alphanumeric mechanical serial number."}]}},"status":"Not Found","code":404,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"success\": false,\n \"message\": \"Device or location not found\"\n}"},{"id":"e72a8fed-6260-4c94-8f1c-4a0ea6a112a1","name":"400 Status Response","originalRequest":{"method":"GET","header":[],"url":{"raw":"/location/:serial","path":["location",":serial"],"variable":[{"key":"serial","value":"!@bad","description":"This can be the device's 15-digit IMEI, the 14-digit hexadecimal MEID, the 18-digit decimal MEID, or an alphanumeric mechanical serial number."}]}},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{ \"success\": false, \"errors\": [ \"serial: Invalid value (!@bad)\" ] }"}],"_postman_id":"53ed0460-8eb9-4022-ac59-6d37f5b25c89"},{"name":"/devices/:serial","id":"db9c7a3e-70bf-4523-897d-ae39f02350a4","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"/devices/:serial","description":"

Gets information about the requested device.

This can be the device's 15-digit IMEI, the 14-digit hexadecimal MEID, the 18-digit decimal MEID, or an alphanumeric mechanical serial number.

\n","type":"text/plain"},"type":"any","value":"351756051523999","key":"serial"}]}},"response":[{"id":"ee6505ab-55b0-48d2-a871-075427964ec2","name":"200 Status Response","originalRequest":{"method":"GET","header":[],"url":{"raw":"/devices/:serial","path":["devices",":serial"],"variable":[{"key":"serial","value":"351756051523999","description":"This can be the device's 15-digit IMEI, the 14-digit hexadecimal MEID, the 18-digit decimal MEID, or an alphanumeric mechanical serial number."}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"success\": true,\n \"data\": {\n \"serials\": {\n \"imei\": [ \"351756051523999\" ],\n \"meid\": [ \"35175605152399\" ],\n \"meidD\": [ \"089072179701385369\" ],\n \"adb\": \"123456789\",\n \"mechanical\": \"Z2056\"\n },\n \"status\": { \n \"status\": \"No Data\", \n \"msg\": \"This device has never checked-in.\"\n },\n \"hardwareInfo\": {\n \"activeCpuUsage\": [],\n \"totalCpuUsage\": [],\n \"cpuTemperatures\": [],\n \"batteryTemperatures\": [],\n \"gpuTemperatures\": [],\n \"skinTemperatures\": []\n },\n \"alias\": \"alias\",\n \"manufacturer\": \"samsung\",\n \"model\": \"\",\n \"brand\": \"\",\n \"security_patch\": \"\",\n \"os\": \"\",\n \"clientVersion\": 0,\n \"registrationDate\": \"2021-07-29T17:43:42.759Z\"\n }\n}"},{"id":"7e871ecb-110f-4f31-9f4c-be9042332676","name":"404 Status Response","originalRequest":{"method":"GET","header":[],"url":{"raw":"/devices/:serial","path":["devices",":serial"],"variable":[{"key":"serial","value":"1234","description":"This can be the device's 15-digit IMEI, the 14-digit hexadecimal MEID, the 18-digit decimal MEID, or an alphanumeric mechanical serial number."}]}},"status":"Not Found","code":404,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"success\": false,\n \"message\": \"Device not found\"\n}"},{"id":"3d4ab9b4-d9be-4c7f-ad1a-8f6d7728458c","name":"400 Status Response","originalRequest":{"method":"GET","header":[],"url":{"raw":"/devices/:serial","path":["devices",":serial"],"variable":[{"key":"serial","value":"!@bad","description":"This can be the device's 15-digit IMEI, the 14-digit hexadecimal MEID, the 18-digit decimal MEID, or an alphanumeric mechanical serial number."}]}},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{ \"success\": false, \"errors\": [ \"serial: Invalid value (!@bad)\" ] }"},{"id":"ec2f69de-8cf7-41c6-b7ba-dc7fa9299344","name":"500 Status Response","originalRequest":{"method":"GET","header":[],"url":{"raw":"/devices/:serial","path":["devices",":serial"],"variable":[{"key":"serial","value":"351756051523999","description":"This can be the device's 15-digit IMEI, the 14-digit hexadecimal MEID, the 18-digit decimal MEID, or an alphanumeric mechanical serial number."}]}},"_postman_previewlanguage":null,"header":null,"cookie":[],"responseTime":null,"body":"{ \"success\": false, \"message\": \"Unexpected issue while looking up device.\" }"}],"_postman_id":"db9c7a3e-70bf-4523-897d-ae39f02350a4"},{"name":"/devices/:serial/suspend","id":"695a007a-e1e7-493a-83b3-44f816e001bc","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"url":"/devices/:serial/suspend","description":"

Sends a SUSPEND command to the device with the matching serial number. Once the device receives the command (it needs to have a data connection), it will then be in a \"suspended\" state. A suspended device is locked for use until it is \"unsuspended\" (see the /unsuspend endpoint).

This can be the device's 15-digit IMEI, the 14-digit hexadecimal MEID, the 18-digit decimal MEID, or an alphanumeric mechanical serial number.

\n","type":"text/plain"},"type":"any","value":"351756051523999","key":"serial"}]}},"response":[{"id":"2ddf9bc8-010c-4ee3-a52b-5533e5ec5611","name":"200 Status Response","originalRequest":{"method":"GET","header":[],"url":{"raw":"/devices/:serial/suspend","path":["devices",":serial","suspend"],"variable":[{"key":"serial","value":"351756051523999","description":"This can be the device's 15-digit IMEI, the 14-digit hexadecimal MEID, the 18-digit decimal MEID, or an alphanumeric mechanical serial number."}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"success\": true,\n \"msg\": \"Device SUSPEND message sent.\"\n}"},{"id":"0e1bf37d-529f-4c1b-acd6-01f01fff8f14","name":"404 Status Response","originalRequest":{"method":"GET","header":[],"url":{"raw":"/devices/:serial/suspend","path":["devices",":serial","suspend"],"variable":[{"key":"serial","value":"1234","description":"This can be the device's 15-digit IMEI, the 14-digit hexadecimal MEID, the 18-digit decimal MEID, or an alphanumeric mechanical serial number."}]}},"status":"Not Found","code":404,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"success\": false,\n \"message\": \"Device cannot be reached at the moment. If this problem persists, contact Customer Support.\"\n}"},{"id":"eb2200e3-b0c9-4f16-af9a-17f3a65db6ec","name":"400 Status Response","originalRequest":{"method":"GET","header":[],"url":{"raw":"/devices/:serial/suspend","path":["devices",":serial","suspend"],"variable":[{"key":"serial","value":"!@bad","description":"This can be the device's 15-digit IMEI, the 14-digit hexadecimal MEID, the 18-digit decimal MEID, or an alphanumeric mechanical serial number."}]}},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{ \"success\": false, \"errors\": [ \"serial: Invalid value (!@bad)\" ] }"},{"id":"50c52ce5-0082-40ca-a4f0-600858297676","name":"500 Status Response","originalRequest":{"method":"GET","header":[],"url":{"raw":"/devices/:serial/suspend","path":["devices",":serial","suspend"],"variable":[{"key":"serial","value":"351756051523999","description":"This can be the device's 15-digit IMEI, the 14-digit hexadecimal MEID, the 18-digit decimal MEID, or an alphanumeric mechanical serial number."}]}},"_postman_previewlanguage":"json","header":null,"cookie":[],"responseTime":null,"body":"{\n \"success\": false,\n \"message\": \"Unexpected issue while looking up device.\"\n}"}],"_postman_id":"695a007a-e1e7-493a-83b3-44f816e001bc"},{"name":"/devices/:serial/unsuspend","id":"28444414-a5a0-46ed-8055-26f6b75209b1","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"url":"/devices/:serial/unsuspend","description":"

Sends an UNSUSPEND command to the device with the matching serial number. Once the device receives the command (it needs to have a data connection), it will then be in an \"unsuspended\" state. An unsuspended device is available for normal use.

This can be the device's 15-digit IMEI, the 14-digit hexadecimal MEID, the 18-digit decimal MEID, or an alphanumeric mechanical serial number.

\n","type":"text/plain"},"type":"any","value":"351756051523999","key":"serial"}]}},"response":[{"id":"b9ab2c78-84df-480b-a488-dc0479b20991","name":"200 Status Response","originalRequest":{"method":"GET","header":[],"url":{"raw":"/devices/:serial/unsuspend","path":["devices",":serial","unsuspend"],"variable":[{"key":"serial","value":"351756051523999","description":"This can be the device's 15-digit IMEI, the 14-digit hexadecimal MEID, the 18-digit decimal MEID, or an alphanumeric mechanical serial number."}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"success\": true,\n \"msg\": \"Device UNSUSPEND message sent.\"\n}"},{"id":"96b8ae1b-18bc-4903-9dad-013e9270c30d","name":"404 Status Response","originalRequest":{"method":"GET","header":[],"url":{"raw":"/devices/:serial/unsuspend","path":["devices",":serial","unsuspend"],"variable":[{"key":"serial","value":"1234","description":"This can be the device's 15-digit IMEI, the 14-digit hexadecimal MEID, the 18-digit decimal MEID, or an alphanumeric mechanical serial number."}]}},"status":"Not Found","code":404,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"success\": false,\n \"message\": \"Device cannot be reached at the moment. If this problem persists, contact Customer Support.\"\n}"},{"id":"326fa667-3b61-4783-9ed9-47c03407db03","name":"400 Status Response","originalRequest":{"method":"GET","header":[],"url":{"raw":"/devices/:serial/unsuspend","path":["devices",":serial","unsuspend"],"variable":[{"key":"serial","value":"!@bad","description":"This can be the device's 15-digit IMEI, the 14-digit hexadecimal MEID, the 18-digit decimal MEID, or an alphanumeric mechanical serial number."}]}},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{ \"success\": false, \"errors\": [ \"serial: Invalid value (!@bad)\" ] }"},{"id":"ff1a3082-2134-4ed6-b22f-2679576f1e89","name":"500 Status Response","originalRequest":{"method":"GET","header":[],"url":{"raw":"/devices/:serial/unsuspend","path":["devices",":serial","unsuspend"],"variable":[{"key":"serial","value":"351756051523999","description":"This can be the device's 15-digit IMEI, the 14-digit hexadecimal MEID, the 18-digit decimal MEID, or an alphanumeric mechanical serial number."}]}},"_postman_previewlanguage":"json","header":null,"cookie":[],"responseTime":null,"body":"{\n \"success\": false,\n \"message\": \"Unexpected issue while looking up device.\"\n}"}],"_postman_id":"28444414-a5a0-46ed-8055-26f6b75209b1"}],"auth":{"type":"apikey","apikey":{"basicConfig":[]}},"event":[{"listen":"prerequest","script":{"id":"ed046ad2-1bdf-4361-97d4-214a58e1e890","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"4478b35a-2ca0-4321-a257-91040500dd3f","type":"text/javascript","exec":[""]}}]}