Get an entity
Returns an entity object for the provided entity ID.
Authorizations:
path Parameters
entityId required | any The ID of the entity to retrieve. |
query Parameters
includeChildren | boolean Default: false If enabled, the response will include an array of all child entity names and IDs at every hierarchical level under the entity specified in the request. |
Responses
Response samples
- 200
{- "id": "000000000000000000000002",
- "name": "My Company",
- "genealogy": [
- "000000000000000000000000",
- "000000000000000000000001"
], - "addresses": [
- {
- "name": "Main Office",
- "address1": "1234 State St.",
- "address2": "Suite 100",
- "city": "Manhattan",
- "state": "NY",
- "stateOrProvince": "New York",
- "zipOrPostalCode": "10001",
- "country": "United States"
}
], - "children": [
- {
- "id": "000000000000000000000003",
- "name": "My Child Company"
}
], - "labels": {
- "foo": "bar"
}
}
Create an entity
Creates a new entity underneath the entity specified in the path parameters.
Authorizations:
path Parameters
entityId | any The ID of the entity to create a child entity under. |
Request Body schema: application/json
name | string The name of the entity to create |
Responses
Request samples
- Payload
{- "name": "string"
}
Response samples
- 200
{- "id": "000000000000000000000002",
- "name": "My Company",
- "genealogy": [
- "000000000000000000000000",
- "000000000000000000000001"
], - "addresses": [
- {
- "name": "Main Office",
- "address1": "1234 State St.",
- "address2": "Suite 100",
- "city": "Manhattan",
- "state": "NY",
- "stateOrProvince": "New York",
- "zipOrPostalCode": "10001",
- "country": "United States"
}
], - "children": [
- {
- "id": "000000000000000000000003",
- "name": "My Child Company"
}
], - "labels": {
- "foo": "bar"
}
}
Update an entity
Updates the entity name, or entity settings.
Updating Entity Settings
Audit logging is not yet supported for settings changed using this endpoint.
Print Tracker supports dynamic settings inheritance. This means that settings set at a parent entity will be inherited by all child entities, installs, and devices unless explicitly overridden. In order to be clear about how settings are being changed within the context of inheritance, this endpoint allows you to specify an array of settings that you want to set
and an array of setting paths that you want to reset
(remove any explicit value so that the value is inherited from the parent).
The following settings paths are allowed to be set or reset. When setting a value, the following table describes the types of values that are allowed.
Path |
Supported Values |
---|---|
snmp.version |
One of: 1 , 2 , 3 |
snmp.communities |
Array of strings |
snmp.v3Algorithm |
One of: MD5 , SHA |
snmp.v3Context |
String |
snmp.v3Username |
String |
snmp.v3PrivacyPassword |
String |
deviceDiscovery.ipaddress |
An array of IP addresses, ranges, or CIDR blocks to scan. May be formatted in any of the following styles, 10.0.0.1, 10.0.0.1-10, 10.0.0.*, 10.0.0.0/24 |
deviceDiscovery.excludeIPAddress |
An array of IP addresses to exclude from scanning. |
labels.<key> |
Any label key values can be provided. Both the keys and values must be strings. |
Authorizations:
path Parameters
entityId | any The ID of the entity to update. |
Request Body schema: application/json
name | string The name of the entity to update |
Array of objects | |
reset | Array of strings |
Responses
Request samples
- Payload
{- "name": "New entity name",
- "set": [
- {
- "path": "snmp.communities",
- "value": [
- "public"
]
}, - {
- "path": "snmp.version",
- "value": 1
}, - {
- "path": "deviceDiscovery.ipaddress",
- "value": [
- "10.0.0.1",
- "10.0.0.5-10",
- "10.0.1.0/24",
- "10.0.2.*"
]
}, - {
- "path": "deviceDiscovery.excludeIPAddress",
- "value": [
- "10.0.0.1"
]
}, - {
- "path": "snmp.v3Username",
- "value": "my username"
}, - {
- "path": "snmp.v3PrivacyPassword",
- "value": "my password"
}, - {
- "path": "snmp.v3Context",
- "value": "my context"
}, - {
- "path": "snmp.v3Algorithm",
- "value": "MD5"
}, - {
- "path": "labels.foo",
- "value": "bar"
}
], - "reset": [
- "snmp.communities"
]
}
Response samples
- 200
{- "id": "000000000000000000000002",
- "name": "My Company",
- "genealogy": [
- "000000000000000000000000",
- "000000000000000000000001"
], - "addresses": [
- {
- "name": "Main Office",
- "address1": "1234 State St.",
- "address2": "Suite 100",
- "city": "Manhattan",
- "state": "NY",
- "stateOrProvince": "New York",
- "zipOrPostalCode": "10001",
- "country": "United States"
}
], - "children": [
- {
- "id": "000000000000000000000003",
- "name": "My Child Company"
}
], - "labels": {
- "foo": "bar"
}
}
Get devices by entity
Returns an array of devices that belong to the specified entity and (optionally) its children.
Authorizations:
path Parameters
entityId required | any The ID of the entity to load devices from. |
query Parameters
includeChildren | boolean Default: false If enabled, the response will include devices at this entity, and all child entities. |
limit | integer Default: 100 The maximum number of devices to return in a single request. |
page | integer Default: 1 The page number to return. Page numbers start at 1. |
excludeDisabled | boolean Default: false If true, only managed devices will be returned. |
Responses
Response samples
- 200
[- {
- "id": "000000000000000000000006",
- "createdDate": "2021-01-01T01:44:44.000Z",
- "modifiedDate": "2021-01-01T01:44:44.000Z",
- "entityKey": "000000000000000000000002",
- "installKeys": [
- "000000000000000000000005"
], - "make": "HP",
- "model": "LaserJet 4000",
- "serialNumber": "CNDQQ05142",
- "customSerialNumber": "CUSTOM-CNDQQ05142",
- "ipAddress": "10.0.0.5",
- "macAddress": "00-60-d1-4d-e1-5f",
- "location": "string",
- "customLocation": "string",
- "assetID": "ABC123",
- "note": "string",
- "isLocal": true,
- "firmware": {
- "device": "FW-101.v10.1.10"
}, - "labels": {
- "foo": "bar"
}, - "managed": true
}
]
Create a device
Creates a device under the specified entity. This endpoint can be used to create devices in Print Tracker prior to discovering the physical devices using a Print Tracker data collection agent. Currently, this endpoint only supports creating devices with a smaller subset of the fields specified.
If the device already exists, this endpoint will return the existing device. This means that calls to this endpoint are idempotent.
If a data collection agent discovers a device with the same serial number in the future, the device will be updated with the new data. The values for properties in the schema below like make
or model
do not need to be perfect. As long as the serial number matches exactly, once the device is discovered by the data collection agent, all other properties will be updated.
Authorizations:
path Parameters
entityId required | any The ID of the entity to load devices from. |
Request Body schema: application/json
make | string The device's manufacturer, e.g. "HP", "Brother", "Canon". |
model | string The device's model, e.g. "LaserJet 4000", "HL-L2340DW". |
serialNumber | string |
customSerialNumber | string |
ipAddress | string |
macAddress | string |
assetId | string |
customLocation | string |
note | string |
labels | object |
managed | boolean Default: true Whether the device should be a managed device, with an "enabled" tracking status in Print Tracker. |
Responses
Request samples
- Payload
[- {
- "make": "HP",
- "model": "LaserJet M477fdw",
- "serialNumber": "SN12345",
- "customSerialNumber": "CUSTOM-SN12345",
- "ipAddress": "10.0.0.10",
- "macAddress": "00:00:00:00:00:00",
- "assetId": 12345,
- "customLocation": "Room 123",
- "note": "This is a note",
- "labels": {
- "foo": "bar"
}, - "managed": true
}
]
Response samples
- 200
[- {
- "id": "000000000000000000000000",
- "make": "HP",
- "model": "LaserJet M477fdw",
- "serialNumber": "SN12345",
- "customSerialNumber": "CUSTOM-SN12345",
- "ipAddress": "10.0.0.10",
- "macAddress": "00:00:00:00:00:00",
- "assetId": 12345,
- "customLocation": "Room 123",
- "note": "This is a note",
- "labels": {
- "foo": "bar"
}, - "managed": true
}
]
Update a device
Updates the specified fields on a device
Authorizations:
path Parameters
entityId required | any The ID of the entity that the device belongs to. |
deviceId required | any The ID of the device to delete. |
Request Body schema: application/json
macAddress | string |
assetId | string |
customLocation | string |
note | string |
labels | object |
Responses
Request samples
- Payload
{- "macAddress": "00:00:00:00:00:00",
- "assetId": 12345,
- "customLocation": "Room 123",
- "note": "This is a note",
- "labels": {
- "foo": "bar"
}
}
Response samples
- 200
{- "id": "000000000000000000000006",
- "createdDate": "2021-01-01T01:44:44.000Z",
- "modifiedDate": "2021-01-01T01:44:44.000Z",
- "entityKey": "000000000000000000000002",
- "installKeys": [
- "000000000000000000000005"
], - "make": "HP",
- "model": "LaserJet 4000",
- "serialNumber": "CNDQQ05142",
- "customSerialNumber": "CUSTOM-CNDQQ05142",
- "ipAddress": "10.0.0.5",
- "macAddress": "00-60-d1-4d-e1-5f",
- "location": "string",
- "customLocation": "string",
- "assetID": "ABC123",
- "note": "string",
- "isLocal": true,
- "firmware": {
- "device": "FW-101.v10.1.10"
}, - "labels": {
- "foo": "bar"
}, - "managed": true
}
Delete a device
Deletes the device and all associated data including meter history, supply history, etc.
Authorizations:
path Parameters
entityId required | any The ID of the entity that the device belongs to. |
deviceId required | any The ID of the device to delete. |
Responses
Response samples
- 200
null
Set a device skip alert
Configures a skip alert for the device. When added to a specific supply, a skip alert prevents a low supply alert from being generated for that supply.
Authorizations:
path Parameters
entityId required | any The ID of the entity that the device belongs to. |
deviceId required | any The ID of the device to delete. |
Request Body schema: application/json
skipsRemaining | integer The number of low supply alerts that should be skipped before alerts are resumed. If set to 0, alerts will be resumed immediately. |
supplyKey | string The key of the supply to skip alerts for. The following supply keys are supported:
|
Responses
Request samples
- Payload
{- "skipsRemaining": 1,
- "supplyKey": "blackToner"
}
Response samples
- 200
null
Get meters by entity
Returns an array of meter reads for the specified entity.
Authorizations:
path Parameters
entityId required | any The ID of the entity to load meters from. |
query Parameters
excludeDisabled | boolean Default: false If true, only meters form managed devices will be returned. |
start required | any Example: start=2020-12-18T17:52:52.417Z The start of the meter read date range formatted as RFC3339, ISO8601 (without timezone), RFC1123Z, RFC1123, RFC1123, RFC822Z, RFC822, RFC8250, ANSIC, or Unix. |
end required | any Example: end=2021-01-25T17:52:52.417Z The end of the meter read date range formatted as RFC3339, ISO8601 (without timezone), RFC1123Z, RFC1123, RFC1123, RFC822Z, RFC822, RFC8250, ANSIC, or Unix. |
Responses
Response samples
- 200
[- {
- "id": "000000000000000000000008",
- "createdDate": "2021-01-01T01:44:44.000Z",
- "modifiedDate": "2021-01-01T01:44:44.000Z",
- "entityKey": "000000000000000000000002",
- "installKey": "000000000000000000000003",
- "deviceKey": "000000000000000000000006",
- "timestamp": "2021-01-01T01:44:44.000Z",
- "console": "Sleeping...",
- "pageCounts": {
- "life": {
- "total": {
- "value": 100,
- "displayName": "Total"
}, - "totalBlack": {
- "value": 75,
- "displayName": "Total Black"
}, - "totalColor": {
- "value": 25,
- "displayName": "Total Color"
}
}, - "equiv": {
- "total": {
- "value": 200,
- "displayName": "Total"
}, - "totalBlack": {
- "value": 150,
- "displayName": "Total Black"
}, - "totalColor": {
- "value": 50,
- "displayName": "Total Color"
}
}
}, - "supplies": {
- "blackToner": {
- "serialNum": {
- "displayName": "Serial Number",
- "value": "CAB231222A22"
}, - "sidesOnSupply": {
- "displayName": "Sides on Supply",
- "value": 4869
}, - "unit": {
- "displayName": "Unit",
- "value": "Impressions"
}, - "currentLevel": {
- "displayName": "Current Level",
- "value": 360
}, - "fillRate": {
- "displayName": "Fill rate",
- "value": 0.06
}, - "maxLevel": {
- "displayName": "Max Level",
- "value": 6000
}, - "pctRemaining": {
- "displayName": "Percent Remaining",
- "value": 6
}, - "type": {
- "displayName": "Type",
- "value": "toner"
}, - "color": {
- "displayName": "Color",
- "value": "black"
}, - "description": {
- "displayName": "Description",
- "value": "Black Toner"
}, - "displayableName": {
- "displayName": "Displayable Name",
- "value": "Black Toner"
}, - "partNum": {
- "displayName": "Part Number",
- "value": "52D0Z00"
}
}
}
}
]
Get current meters by entity
Returns an array of current meter reads for all devices at the specified entity. If includeChildren is enabled and provided in the query string, this endpoint will return the current meter reads for all devices at the provided entity and any children of the provided entity. This endpoint is paginated, and the caller should pass a page and limit to paginate all the results from the endpoint.
Authorizations:
path Parameters
entityId required | any The ID of the entity to load meters from. |
query Parameters
excludeDisabled | boolean Default: false If true, only meters form managed devices will be returned. |
includeChildren | boolean Default: false If enabled, the response will include meters at this entity, and all child entities. |
limit | integer Default: 100 The maximum number of results to return in a single request. Maximum is 1000. |
page | integer Default: 1 The page number to return. Page numbers start at 1. |
Responses
Response samples
- 200
[- {
- "id": "000000000000000000000008",
- "createdDate": "2021-01-01T01:44:44.000Z",
- "modifiedDate": "2021-01-01T01:44:44.000Z",
- "entityKey": "000000000000000000000002",
- "installKey": "000000000000000000000003",
- "deviceKey": "000000000000000000000006",
- "timestamp": "2021-01-01T01:44:44.000Z",
- "console": "Sleeping...",
- "pageCounts": {
- "life": {
- "total": {
- "value": 100,
- "displayName": "Total"
}, - "totalBlack": {
- "value": 75,
- "displayName": "Total Black"
}, - "totalColor": {
- "value": 25,
- "displayName": "Total Color"
}
}, - "equiv": {
- "total": {
- "value": 200,
- "displayName": "Total"
}, - "totalBlack": {
- "value": 150,
- "displayName": "Total Black"
}, - "totalColor": {
- "value": 50,
- "displayName": "Total Color"
}
}
}, - "supplies": {
- "blackToner": {
- "serialNum": {
- "displayName": "Serial Number",
- "value": "CAB231222A22"
}, - "sidesOnSupply": {
- "displayName": "Sides on Supply",
- "value": 4869
}, - "unit": {
- "displayName": "Unit",
- "value": "Impressions"
}, - "currentLevel": {
- "displayName": "Current Level",
- "value": 360
}, - "fillRate": {
- "displayName": "Fill rate",
- "value": 0.06
}, - "maxLevel": {
- "displayName": "Max Level",
- "value": 6000
}, - "pctRemaining": {
- "displayName": "Percent Remaining",
- "value": 6
}, - "type": {
- "displayName": "Type",
- "value": "toner"
}, - "color": {
- "displayName": "Color",
- "value": "black"
}, - "description": {
- "displayName": "Description",
- "value": "Black Toner"
}, - "displayableName": {
- "displayName": "Displayable Name",
- "value": "Black Toner"
}, - "partNum": {
- "displayName": "Part Number",
- "value": "52D0Z00"
}
}
}
}
]
Get meters by device
Returns an array of meter reads for a single device
Authorizations:
path Parameters
entityId required | any The ID of the entity that the device belongs to |
deviceId required | any The ID of the device to load meters from. |
query Parameters
limit | integer Default: 100 The maximum number of devices to return in a single request. |
page | integer Default: 1 The page number to return. Page numbers start at 1. |
start required | any Example: start=2020-12-18T17:52:52.417Z The start of the meter read date range formatted as RFC3339, ISO8601 (without timezone), RFC1123Z, RFC1123, RFC1123, RFC822Z, RFC822, RFC8250, ANSIC, or Unix. |
end required | any Example: end=2021-01-25T17:52:52.417Z The end of the meter read date range formatted as RFC3339, ISO8601 (without timezone), RFC1123Z, RFC1123, RFC1123, RFC822Z, RFC822, RFC8250, ANSIC, or Unix. |
Responses
Response samples
- 200
[- {
- "id": "000000000000000000000008",
- "createdDate": "2021-01-01T01:44:44.000Z",
- "modifiedDate": "2021-01-01T01:44:44.000Z",
- "entityKey": "000000000000000000000002",
- "installKey": "000000000000000000000003",
- "deviceKey": "000000000000000000000006",
- "timestamp": "2021-01-01T01:44:44.000Z",
- "console": "Sleeping...",
- "pageCounts": {
- "life": {
- "total": {
- "value": 100,
- "displayName": "Total"
}, - "totalBlack": {
- "value": 75,
- "displayName": "Total Black"
}, - "totalColor": {
- "value": 25,
- "displayName": "Total Color"
}
}, - "equiv": {
- "total": {
- "value": 200,
- "displayName": "Total"
}, - "totalBlack": {
- "value": 150,
- "displayName": "Total Black"
}, - "totalColor": {
- "value": 50,
- "displayName": "Total Color"
}
}
}, - "supplies": {
- "blackToner": {
- "serialNum": {
- "displayName": "Serial Number",
- "value": "CAB231222A22"
}, - "sidesOnSupply": {
- "displayName": "Sides on Supply",
- "value": 4869
}, - "unit": {
- "displayName": "Unit",
- "value": "Impressions"
}, - "currentLevel": {
- "displayName": "Current Level",
- "value": 360
}, - "fillRate": {
- "displayName": "Fill rate",
- "value": 0.06
}, - "maxLevel": {
- "displayName": "Max Level",
- "value": 6000
}, - "pctRemaining": {
- "displayName": "Percent Remaining",
- "value": 6
}, - "type": {
- "displayName": "Type",
- "value": "toner"
}, - "color": {
- "displayName": "Color",
- "value": "black"
}, - "description": {
- "displayName": "Description",
- "value": "Black Toner"
}, - "displayableName": {
- "displayName": "Displayable Name",
- "value": "Black Toner"
}, - "partNum": {
- "displayName": "Part Number",
- "value": "52D0Z00"
}
}
}
}
]
Create meters for device
Creates meter readings for a device. This endpoint can be used to load meter history collected from another data collection agent, into Print Tracker.
Requirements
- The total number of meter reads for a single device cannot exceed 186.
- The meter read timestamps must be in the same timezone.
- The meter read timestamps must be in the past.
- No more than one meter read per calendar day.
- The
pageCounts
must contain at least adefault
format. - Each
pageCounts
format must contain at least atotal
counter.
Authorizations:
path Parameters
entityId required | any The ID of the entity that the device belongs to |
deviceId required | any The ID of the device to load meters from. |
Request Body schema: application/json
Array of objects | |||||
Array
|
Responses
Request samples
- Payload
{- "meters": [
- {
- "timestamp": "2024-03-24T01:45:58-06:00",
- "pageCounts": {
- "default": {
- "total": {
- "value": 150
}, - "totalBlack": {
- "value": 100
}, - "totalColor": {
- "value": 50
}
}, - "equiv": {
- "total": {
- "value": 175
}, - "totalBlack": {
- "value": 125
}, - "totalColor": {
- "value": 50
}
}
}
}
]
}
Response samples
- 200
null
Get meter immediately prior to a date
Returns the meter read for a device that is closest to, but not after the provided date query parameter.
Authorizations:
path Parameters
entityId required | any The ID of the entity that the device belongs to |
deviceId required | any The ID of the device to load meters from. |
query Parameters
date required | any Example: date=2021-01-25T17:52:52.417Z The meter read returned will be the most recent meter read that occurred before this date, formatted as RFC3339, ISO8601 (without timezone), RFC1123Z, RFC1123, RFC1123, RFC822Z, RFC822, RFC8250, ANSIC, or Unix. |
Responses
Response samples
- 200
[- {
- "id": "000000000000000000000008",
- "createdDate": "2021-01-01T01:44:44.000Z",
- "modifiedDate": "2021-01-01T01:44:44.000Z",
- "entityKey": "000000000000000000000002",
- "installKey": "000000000000000000000003",
- "deviceKey": "000000000000000000000006",
- "timestamp": "2021-01-01T01:44:44.000Z",
- "console": "Sleeping...",
- "pageCounts": {
- "life": {
- "total": {
- "value": 100,
- "displayName": "Total"
}, - "totalBlack": {
- "value": 75,
- "displayName": "Total Black"
}, - "totalColor": {
- "value": 25,
- "displayName": "Total Color"
}
}, - "equiv": {
- "total": {
- "value": 200,
- "displayName": "Total"
}, - "totalBlack": {
- "value": 150,
- "displayName": "Total Black"
}, - "totalColor": {
- "value": 50,
- "displayName": "Total Color"
}
}
}, - "supplies": {
- "blackToner": {
- "serialNum": {
- "displayName": "Serial Number",
- "value": "CAB231222A22"
}, - "sidesOnSupply": {
- "displayName": "Sides on Supply",
- "value": 4869
}, - "unit": {
- "displayName": "Unit",
- "value": "Impressions"
}, - "currentLevel": {
- "displayName": "Current Level",
- "value": 360
}, - "fillRate": {
- "displayName": "Fill rate",
- "value": 0.06
}, - "maxLevel": {
- "displayName": "Max Level",
- "value": 6000
}, - "pctRemaining": {
- "displayName": "Percent Remaining",
- "value": 6
}, - "type": {
- "displayName": "Type",
- "value": "toner"
}, - "color": {
- "displayName": "Color",
- "value": "black"
}, - "description": {
- "displayName": "Description",
- "value": "Black Toner"
}, - "displayableName": {
- "displayName": "Displayable Name",
- "value": "Black Toner"
}, - "partNum": {
- "displayName": "Part Number",
- "value": "52D0Z00"
}
}
}
}
]
Get supplies by entity
Returns all the supplies from all the devices belonging to the specified entity or its children.
Authorizations:
path Parameters
entityId required | any The ID of the entity that we want to pull supplies |
query Parameters
includeChildren | boolean Default: false If enabled, the response will include meters at this entity, and all child entities. |
replaced | boolean Default: false If enabled, the response will only include replaced supplies |
start required | any Example: start=2020-12-18T17:52:52.417Z If |
end required | any Example: end=2021-01-25T17:52:52.417Z If |
limit | integer Default: 100 The maximum number of supplies to return in a single request. |
page | integer Default: 1 The page number to return. Page numbers start at 1. |
Responses
Response samples
- 200
[- {
- "deviceKey": "000000000000000000000006",
- "installedDate": "2021-01-01T01:44:44.000Z",
- "replacedDate": "2021-01-01T01:44:44.000Z",
- "confirmedReplacedDate": "2021-01-01T01:44:44.000Z",
- "depletionDate": "2021-01-01T01:44:44.000Z",
- "previousSupplyKey": "000000000000000000000007",
- "supply": "blackToner",
- "firstMeterRead": {
- "installKey": "000000000000000000000003",
- "deviceKey": "000000000000000000000006",
- "timestamp": "2021-01-01T01:44:44.000Z",
- "pageCounts": {
- "life": {
- "total": {
- "value": 100,
- "displayName": "Total"
}, - "totalBlack": {
- "value": 75,
- "displayName": "Total Black"
}, - "totalColor": {
- "value": 25,
- "displayName": "Total Color"
}
}, - "equiv": {
- "total": {
- "value": 200,
- "displayName": "Total"
}, - "totalBlack": {
- "value": 150,
- "displayName": "Total Black"
}, - "totalColor": {
- "value": 50,
- "displayName": "Total Color"
}
}
}, - "supplies": {
- "blackToner": {
- "serialNum": {
- "displayName": "Serial Number",
- "value": "CAB231222A22"
}, - "sidesOnSupply": {
- "displayName": "Sides on Supply",
- "value": 4869
}, - "unit": {
- "displayName": "Unit",
- "value": "Impressions"
}, - "currentLevel": {
- "displayName": "Current Level",
- "value": 360
}, - "fillRate": {
- "displayName": "Fill rate",
- "value": 0.06
}, - "maxLevel": {
- "displayName": "Max Level",
- "value": 6000
}, - "pctRemaining": {
- "displayName": "Percent Remaining",
- "value": 6
}, - "type": {
- "displayName": "Type",
- "value": "toner"
}, - "color": {
- "displayName": "Color",
- "value": "black"
}, - "description": {
- "displayName": "Description",
- "value": "Black Toner"
}, - "displayableName": {
- "displayName": "Displayable Name",
- "value": "Black Toner"
}, - "partNum": {
- "displayName": "Part Number",
- "value": "52D0Z00"
}
}
}
}, - "lastMeterRead": {
- "installKey": "000000000000000000000003",
- "deviceKey": "000000000000000000000006",
- "timestamp": "2021-01-01T01:44:44.000Z",
- "pageCounts": {
- "life": {
- "total": {
- "value": 100,
- "displayName": "Total"
}, - "totalBlack": {
- "value": 75,
- "displayName": "Total Black"
}, - "totalColor": {
- "value": 25,
- "displayName": "Total Color"
}
}, - "equiv": {
- "total": {
- "value": 200,
- "displayName": "Total"
}, - "totalBlack": {
- "value": 150,
- "displayName": "Total Black"
}, - "totalColor": {
- "value": 50,
- "displayName": "Total Color"
}
}
}, - "supplies": {
- "blackToner": {
- "serialNum": {
- "displayName": "Serial Number",
- "value": "CAB231222A22"
}, - "sidesOnSupply": {
- "displayName": "Sides on Supply",
- "value": 4869
}, - "unit": {
- "displayName": "Unit",
- "value": "Impressions"
}, - "currentLevel": {
- "displayName": "Current Level",
- "value": 360
}, - "fillRate": {
- "displayName": "Fill rate",
- "value": 0.06
}, - "maxLevel": {
- "displayName": "Max Level",
- "value": 6000
}, - "pctRemaining": {
- "displayName": "Percent Remaining",
- "value": 6
}, - "type": {
- "displayName": "Type",
- "value": "toner"
}, - "color": {
- "displayName": "Color",
- "value": "black"
}, - "description": {
- "displayName": "Description",
- "value": "Black Toner"
}, - "displayableName": {
- "displayName": "Displayable Name",
- "value": "Black Toner"
}, - "partNum": {
- "displayName": "Part Number",
- "value": "52D0Z00"
}
}
}
}, - "attributes": {
- "serialNum": {
- "displayName": "Serial Number",
- "value": "CAB231222A22"
}, - "sidesOnSupply": {
- "displayName": "Sides on Supply",
- "value": 4869
}, - "unit": {
- "displayName": "Unit",
- "value": "Impressions"
}, - "currentLevel": {
- "displayName": "Current Level",
- "value": 360
}, - "fillRate": {
- "displayName": "Fill rate",
- "value": 0.06
}, - "maxLevel": {
- "displayName": "Max Level",
- "value": 6000
}, - "pctRemaining": {
- "displayName": "Percent Remaining",
- "value": 6
}, - "type": {
- "displayName": "Type",
- "value": "toner"
}, - "color": {
- "displayName": "Color",
- "value": "black"
}, - "description": {
- "displayName": "Description",
- "value": "Black Toner"
}, - "displayableName": {
- "displayName": "Displayable Name",
- "value": "Black Toner"
}, - "partNum": {
- "displayName": "Part Number",
- "value": "52D0Z00"
}
}, - "statistics": {
- "estimatedDepletionDate": "2021-01-01T01:44:44.000Z",
- "estimatedDepletionDateSource": "Calculated",
- "fillRate": 0.06,
- "actualCostPerPage": 0.06,
- "lostPages": 150,
- "volumeByFormat": {
- "life": 100,
- "equiv": 200
}, - "granularity": 1
}, - "settings": {
- "partNumber": "CF410A",
- "expectedFillRate": 0.05,
- "expectedYield": 6000,
- "supplyCost": 120.55
}
}
]
Get supplies by device
Returns all the supplies for a single device
Authorizations:
path Parameters
entityId required | any The ID of the entity that the device belongs to |
deviceId required | any The ID of the entity that the device belongs to |
query Parameters
replaced | boolean Default: false If enabled, the response will only include replaced supplies |
start required | any Example: start=2020-12-18T17:52:52.417Z If |
end required | any Example: end=2021-01-25T17:52:52.417Z If |
limit | integer Default: 100 The maximum number of supplies to return in a single request. |
page | integer Default: 1 The page number to return. Page numbers start at 1. |
Responses
Response samples
- 200
[- {
- "deviceKey": "000000000000000000000006",
- "installedDate": "2021-01-01T01:44:44.000Z",
- "replacedDate": "2021-01-01T01:44:44.000Z",
- "confirmedReplacedDate": "2021-01-01T01:44:44.000Z",
- "depletionDate": "2021-01-01T01:44:44.000Z",
- "previousSupplyKey": "000000000000000000000007",
- "supply": "blackToner",
- "firstMeterRead": {
- "installKey": "000000000000000000000003",
- "deviceKey": "000000000000000000000006",
- "timestamp": "2021-01-01T01:44:44.000Z",
- "pageCounts": {
- "life": {
- "total": {
- "value": 100,
- "displayName": "Total"
}, - "totalBlack": {
- "value": 75,
- "displayName": "Total Black"
}, - "totalColor": {
- "value": 25,
- "displayName": "Total Color"
}
}, - "equiv": {
- "total": {
- "value": 200,
- "displayName": "Total"
}, - "totalBlack": {
- "value": 150,
- "displayName": "Total Black"
}, - "totalColor": {
- "value": 50,
- "displayName": "Total Color"
}
}
}, - "supplies": {
- "blackToner": {
- "serialNum": {
- "displayName": "Serial Number",
- "value": "CAB231222A22"
}, - "sidesOnSupply": {
- "displayName": "Sides on Supply",
- "value": 4869
}, - "unit": {
- "displayName": "Unit",
- "value": "Impressions"
}, - "currentLevel": {
- "displayName": "Current Level",
- "value": 360
}, - "fillRate": {
- "displayName": "Fill rate",
- "value": 0.06
}, - "maxLevel": {
- "displayName": "Max Level",
- "value": 6000
}, - "pctRemaining": {
- "displayName": "Percent Remaining",
- "value": 6
}, - "type": {
- "displayName": "Type",
- "value": "toner"
}, - "color": {
- "displayName": "Color",
- "value": "black"
}, - "description": {
- "displayName": "Description",
- "value": "Black Toner"
}, - "displayableName": {
- "displayName": "Displayable Name",
- "value": "Black Toner"
}, - "partNum": {
- "displayName": "Part Number",
- "value": "52D0Z00"
}
}
}
}, - "lastMeterRead": {
- "installKey": "000000000000000000000003",
- "deviceKey": "000000000000000000000006",
- "timestamp": "2021-01-01T01:44:44.000Z",
- "pageCounts": {
- "life": {
- "total": {
- "value": 100,
- "displayName": "Total"
}, - "totalBlack": {
- "value": 75,
- "displayName": "Total Black"
}, - "totalColor": {
- "value": 25,
- "displayName": "Total Color"
}
}, - "equiv": {
- "total": {
- "value": 200,
- "displayName": "Total"
}, - "totalBlack": {
- "value": 150,
- "displayName": "Total Black"
}, - "totalColor": {
- "value": 50,
- "displayName": "Total Color"
}
}
}, - "supplies": {
- "blackToner": {
- "serialNum": {
- "displayName": "Serial Number",
- "value": "CAB231222A22"
}, - "sidesOnSupply": {
- "displayName": "Sides on Supply",
- "value": 4869
}, - "unit": {
- "displayName": "Unit",
- "value": "Impressions"
}, - "currentLevel": {
- "displayName": "Current Level",
- "value": 360
}, - "fillRate": {
- "displayName": "Fill rate",
- "value": 0.06
}, - "maxLevel": {
- "displayName": "Max Level",
- "value": 6000
}, - "pctRemaining": {
- "displayName": "Percent Remaining",
- "value": 6
}, - "type": {
- "displayName": "Type",
- "value": "toner"
}, - "color": {
- "displayName": "Color",
- "value": "black"
}, - "description": {
- "displayName": "Description",
- "value": "Black Toner"
}, - "displayableName": {
- "displayName": "Displayable Name",
- "value": "Black Toner"
}, - "partNum": {
- "displayName": "Part Number",
- "value": "52D0Z00"
}
}
}
}, - "attributes": {
- "serialNum": {
- "displayName": "Serial Number",
- "value": "CAB231222A22"
}, - "sidesOnSupply": {
- "displayName": "Sides on Supply",
- "value": 4869
}, - "unit": {
- "displayName": "Unit",
- "value": "Impressions"
}, - "currentLevel": {
- "displayName": "Current Level",
- "value": 360
}, - "fillRate": {
- "displayName": "Fill rate",
- "value": 0.06
}, - "maxLevel": {
- "displayName": "Max Level",
- "value": 6000
}, - "pctRemaining": {
- "displayName": "Percent Remaining",
- "value": 6
}, - "type": {
- "displayName": "Type",
- "value": "toner"
}, - "color": {
- "displayName": "Color",
- "value": "black"
}, - "description": {
- "displayName": "Description",
- "value": "Black Toner"
}, - "displayableName": {
- "displayName": "Displayable Name",
- "value": "Black Toner"
}, - "partNum": {
- "displayName": "Part Number",
- "value": "52D0Z00"
}
}, - "statistics": {
- "estimatedDepletionDate": "2021-01-01T01:44:44.000Z",
- "estimatedDepletionDateSource": "Calculated",
- "fillRate": 0.06,
- "actualCostPerPage": 0.06,
- "lostPages": 150,
- "volumeByFormat": {
- "life": 100,
- "equiv": 200
}, - "granularity": 1
}, - "settings": {
- "partNumber": "CF410A",
- "expectedFillRate": 0.05,
- "expectedYield": 6000,
- "supplyCost": 120.55
}
}
]
Update current supply
Updates the currently installed supply's settings.
Updating Supply Settings
Audit logging is not yet supported for settings changed using this endpoint.
The following settings paths are allowed to be set or reset. When setting a value, the following table describes the types of values that are allowed.
Path |
Supported Values |
---|---|
partNumber |
String |
expectedFillRate |
Number |
expectedYield |
Number |
supplyCost |
Number |
Authorizations:
path Parameters
entityId required | string The entity ID of the device that the supply belongs to. |
deviceId required | string The device ID that the supply belongs to. |
query Parameters
type required | string The supply type to use when finding which currently installed supply to update. |
color | string The supply color to use when finding which currently installed supply to update. If not provided, it will look for a color-less supply (such as a waste toner kit). |
Request Body schema: application/json
Array of objects | |
reset | Array of strings |
Responses
Request samples
- Payload
{- "set": [
- {
- "path": "partNumber",
- "value": "CF410A"
}
], - "reset": [
- "expectedYield"
]
}
Response samples
- 200
{- "deviceKey": "000000000000000000000006",
- "installedDate": "2021-01-01T01:44:44.000Z",
- "replacedDate": "2021-01-01T01:44:44.000Z",
- "confirmedReplacedDate": "2021-01-01T01:44:44.000Z",
- "depletionDate": "2021-01-01T01:44:44.000Z",
- "previousSupplyKey": "000000000000000000000007",
- "supply": "blackToner",
- "firstMeterRead": {
- "installKey": "000000000000000000000003",
- "deviceKey": "000000000000000000000006",
- "timestamp": "2021-01-01T01:44:44.000Z",
- "pageCounts": {
- "life": {
- "total": {
- "value": 100,
- "displayName": "Total"
}, - "totalBlack": {
- "value": 75,
- "displayName": "Total Black"
}, - "totalColor": {
- "value": 25,
- "displayName": "Total Color"
}
}, - "equiv": {
- "total": {
- "value": 200,
- "displayName": "Total"
}, - "totalBlack": {
- "value": 150,
- "displayName": "Total Black"
}, - "totalColor": {
- "value": 50,
- "displayName": "Total Color"
}
}
}, - "supplies": {
- "blackToner": {
- "serialNum": {
- "displayName": "Serial Number",
- "value": "CAB231222A22"
}, - "sidesOnSupply": {
- "displayName": "Sides on Supply",
- "value": 4869
}, - "unit": {
- "displayName": "Unit",
- "value": "Impressions"
}, - "currentLevel": {
- "displayName": "Current Level",
- "value": 360
}, - "fillRate": {
- "displayName": "Fill rate",
- "value": 0.06
}, - "maxLevel": {
- "displayName": "Max Level",
- "value": 6000
}, - "pctRemaining": {
- "displayName": "Percent Remaining",
- "value": 6
}, - "type": {
- "displayName": "Type",
- "value": "toner"
}, - "color": {
- "displayName": "Color",
- "value": "black"
}, - "description": {
- "displayName": "Description",
- "value": "Black Toner"
}, - "displayableName": {
- "displayName": "Displayable Name",
- "value": "Black Toner"
}, - "partNum": {
- "displayName": "Part Number",
- "value": "52D0Z00"
}
}
}
}, - "lastMeterRead": {
- "installKey": "000000000000000000000003",
- "deviceKey": "000000000000000000000006",
- "timestamp": "2021-01-01T01:44:44.000Z",
- "pageCounts": {
- "life": {
- "total": {
- "value": 100,
- "displayName": "Total"
}, - "totalBlack": {
- "value": 75,
- "displayName": "Total Black"
}, - "totalColor": {
- "value": 25,
- "displayName": "Total Color"
}
}, - "equiv": {
- "total": {
- "value": 200,
- "displayName": "Total"
}, - "totalBlack": {
- "value": 150,
- "displayName": "Total Black"
}, - "totalColor": {
- "value": 50,
- "displayName": "Total Color"
}
}
}, - "supplies": {
- "blackToner": {
- "serialNum": {
- "displayName": "Serial Number",
- "value": "CAB231222A22"
}, - "sidesOnSupply": {
- "displayName": "Sides on Supply",
- "value": 4869
}, - "unit": {
- "displayName": "Unit",
- "value": "Impressions"
}, - "currentLevel": {
- "displayName": "Current Level",
- "value": 360
}, - "fillRate": {
- "displayName": "Fill rate",
- "value": 0.06
}, - "maxLevel": {
- "displayName": "Max Level",
- "value": 6000
}, - "pctRemaining": {
- "displayName": "Percent Remaining",
- "value": 6
}, - "type": {
- "displayName": "Type",
- "value": "toner"
}, - "color": {
- "displayName": "Color",
- "value": "black"
}, - "description": {
- "displayName": "Description",
- "value": "Black Toner"
}, - "displayableName": {
- "displayName": "Displayable Name",
- "value": "Black Toner"
}, - "partNum": {
- "displayName": "Part Number",
- "value": "52D0Z00"
}
}
}
}, - "attributes": {
- "serialNum": {
- "displayName": "Serial Number",
- "value": "CAB231222A22"
}, - "sidesOnSupply": {
- "displayName": "Sides on Supply",
- "value": 4869
}, - "unit": {
- "displayName": "Unit",
- "value": "Impressions"
}, - "currentLevel": {
- "displayName": "Current Level",
- "value": 360
}, - "fillRate": {
- "displayName": "Fill rate",
- "value": 0.06
}, - "maxLevel": {
- "displayName": "Max Level",
- "value": 6000
}, - "pctRemaining": {
- "displayName": "Percent Remaining",
- "value": 6
}, - "type": {
- "displayName": "Type",
- "value": "toner"
}, - "color": {
- "displayName": "Color",
- "value": "black"
}, - "description": {
- "displayName": "Description",
- "value": "Black Toner"
}, - "displayableName": {
- "displayName": "Displayable Name",
- "value": "Black Toner"
}, - "partNum": {
- "displayName": "Part Number",
- "value": "52D0Z00"
}
}, - "statistics": {
- "estimatedDepletionDate": "2021-01-01T01:44:44.000Z",
- "estimatedDepletionDateSource": "Calculated",
- "fillRate": 0.06,
- "actualCostPerPage": 0.06,
- "lostPages": 150,
- "volumeByFormat": {
- "life": 100,
- "equiv": 200
}, - "granularity": 1
}, - "settings": {
- "partNumber": "CF410A",
- "expectedFillRate": 0.05,
- "expectedYield": 6000,
- "supplyCost": 120.55
}
}
Get events by entity
Returns an array of events for the specified entity.
Authorizations:
path Parameters
entityId required | any The ID of the entity to load meters from. |
query Parameters
excludeDisabled | boolean Default: false If true, only events from managed devices will be returned. |
includeChildren | boolean Default: false If true, events from this entity and child entities will be returned. |
start required | any Example: start=2020-12-18T17:52:52.417Z The start of the event read date range formatted as RFC3339, ISO8601 (without timezone), RFC1123Z, RFC1123, RFC1123, RFC822Z, RFC822, RFC8250, ANSIC, or Unix. |
end required | any Example: end=2021-01-25T17:52:52.417Z The end of the event read date range formatted as RFC3339, ISO8601 (without timezone), RFC1123Z, RFC1123, RFC1123, RFC822Z, RFC822, RFC8250, ANSIC, or Unix. |
Responses
Response samples
- 200
[- {
- "id": "000000000000000000000006",
- "createdDate": "2021-01-01T01:44:44.000Z",
- "modifiedDate": "2021-01-01T01:44:44.000Z",
- "entityKey": "000000000000000000000002",
- "installKey": "000000000000000000000003",
- "deviceKey": "000000000000000000000006",
- "deviceSerialNumber": "SN12345",
- "timestamp": "2021-01-01T01:44:44.000Z",
- "description": "A black toner was replaced",
- "alertType": null,
- "supplyKey": "blackToner",
- "resolutionStatus": "Open",
- "acknowledged": {
- "timestamp": "2021-01-01T01:44:44.000Z",
- "note": "string",
- "userKey": "000000000000000000000001",
- "userName": "John Doe"
}, - "meterRead": {
- "installKey": "000000000000000000000003",
- "deviceKey": "000000000000000000000006",
- "timestamp": "2021-01-01T01:44:44.000Z",
- "pageCounts": {
- "life": {
- "total": {
- "value": 100,
- "displayName": "Total"
}, - "totalBlack": {
- "value": 75,
- "displayName": "Total Black"
}, - "totalColor": {
- "value": 25,
- "displayName": "Total Color"
}
}, - "equiv": {
- "total": {
- "value": 200,
- "displayName": "Total"
}, - "totalBlack": {
- "value": 150,
- "displayName": "Total Black"
}, - "totalColor": {
- "value": 50,
- "displayName": "Total Color"
}
}
}, - "supplies": {
- "blackToner": {
- "serialNum": {
- "displayName": "Serial Number",
- "value": "CAB231222A22"
}, - "sidesOnSupply": {
- "displayName": "Sides on Supply",
- "value": 4869
}, - "unit": {
- "displayName": "Unit",
- "value": "Impressions"
}, - "currentLevel": {
- "displayName": "Current Level",
- "value": 360
}, - "fillRate": {
- "displayName": "Fill rate",
- "value": 0.06
}, - "maxLevel": {
- "displayName": "Max Level",
- "value": 6000
}, - "pctRemaining": {
- "displayName": "Percent Remaining",
- "value": 6
}, - "type": {
- "displayName": "Type",
- "value": "toner"
}, - "color": {
- "displayName": "Color",
- "value": "black"
}, - "description": {
- "displayName": "Description",
- "value": "Black Toner"
}, - "displayableName": {
- "displayName": "Displayable Name",
- "value": "Black Toner"
}, - "partNum": {
- "displayName": "Part Number",
- "value": "52D0Z00"
}
}
}
}, - "attributes": {
- "blackToner": {
- "serialNum": {
- "displayName": "Serial Number",
- "value": "CAB231222A22"
}, - "sidesOnSupply": {
- "displayName": "Sides on Supply",
- "value": 4869
}, - "unit": {
- "displayName": "Unit",
- "value": "Impressions"
}, - "currentLevel": {
- "displayName": "Current Level",
- "value": 360
}, - "fillRate": {
- "displayName": "Fill rate",
- "value": 0.06
}, - "maxLevel": {
- "displayName": "Max Level",
- "value": 6000
}, - "pctRemaining": {
- "displayName": "Percent Remaining",
- "value": 6
}, - "type": {
- "displayName": "Type",
- "value": "toner"
}, - "color": {
- "displayName": "Color",
- "value": "black"
}, - "description": {
- "displayName": "Description",
- "value": "Black Toner"
}, - "displayableName": {
- "displayName": "Displayable Name",
- "value": "Black Toner"
}, - "partNum": {
- "displayName": "Part Number",
- "value": "52D0Z00"
}
}
}
}
]
Update event
Update an event using its ID
Authorizations:
path Parameters
entityId required | any The ID of the entity that this event belongs to. |
eventId required | any The ID of the event to update. |
Request Body schema: application/json
resolutionStatus | string (ResolutionStatus) Enum: "Open" "In Progress" "Resolved" |
Responses
Request samples
- Payload
{- "resolutionStatus": "Open"
}
Response samples
- 200
{- "id": "000000000000000000000006",
- "createdDate": "2021-01-01T01:44:44.000Z",
- "modifiedDate": "2021-01-01T01:44:44.000Z",
- "entityKey": "000000000000000000000002",
- "installKey": "000000000000000000000003",
- "deviceKey": "000000000000000000000006",
- "deviceSerialNumber": "SN12345",
- "timestamp": "2021-01-01T01:44:44.000Z",
- "description": "A black toner was replaced",
- "alertType": null,
- "supplyKey": "blackToner",
- "resolutionStatus": "Open",
- "acknowledged": {
- "timestamp": "2021-01-01T01:44:44.000Z",
- "note": "string",
- "userKey": "000000000000000000000001",
- "userName": "John Doe"
}, - "meterRead": {
- "installKey": "000000000000000000000003",
- "deviceKey": "000000000000000000000006",
- "timestamp": "2021-01-01T01:44:44.000Z",
- "pageCounts": {
- "life": {
- "total": {
- "value": 100,
- "displayName": "Total"
}, - "totalBlack": {
- "value": 75,
- "displayName": "Total Black"
}, - "totalColor": {
- "value": 25,
- "displayName": "Total Color"
}
}, - "equiv": {
- "total": {
- "value": 200,
- "displayName": "Total"
}, - "totalBlack": {
- "value": 150,
- "displayName": "Total Black"
}, - "totalColor": {
- "value": 50,
- "displayName": "Total Color"
}
}
}, - "supplies": {
- "blackToner": {
- "serialNum": {
- "displayName": "Serial Number",
- "value": "CAB231222A22"
}, - "sidesOnSupply": {
- "displayName": "Sides on Supply",
- "value": 4869
}, - "unit": {
- "displayName": "Unit",
- "value": "Impressions"
}, - "currentLevel": {
- "displayName": "Current Level",
- "value": 360
}, - "fillRate": {
- "displayName": "Fill rate",
- "value": 0.06
}, - "maxLevel": {
- "displayName": "Max Level",
- "value": 6000
}, - "pctRemaining": {
- "displayName": "Percent Remaining",
- "value": 6
}, - "type": {
- "displayName": "Type",
- "value": "toner"
}, - "color": {
- "displayName": "Color",
- "value": "black"
}, - "description": {
- "displayName": "Description",
- "value": "Black Toner"
}, - "displayableName": {
- "displayName": "Displayable Name",
- "value": "Black Toner"
}, - "partNum": {
- "displayName": "Part Number",
- "value": "52D0Z00"
}
}
}
}, - "attributes": {
- "blackToner": {
- "serialNum": {
- "displayName": "Serial Number",
- "value": "CAB231222A22"
}, - "sidesOnSupply": {
- "displayName": "Sides on Supply",
- "value": 4869
}, - "unit": {
- "displayName": "Unit",
- "value": "Impressions"
}, - "currentLevel": {
- "displayName": "Current Level",
- "value": 360
}, - "fillRate": {
- "displayName": "Fill rate",
- "value": 0.06
}, - "maxLevel": {
- "displayName": "Max Level",
- "value": 6000
}, - "pctRemaining": {
- "displayName": "Percent Remaining",
- "value": 6
}, - "type": {
- "displayName": "Type",
- "value": "toner"
}, - "color": {
- "displayName": "Color",
- "value": "black"
}, - "description": {
- "displayName": "Description",
- "value": "Black Toner"
}, - "displayableName": {
- "displayName": "Displayable Name",
- "value": "Black Toner"
}, - "partNum": {
- "displayName": "Part Number",
- "value": "52D0Z00"
}
}
}
}
Billing usage by entity
Returns a list of SKUs and their associated quantities for a given entity. You can provide any entity and this endpoint will return the billable resources from the perspective of that entity. For example, if you provide your dealer entity key, you'll get SKUs and quantities that could be correlated to your monthly invoice. If you were to provide a customer entity, you'd see only the usage contributed to your account by that customer.
Authorizations:
path Parameters
entityId required | any The ID of the entity that we want to pull supplies |
query Parameters
year required | any Example: year=2023 The year to pull billing usage for |
month required | any Example: month=1 The month to pull billing usage for. Months are numbered 1-12 starting with January. |
Responses
Response samples
- 200
[- {
- "sku": "PTRDVC",
- "quantity": 150,
- "description": "string"
}
]