Pular para o conteúdo principal
API docs by Redocly

Print Tracker API (1.0.0)

Download OpenAPI specification:Download

License: MIT

Entity

Get an entity

Returns an entity object for the provided entity ID.

Authorizations:
ApiKeyAuth
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

Content type
application/json
{
  • "id": "000000000000000000000002",
  • "name": "My Company",
  • "genealogy": [
    ],
  • "addresses": [
    ],
  • "children": [
    ],
  • "labels": {
    }
}

Create an entity

Creates a new entity underneath the entity specified in the path parameters.

Authorizations:
ApiKeyAuth
path Parameters
entityId
any

The ID of the entity to create a child entity under.

Request Body schema: application/json
required
name
string

The name of the entity to create

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "id": "000000000000000000000002",
  • "name": "My Company",
  • "genealogy": [
    ],
  • "addresses": [
    ],
  • "children": [
    ],
  • "labels": {
    }
}

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:
ApiKeyAuth
path Parameters
entityId
any

The ID of the entity to update.

Request Body schema: application/json
required
name
string

The name of the entity to update

Array of objects
reset
Array of strings

Responses

Request samples

Content type
application/json
{
  • "name": "New entity name",
  • "set": [
    ],
  • "reset": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "000000000000000000000002",
  • "name": "My Company",
  • "genealogy": [
    ],
  • "addresses": [
    ],
  • "children": [
    ],
  • "labels": {
    }
}

Delete an entity

Deletes the entity and all of its children.

Authorizations:
ApiKeyAuth
path Parameters
entityId
required
any

The ID of the entity to delete.

Responses

Response samples

Content type
application/json
null

Devices

Get devices by entity

Returns an array of devices that belong to the specified entity and (optionally) its children.

Authorizations:
ApiKeyAuth
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.

serialNumber
string
Default: false
Example: serialNumber=SN123,SNABC

A comma-separated list of serial numbers to search

Responses

Response samples

Content type
application/json
[
  • {
    }
]

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:
ApiKeyAuth
path Parameters
entityId
required
any

The ID of the entity to load devices from.

Request Body schema: application/json
required
Array
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

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

Update a device

Updates the specified fields on a device

Authorizations:
ApiKeyAuth
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
required
macAddress
string
assetId
string
customLocation
string
note
string
labels
object

Responses

Request samples

Content type
application/json
{
  • "macAddress": "00:00:00:00:00:00",
  • "assetId": 12345,
  • "customLocation": "Room 123",
  • "note": "This is a note",
  • "labels": {
    }
}

Response samples

Content type
application/json
{
  • "id": "000000000000000000000006",
  • "createdDate": "2021-01-01T01:44:44.000Z",
  • "modifiedDate": "2021-01-01T01:44:44.000Z",
  • "entityKey": "000000000000000000000002",
  • "installKeys": [
    ],
  • "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": {
    },
  • "labels": {
    },
  • "managed": true
}

Delete a device

Deletes the device and all associated data including meter history, supply history, etc.

Authorizations:
ApiKeyAuth
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

Content type
application/json
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:
ApiKeyAuth
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
required
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:

  • blackToner
  • cyanToner
  • magentaToner
  • yellowToner
  • blackInk
  • cyanInk
  • magentaInk
  • yellowInk
  • blackDrum
  • cyanDrum
  • magentaDrum
  • yellowDrum

Responses

Request samples

Content type
application/json
{
  • "skipsRemaining": 1,
  • "supplyKey": "blackToner"
}

Response samples

Content type
application/json
null

Installs

Get installs by entity

Returns an array of installs that belong to the specified entity and (optionally) its children.

Authorizations:
ApiKeyAuth
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.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get installs by device

Returns an array of installs associated with the specified device. A device may be tracked by more than one install, and this endpoint returns all of them.

Authorizations:
ApiKeyAuth
path Parameters
entityId
required
any

The ID of the entity the device belongs to.

deviceId
required
any

The ID of the device to load installs for.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Meters

Get meters by entity

Returns an array of meter reads for the specified entity.

Authorizations:
ApiKeyAuth
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

Content type
application/json
[
  • {
    }
]

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:
ApiKeyAuth
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

Content type
application/json
[
  • {
    }
]

Get meters by device

Returns an array of meter reads for a single device

Authorizations:
ApiKeyAuth
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

Content type
application/json
[
  • {
    }
]

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 a default format.
  • Each pageCounts format must contain at least a total counter.
Authorizations:
ApiKeyAuth
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
timestamp
string

The timestamp of the meter read formatted as RFC3339

object

Responses

Request samples

Content type
application/json
{
  • "meters": [
    ]
}

Response samples

Content type
application/json
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:
ApiKeyAuth
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

Content type
application/json
[
  • {
    }
]

Supplies

Get supplies by entity

Returns all the supplies from all the devices belonging to the specified entity or its children.

Authorizations:
ApiKeyAuth
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 replaced is true, only supplies replaced after this date will be included. The date should be 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

If replaced is true, only supplies replaced before this date will be included. The date should be formatted as RFC3339, ISO8601 (without timezone), RFC1123Z, RFC1123, RFC1123, RFC822Z, RFC822, RFC8250, ANSIC, or Unix.

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

Content type
application/json
[
  • {
    }
]

Get supplies by device

Returns all the supplies for a single device

Authorizations:
ApiKeyAuth
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 replaced is true, only supplies replaced after this date will be included. The date should be 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

If replaced is true, only supplies replaced before this date will be included. The date should be formatted as RFC3339, ISO8601 (without timezone), RFC1123Z, RFC1123, RFC1123, RFC822Z, RFC822, RFC8250, ANSIC, or Unix.

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

Content type
application/json
[
  • {
    }
]

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:
ApiKeyAuth
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
required
Array of objects
reset
Array of strings

Responses

Request samples

Content type
application/json
{
  • "set": [
    ],
  • "reset": [
    ]
}

Response samples

Content type
application/json
{
  • "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": {
    },
  • "lastMeterRead": {
    },
  • "attributes": {
    },
  • "statistics": {
    },
  • "settings": {
    }
}

Events

Get events by entity

Returns an array of events for the specified entity.

Authorizations:
ApiKeyAuth
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

Content type
application/json
[
  • {
    }
]

Update event

Update an event using its ID

Authorizations:
ApiKeyAuth
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

Content type
application/json
{
  • "resolutionStatus": "Open"
}

Response samples

Content type
application/json
{
  • "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": {
    },
  • "meterRead": {
    },
  • "attributes": {
    }
}

Billing

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:
ApiKeyAuth
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

Content type
application/json
[
  • {
    }
]