REST Reference

Download JSDoc Helper
©2024 Trak-iT Wireless Inc.
Updated Wednesday August 21, 2024 09:47AM
Version 6.2.04
Beta end-point:
https://mindflayer.trakit.ca/
Production end-point:
https://rest.trakit.ca/

API Definitions

GET/timezones

Gets a list of Timezones.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.
timezones	Array.<Timezone>	The list of valid system Timezones.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number,
	"timezones": [
		{
			"code": string,
			"dst": boolean,
			"name": string,
			"offset": number
		}
	]
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	System Timezone list could not be retrieved. If you receive this error, please contact technical support.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.

GET/timezones/{code}

Gets details of the specified Timezone.

URL Parameters

Parameter	Type	Required	Description
code	string	required	Unique identifier of the Timezone.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.
timezone	Timezone	The requested Timezone.
timezone.code	codified	Unique timezone code
timezone.dst	boolean	Indicates whether this timezone abides by daylight savings
timezone.name	string	Common timezone name
timezone.offset	int16	Minutes offset from GMT

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number,
	"timezone": {
		"code": string,
		"dst": boolean,
		"name": string,
		"offset": number
	}
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a timezone object, or it is invalid.
400	3	The timezone object does not contain a code, or it is invalid.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	62	The Timezone was not found by its codified identifier.

Assets

GET/assets?includeSuspended=boolean&includeMessages=boolean&includeTasks=boolean&includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

This request is an alias of /companies/{your-company-id}/assets (when no additional query-string parameters are given) or /companies/{your-company-id}/assets?{keys=values} (when at least one additional query-string key/value is given).

URL Parameters

Parameter	Type	Required	Default	Description
highest	uint64	optional		When using , sets the maximum id when listing from the database.
includeArchive	boolean	optional	`false`	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	`false`	False by default, but when true the command will also return deleted objects.
includeMessages	boolean	optional	`false`	False by default, but when true will include Asset.messages..
includeSuspended	boolean	optional	`true`	When true (default), the command will also return Assets marked as Asset.suspended.
includeTasks	boolean	optional	`false`	False by default, but when true will include Asset.tasks..
limit	uint16	optional		When using , sets the maximum number of objects in this response.
lowest	uint64	optional		When using , sets the minimum id when listing from the database.
your-company-id	uint64	aliased	`{your-company-id}`	Your own Company's identifier.

PATCH/assets

Creates a new, or updates an existing Asset.

HTTP Request body description

Property	Type	Required	Description
asset	Object.<string, ?>	always	A simple object to contain the Asset parameters.
asset.attributes	Object.<string, AssetAttribute>	optional	Allows you to add, remove, and replace attributes. For each AssetAttribute in the attributes object, the value will be replaced on the Asset. If value is null, the attribute is removed from the Asset. If the key in the attributes object is different from the codified(AssetAttribute.name) in the object, the attribute of the key is removed from the Asset, and one of the codified name is added to the Asset. If a new value or null is not provided for a current attribute, no change is made.
asset.colour	colour maximum-length: 22	optional	The pretty-pretty colour of this Vehicle or Trailer. Only applicable if `asset.kind` is AssetType.vehicle or AssetType.trailer.
asset.company	uint64?	create	The identifier of the Company to which this Asset belongs. After creation, this value is read-only.
asset.contact	uint64?	create (for person)	The contact card details for this Asset. Only applicable if `asset.kind` is AssetType.person.
asset.engineHours	double?	optional	The number of hours the engine has been running for this Vehicle. Only applicable if `asset.kind` is AssetType.vehicle.
asset.icon	uint64? see: Icon.id	create	The identifier of the Icon used to represent this Asset in the UI.
asset.id	uint64?	update	The unique identifier of the Asset you want to update.
asset.kind	AssetType?	create	The kind of Asset being created. After creation, this value is read-only.
asset.labels	Array.<codified> for values see: LabelStyle.code	optional	A list of codified label names to categorize/organize this Asset.
asset.make	string	optional	The manufacturer of this Vehicle or Trailer. Only applicable if `asset.kind` is AssetType.vehicle or AssetType.trailer.
asset.messagingAddress	string	optional	The email address or phone number of this Asset when a Person's Contact card is blank, or the Provider's PND is not installed.
asset.model	string	optional	The model of this Vehicle or Trailer. Only applicable if `asset.kind` is AssetType.vehicle or AssetType.trailer.
asset.name	string maximum-length: 100	create	Name for the Asset.
asset.notes	string	optional	Notes for the Asset.
asset.odometer	double?	optional	The distance travelled by this Asset. Can be a GPS odometer, OBD-II odometer, or other depending on scripts.
asset.pictures	Array.<uint64> for values see: Picture.id	optional	The identifiers of Pictures of this Asset.
asset.plate	string	optional	The license plate of this Vehicle or Trailer. Only applicable if `asset.kind` is AssetType.vehicle or AssetType.trailer.
asset.references	Object.<string, string>	optional	Name/value collections of custom fields used to refer to external systems. If the value is null, the references are removed from the Asset.
asset.relationships	Array.<uint64> for values see: Asset.id	optional	A list of related asset identifiers like a driver for a Vehicle, or Trailer for a truck.
asset.serial	string	optional	The manufacturer's identification number of this Trailer. Only applicable if `asset.kind` is AssetType.vehicle.
asset.tags	Array.<string>	optional	Replaces the Asset's status tags with the given list of codified tags.
asset.v	Array.<int32>	optional
asset.vin	string	optional	The Vehicle Identification Number of this Vehicle. Only applicable if `asset.kind` is AssetType.trailer.
asset.year	uint16?	optional	The year this Vehicle or Trailer was built. Only applicable if `asset.kind` is AssetType.vehicle or AssetType.trailer.
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"asset": {
		"attributes": {
			string: {
				"asset": number,
				"complex": string,
				"dts": string,
				"global": boolean,
				"name": string,
				"provider": string,
				"raw": Object,
				"simple": string,
				"unit": string
			}
		},
		"colour": string,
		"company": number,
		"contact": number,
		"engineHours": number,
		"icon": number,
		"id": number,
		"kind": string,
		"labels": [
			string
		],
		"make": string,
		"messagingAddress": string,
		"model": string,
		"name": string,
		"notes": string,
		"odometer": number,
		"pictures": [
			number
		],
		"plate": string,
		"references": {
			string: string
		},
		"relationships": [
			number
		],
		"serial": string,
		"tags": [
			string
		],
		"v": [
			number
		],
		"vin": string,
		"year": number
	},
	"reqId": number
}

Response description

Property	Type	Description
asset	RespIdCompany	An object which contains the "id" and "company" keys.
asset.company	uint64	Identifier of the Company to which this object belongs.
asset.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"asset": {
		"company": number,
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a asset object, or it is invalid.
400	3	No valid changes would be performed.
400	3	During create: When creating a new Asset, a name was not given.
400	3	During create: When creating a new Asset, a company was not given.
400	3	During create: When creating a new Asset, an icon was not given.
400	3	During create (for person): When creating a new Person, a contact was not given.
400	3	During update: When updating an Asset, the name was given as null or blank.
400	3	During update: When updating an Asset, the v was not an array, or contained too few numbers.
400	3	During create: The kind value is not a known AssetType. Returns an ErrorDetailEnum as the `errorDetails`.
400	3	One of the asset.attributes names is invalid. Returns an ErrorDetailInput as the `errorDetails`.
400	3	One of the asset.attributes values is not null or an object. Returns an ErrorDetailInput as the `errorDetails`.
400	3	The asset.attributes object is given, but empty. Returns an ErrorDetailInput as the `errorDetails`.
400	3	The asset.messagingAddress contains values that cannot be parsed as a phone number or email address. Returns an ErrorDetailInput as the `errorDetails`.
400	3	One of the asset.pictures given in the array cannot be parsed, or is a value less than zero. Returns an ErrorDetailInput as the `errorDetails`.
400	3	The asset.references were not provided as null or an object. Returns an ErrorDetailInput as the `errorDetails`.
400	3	One of the asset.relationships given in the array cannot be parsed, or is a value less than zero. Returns an ErrorDetailInput as the `errorDetails`.
400	3	During create: When creating a new Asset, too many asset.references were given as input. Returns an ErrorDetailMinMax as the `errorDetails`.
401	5	You do not have permission to create a new Asset.
401	5	You do not have permission to update this Asset.
400	6	During update: When updating an Asset, an incorrect v value was given as input.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	20	During update: When updating, the Asset was not found by its unique identifier.
404	22	One of the Assets given as input in the asset.relationships array was not found. Returns an ErrorDetailBadIds as the `errorDetails`.
404	31	The asset.contact given as input was not found.
404	33	The asset.icon given as input was not found.
404	69	One of the asset.pictures given as input in the pictures array was not found. Returns an ErrorDetailBadIds as the `errorDetails`.
401	71	During update: Changing the labels on this Asset in the requested way would grant you elevated access to it. Returns an ErrorDetailEscalation as the `errorDetails`.
403	96	During update: When updating, the Asset is suspended. Before making changes to an Asset, it must be reactivated.
409	130	During update: When updating an Asset, the asset.company can not be changed.
409	130	During update: When updating an Asset, the asset.kind can not be changed.
409	130	During update: When updating an Asset, the resulting number of asset.references would be too high.

DELETE/assets

Deletes an existing Asset.

Response description

Property	Type	Description
asset	RespDeleted	An object which contains the Asset's id, owning Company id, and deleted status.
asset.company	uint64	Identifier of the Company to which this object belongs.
asset.deleted	boolean	Flag showing if the object is deleted.
asset.id	uint64?	Identifier given as input for the command.
asset.v	Array.<uint32>
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"asset": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a asset object, or it is invalid.
400	3	The asset object does not contain an id, or it is invalid.
401	5	You do not have permission to delete this Asset.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	20	The Asset was not found by its unique identifier.

GET/assets/{assetId}?includeMessages=boolean&includeTasks=boolean&includeDeleted=boolean

Gets details of the specified Asset.

URL Parameters

Parameter	Type	Required	Default	Description
assetId	uint64	required		Unique identifier of the Asset.
includeDeleted	boolean	optional		False by default, but when true the command will also return deleted objects.
includeMessages	boolean	optional	`false`	False by default, but when true, the command will also return AssetMessages for the asset.
includeTasks	boolean	optional	`false`	False by default, but when true the command will also return the AssetDispatch for the asset.

Response description

Property	Type	Description
asset	Asset	The requested Asset.
asset.attributes	Object.<codified, AssetAttribute> for keys see: AssetAttribute.name	A list of attributes given to this asset by the connection device such as wiring state, VBus, etc.
asset.company	uint64 see: Company.id	The company to which this asset belongs.
asset.dispatch	AssetDispatch	Current jobs dispatched and driving directions.
asset.dispatch.company	uint64 see: Company.id	The company to which this asset belongs.
asset.dispatch.directions	Array.<DispatchDirection>	Driving directions and route path details.
asset.dispatch.id	uint64 see: Asset.id	Unique identifier of this asset.
asset.dispatch.jobs	Array.<uint64> see: DispatchJob	The current list of DispatchJobs assigned to the asset.
asset.dispatch.lastDispatched	datetime	Timestamp from the last update to this AssetDispatch by a User, Machine, Asset, or an assigned DispatchJob.
asset.dispatch.processedUtc	datetime	When the was change procesed.
asset.dispatch.tasks Deprecated	Array.<DispatchTask>	The current list of tasks assigned to this asset.
asset.dispatch.updated		by: login, from: monster
asset.dispatch.v	Array.<uint32>	Object version keys used to validate synchronization for all object properties.
asset.icon	uint64 see: Icon.id	The icon that represents this asset on the map and in lists.
asset.id	uint64	Unique identifier of this asset.
asset.kind	AssetType	Type of asset.
asset.labels	Array.<codified> for values see: LabelStyle.code	Codified label names.
asset.messages	Array.<AssetMessage>	A list of messages sent to or from this asset.
asset.messagingAddress	string maximum-length: 254	The fall-back address which is used to send Messages if the asset is a Person and has no Contact phone or email.
asset.name	string maximum-length: 100	This thing's name.
asset.notes	string	Notes about it.
asset.odometer	double	The cumulative distance travelled in kilometres.
asset.pictures	Array.<uint64> for values see: Picture.id	A list of photos of this thing.
asset.places	Object.<uint64, AssetPlaceStatus> for keys see: Place.id	The current state of this asset's interaction with known Places.
asset.position	Position	The things GPS coordinates including speed, bearing, and street information.
asset.position.accuracy	uint32?	Threshold in meters for the accuracy of a position
asset.position.address	string	The road segment description
asset.position.altitude	double?	Distance in meters from the sea level
asset.position.bearing	uint16?	Direction of travel
asset.position.dts	datetime	The Date/Time of the GPS reading
asset.position.lat	double?	Latitude
asset.position.lng	double?	Longitude
asset.position.origin	string	Provider Identifier
asset.position.speed	double?	Speed
asset.position.speedLimit	double?	The posted speed limit for the road segment
asset.position.streetAddress	StreetAddress	A better description of the current road-segment
asset.position.streetAddress.city	string	City name.
asset.position.streetAddress.country	string fixed length: 2	Country code. Codes should be a value from ISO 3166-1 alpha-2.
asset.position.streetAddress.isToll	boolean	Indicates that there is a toll for the current road segment.
asset.position.streetAddress.number	string	House number.
asset.position.streetAddress.postal	string	Postal or zip code.
asset.position.streetAddress.province	string fixed length: 2	Province or state code. Codes should be a value from ISO 3166-2.
asset.position.streetAddress.region	string	Region name.
asset.position.streetAddress.street	string	Full street name.
asset.processedUtc	datetime	When the was change procesed.
asset.providers	Array.<string> for values see: Provider.id	The list of devices providing events for this asset.
asset.reference Deprecated	string maximum-length: 100	A custom field used to refer to an external system. Use asset.references[AssetGeneral.REFERENCE] instead.
asset.references	Object.<string, string> maximum-count: 10 maximum-length of keys: 20 maximum-length of values: 100	Name/value collections of custom fields used to refer to external systems.
asset.relationships	Array.<uint64> for values see: Asset.id	A list of assets related to this one; like a Person for a Vehicle (driver).
asset.tags	Array.<codified> for values see: LabelStyle.code	The codified status tag names.
asset.updated		by: login, from: monster
asset.v	Array.<int32> fixed count: 3	Object version keys used to validate synchronization for all object properties.
asset.v[0]	int32	The first element is for the AssetGeneral properties.
asset.v[1]	int32	The second element is for the AssetAdvanced properties.
asset.v[2]	int32	The third element is for the Asset.dispatch properties.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"asset": {
		"attributes": {
			string: {
				"asset": number,
				"complex": string,
				"dts": string,
				"global": boolean,
				"name": string,
				"provider": string,
				"raw": Object,
				"simple": string,
				"unit": string
			}
		},
		"company": number,
		"dispatch": {
			"company": number,
			"directions": [
				{
					"directions": [
						{ /* recursive DispatchDirection objects */ }
					],
					"distance": number,
					"duration": string,
					"instructions": string,
					"job": number,
					"path": string,
					"step": number
				}
			],
			"id": number,
			"jobs": [
				number
			],
			"lastDispatched": string,
			"processedUtc": string,
			"tasks": [
				{
					"address": string,
					"arrived": string,
					"asset": number,
					"attachments": [
						number
					],
					"company": number,
					"completed": string,
					"created": string,
					"duration": string,
					"eta": string,
					"id": number,
					"instructions": string,
					"latlng": {
						"lat": number,
						"lng": number
					},
					"name": string,
					"notes": string,
					"place": number,
					"processedUtc": string,
					"reference": string,
					"references": {
						string: string
					},
					"signatory": string,
					"signature": boolean,
					"status": string,
					"updated": {
					},
					"v": [
						number
					]
				}
			],
			"updated": {
			},
			"v": [
				number
			]
		},
		"icon": number,
		"id": number,
		"kind": string,
		"labels": [
			string
		],
		"messages": [
			{
				"asset": number,
				"body": string,
				"company": number,
				"delivered": string,
				"folder": string,
				"from": string,
				"id": number,
				"incoming": boolean,
				"kind": string,
				"processed": string,
				"processedUtc": string,
				"readBy": string,
				"status": string,
				"subject": string,
				"to": string,
				"updated": {
				},
				"user": string,
				"v": [
					number
				]
			}
		],
		"messagingAddress": string,
		"name": string,
		"notes": string,
		"odometer": number,
		"pictures": [
			number
		],
		"places": {
			string: {
				"enter": string,
				"kind": string,
				"latest": string
			}
		},
		"position": {
			"accuracy": number,
			"address": string,
			"altitude": number,
			"bearing": number,
			"dts": string,
			"lat": number,
			"lng": number,
			"origin": string,
			"speed": number,
			"speedLimit": number,
			"streetAddress": {
				"city": string,
				"country": string,
				"isToll": boolean,
				"number": string,
				"postal": string,
				"province": string,
				"region": string,
				"street": string
			}
		},
		"processedUtc": string,
		"providers": [
			string
		],
		"reference": string,
		"references": {
			string: string
		},
		"relationships": [
			number
		],
		"tags": [
			string
		],
		"updated": {
		},
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a asset object, or it is invalid.
400	3	The asset object does not contain an id, or it is invalid.
401	5	You do not have permission to view this Asset.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	20	The Asset was not found by its unique identifier.

POST/assets/{assetId}

Creates a new, or updates an existing Asset.

URL Parameters

Parameter	Type	Required	Description
assetId	uint64?	optional	Unique identifier of the Asset. This value is optional, and ignored by the command.

HTTP Request body description

Property	Type	Required	Description
asset	Object.<string, ?>	always	A simple object to contain the Asset parameters.
asset.attributes	Object.<string, AssetAttribute>	optional	Allows you to add, remove, and replace attributes. For each AssetAttribute in the attributes object, the value will be replaced on the Asset. If value is null, the attribute is removed from the Asset. If the key in the attributes object is different from the codified(AssetAttribute.name) in the object, the attribute of the key is removed from the Asset, and one of the codified name is added to the Asset. If a new value or null is not provided for a current attribute, no change is made.
asset.colour	colour maximum-length: 22	optional	The pretty-pretty colour of this Vehicle or Trailer. Only applicable if `asset.kind` is AssetType.vehicle or AssetType.trailer.
asset.company	uint64?	create	The identifier of the Company to which this Asset belongs. After creation, this value is read-only.
asset.contact	uint64?	create (for person)	The contact card details for this Asset. Only applicable if `asset.kind` is AssetType.person.
asset.engineHours	double?	optional	The number of hours the engine has been running for this Vehicle. Only applicable if `asset.kind` is AssetType.vehicle.
asset.icon	uint64? see: Icon.id	create	The identifier of the Icon used to represent this Asset in the UI.
asset.id	uint64?	update	The unique identifier of the Asset you want to update.
asset.kind	AssetType?	create	The kind of Asset being created. After creation, this value is read-only.
asset.labels	Array.<codified> for values see: LabelStyle.code	optional	A list of codified label names to categorize/organize this Asset.
asset.make	string	optional	The manufacturer of this Vehicle or Trailer. Only applicable if `asset.kind` is AssetType.vehicle or AssetType.trailer.
asset.messagingAddress	string	optional	The email address or phone number of this Asset when a Person's Contact card is blank, or the Provider's PND is not installed.
asset.model	string	optional	The model of this Vehicle or Trailer. Only applicable if `asset.kind` is AssetType.vehicle or AssetType.trailer.
asset.name	string maximum-length: 100	create	Name for the Asset.
asset.notes	string	optional	Notes for the Asset.
asset.odometer	double?	optional	The distance travelled by this Asset. Can be a GPS odometer, OBD-II odometer, or other depending on scripts.
asset.pictures	Array.<uint64> for values see: Picture.id	optional	The identifiers of Pictures of this Asset.
asset.plate	string	optional	The license plate of this Vehicle or Trailer. Only applicable if `asset.kind` is AssetType.vehicle or AssetType.trailer.
asset.references	Object.<string, string>	optional	Name/value collections of custom fields used to refer to external systems. If the value is null, the references are removed from the Asset.
asset.relationships	Array.<uint64> for values see: Asset.id	optional	A list of related asset identifiers like a driver for a Vehicle, or Trailer for a truck.
asset.serial	string	optional	The manufacturer's identification number of this Trailer. Only applicable if `asset.kind` is AssetType.vehicle.
asset.tags	Array.<string>	optional	Replaces the Asset's status tags with the given list of codified tags.
asset.v	Array.<int32>	optional
asset.vin	string	optional	The Vehicle Identification Number of this Vehicle. Only applicable if `asset.kind` is AssetType.trailer.
asset.year	uint16?	optional	The year this Vehicle or Trailer was built. Only applicable if `asset.kind` is AssetType.vehicle or AssetType.trailer.
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"asset": {
		"attributes": {
			string: {
				"asset": number,
				"complex": string,
				"dts": string,
				"global": boolean,
				"name": string,
				"provider": string,
				"raw": Object,
				"simple": string,
				"unit": string
			}
		},
		"colour": string,
		"company": number,
		"contact": number,
		"engineHours": number,
		"icon": number,
		"id": number,
		"kind": string,
		"labels": [
			string
		],
		"make": string,
		"messagingAddress": string,
		"model": string,
		"name": string,
		"notes": string,
		"odometer": number,
		"pictures": [
			number
		],
		"plate": string,
		"references": {
			string: string
		},
		"relationships": [
			number
		],
		"serial": string,
		"tags": [
			string
		],
		"v": [
			number
		],
		"vin": string,
		"year": number
	},
	"reqId": number
}

Response description

Property	Type	Description
asset	RespIdCompany	An object which contains the "id" and "company" keys.
asset.company	uint64	Identifier of the Company to which this object belongs.
asset.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"asset": {
		"company": number,
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a asset object, or it is invalid.
400	3	No valid changes would be performed.
400	3	During create: When creating a new Asset, a name was not given.
400	3	During create: When creating a new Asset, a company was not given.
400	3	During create: When creating a new Asset, an icon was not given.
400	3	During create (for person): When creating a new Person, a contact was not given.
400	3	During update: When updating an Asset, the name was given as null or blank.
400	3	During update: When updating an Asset, the v was not an array, or contained too few numbers.
400	3	During create: The kind value is not a known AssetType. Returns an ErrorDetailEnum as the `errorDetails`.
400	3	One of the asset.attributes names is invalid. Returns an ErrorDetailInput as the `errorDetails`.
400	3	One of the asset.attributes values is not null or an object. Returns an ErrorDetailInput as the `errorDetails`.
400	3	The asset.attributes object is given, but empty. Returns an ErrorDetailInput as the `errorDetails`.
400	3	The asset.messagingAddress contains values that cannot be parsed as a phone number or email address. Returns an ErrorDetailInput as the `errorDetails`.
400	3	One of the asset.pictures given in the array cannot be parsed, or is a value less than zero. Returns an ErrorDetailInput as the `errorDetails`.
400	3	The asset.references were not provided as null or an object. Returns an ErrorDetailInput as the `errorDetails`.
400	3	One of the asset.relationships given in the array cannot be parsed, or is a value less than zero. Returns an ErrorDetailInput as the `errorDetails`.
400	3	During create: When creating a new Asset, too many asset.references were given as input. Returns an ErrorDetailMinMax as the `errorDetails`.
401	5	You do not have permission to create a new Asset.
401	5	You do not have permission to update this Asset.
400	6	During update: When updating an Asset, an incorrect v value was given as input.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	20	During update: When updating, the Asset was not found by its unique identifier.
404	22	One of the Assets given as input in the asset.relationships array was not found. Returns an ErrorDetailBadIds as the `errorDetails`.
404	31	The asset.contact given as input was not found.
404	33	The asset.icon given as input was not found.
404	69	One of the asset.pictures given as input in the pictures array was not found. Returns an ErrorDetailBadIds as the `errorDetails`.
401	71	During update: Changing the labels on this Asset in the requested way would grant you elevated access to it. Returns an ErrorDetailEscalation as the `errorDetails`.
403	96	During update: When updating, the Asset is suspended. Before making changes to an Asset, it must be reactivated.
409	130	During update: When updating an Asset, the asset.company can not be changed.
409	130	During update: When updating an Asset, the asset.kind can not be changed.
409	130	During update: When updating an Asset, the resulting number of asset.references would be too high.

DELETE/assets/{assetId}

Deletes an existing Asset.

URL Parameters

Parameter	Type	Required	Description
assetId	uint64	required	Unique identifier of the Asset.

Response description

Property	Type	Description
asset	RespDeleted	An object which contains the Asset's id, owning Company id, and deleted status.
asset.company	uint64	Identifier of the Company to which this object belongs.
asset.deleted	boolean	Flag showing if the object is deleted.
asset.id	uint64?	Identifier given as input for the command.
asset.v	Array.<uint32>
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"asset": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a asset object, or it is invalid.
400	3	The asset object does not contain an id, or it is invalid.
401	5	You do not have permission to delete this Asset.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	20	The Asset was not found by its unique identifier.

GET/assets/{assetId}/advanceds?includeDeleted=boolean

Gets details of the specified Asset.

URL Parameters

Parameter	Type	Required	Description
assetId	uint64	required	Unique identifier of the AssetAdvanced.
includeDeleted	boolean	optional	False by default, but when true the command will also return deleted objects.

Response description

Property	Type	Description
assetAdvanced	AssetAdvanced	The requested Asset.
assetAdvanced.attributes	Object.<codified, AssetAttribute> for keys see: AssetAttribute.name	A list of attributes given to this asset by the connection device such as wiring state, VBus, etc.
assetAdvanced.company	uint64 see: Company.id	The company to which this asset belongs.
assetAdvanced.id	uint64 see: Asset.id	Unique identifier of this asset.
assetAdvanced.odometer	double	The cumulative distance travelled in kilometres.
assetAdvanced.places	Object.<uint64, AssetPlaceStatus> for keys see: Place.id	The current state of this asset's interaction with known Places.
assetAdvanced.position	Position	The things GPS coordinates including speed, bearing, and street information.
assetAdvanced.position.accuracy	uint32?	Threshold in meters for the accuracy of a position
assetAdvanced.position.address	string	The road segment description
assetAdvanced.position.altitude	double?	Distance in meters from the sea level
assetAdvanced.position.bearing	uint16?	Direction of travel
assetAdvanced.position.dts	datetime	The Date/Time of the GPS reading
assetAdvanced.position.lat	double?	Latitude
assetAdvanced.position.lng	double?	Longitude
assetAdvanced.position.origin	string	Provider Identifier
assetAdvanced.position.speed	double?	Speed
assetAdvanced.position.speedLimit	double?	The posted speed limit for the road segment
assetAdvanced.position.streetAddress	StreetAddress	A better description of the current road-segment
assetAdvanced.position.streetAddress.city	string	City name.
assetAdvanced.position.streetAddress.country	string fixed length: 2	Country code. Codes should be a value from ISO 3166-1 alpha-2.
assetAdvanced.position.streetAddress.isToll	boolean	Indicates that there is a toll for the current road segment.
assetAdvanced.position.streetAddress.number	string	House number.
assetAdvanced.position.streetAddress.postal	string	Postal or zip code.
assetAdvanced.position.streetAddress.province	string fixed length: 2	Province or state code. Codes should be a value from ISO 3166-2.
assetAdvanced.position.streetAddress.region	string	Region name.
assetAdvanced.position.streetAddress.street	string	Full street name.
assetAdvanced.processedUtc	datetime	When the was change procesed.
assetAdvanced.providers	Array.<string> for values see: Provider.id	The list of devices providing events for this asset.
assetAdvanced.relationships	Array.<uint64> for values see: Asset.id	A list of assets related to this one; like a Person for a Vehicle (driver).
assetAdvanced.tags	Array.<codified> for values see: LabelStyle.code	The codified status tag names.
assetAdvanced.updated		by: login, from: monster
assetAdvanced.v	Array.<uint32>	Object version keys used to validate synchronization for all object properties.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"assetAdvanced": {
		"attributes": {
			string: {
				"asset": number,
				"complex": string,
				"dts": string,
				"global": boolean,
				"name": string,
				"provider": string,
				"raw": Object,
				"simple": string,
				"unit": string
			}
		},
		"company": number,
		"id": number,
		"odometer": number,
		"places": {
			string: {
				"enter": string,
				"kind": string,
				"latest": string
			}
		},
		"position": {
			"accuracy": number,
			"address": string,
			"altitude": number,
			"bearing": number,
			"dts": string,
			"lat": number,
			"lng": number,
			"origin": string,
			"speed": number,
			"speedLimit": number,
			"streetAddress": {
				"city": string,
				"country": string,
				"isToll": boolean,
				"number": string,
				"postal": string,
				"province": string,
				"region": string,
				"street": string
			}
		},
		"processedUtc": string,
		"providers": [
			string
		],
		"relationships": [
			number
		],
		"tags": [
			string
		],
		"updated": {
		},
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a asset object, or it is invalid.
400	3	The asset object does not contain an id, or it is invalid.
401	5	You do not have permission to view this Asset.
401	5	You do not have permission to view this Asset's advanced details.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	20	The Asset was not found by its unique identifier.

GET/assets/{assetId}/dispatches?includeDeleted=boolean

Gets details of the specified Asset.

URL Parameters

Parameter	Type	Required	Description
assetId	uint64	required	Unique identifier of the AssetDispatch.
includeDeleted	boolean	optional	False by default, but when true the command will also return deleted objects.

Response description

Property	Type	Description
assetDispatch	AssetDispatch	The requested AssetDispatch.
assetDispatch.company	uint64 see: Company.id	The company to which this asset belongs.
assetDispatch.directions	Array.<DispatchDirection>	Driving directions and route path details.
assetDispatch.id	uint64 see: Asset.id	Unique identifier of this asset.
assetDispatch.jobs	Array.<uint64> see: DispatchJob	The current list of DispatchJobs assigned to the asset.
assetDispatch.lastDispatched	datetime	Timestamp from the last update to this AssetDispatch by a User, Machine, Asset, or an assigned DispatchJob.
assetDispatch.processedUtc	datetime	When the was change procesed.
assetDispatch.tasks Deprecated	Array.<DispatchTask>	The current list of tasks assigned to this asset.
assetDispatch.updated		by: login, from: monster
assetDispatch.v	Array.<uint32>	Object version keys used to validate synchronization for all object properties.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"assetDispatch": {
		"company": number,
		"directions": [
			{
				"directions": [
					{ /* recursive DispatchDirection objects */ }
				],
				"distance": number,
				"duration": string,
				"instructions": string,
				"job": number,
				"path": string,
				"step": number
			}
		],
		"id": number,
		"jobs": [
			number
		],
		"lastDispatched": string,
		"processedUtc": string,
		"tasks": [
			{
				"address": string,
				"arrived": string,
				"asset": number,
				"attachments": [
					number
				],
				"company": number,
				"completed": string,
				"created": string,
				"duration": string,
				"eta": string,
				"id": number,
				"instructions": string,
				"latlng": {
					"lat": number,
					"lng": number
				},
				"name": string,
				"notes": string,
				"place": number,
				"processedUtc": string,
				"reference": string,
				"references": {
					string: string
				},
				"signatory": string,
				"signature": boolean,
				"status": string,
				"updated": {
				},
				"v": [
					number
				]
			}
		],
		"updated": {
		},
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a asset object, or it is invalid.
400	3	The asset object does not contain an id, or it is invalid.
401	5	You do not have permission to view this Asset.
401	5	You do not have permission to view this Asset's dispatch details.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	20	The Asset was not found by its unique identifier.

GET/assets/{assetId}/generals?includeDeleted=boolean

Gets details of the specified Asset.

URL Parameters

Parameter	Type	Required	Description
assetId	uint64	required	Unique identifier of the AssetGeneral.
includeDeleted	boolean	optional	False by default, but when true the command will also return deleted objects.

Response description

Property	Type	Description
assetGeneral	AssetGeneral	The requested Asset.
assetGeneral.company	uint64 see: Company.id	The company to which this asset belongs.
assetGeneral.icon	uint64 see: Icon.id	The icon that represents this asset on the map and in lists.
assetGeneral.id	uint64 see: Asset.id	Unique identifier of this asset.
assetGeneral.kind	AssetType	Type of asset.
assetGeneral.labels	Array.<codified> for values see: LabelStyle.code	Codified label names.
assetGeneral.messagingAddress	string maximum-length: 254	The fall-back address which is used to send Messages if the asset is a Person and has no Contact phone or email.
assetGeneral.name	string maximum-length: 100	This thing's name.
assetGeneral.notes	string	Notes about it.
assetGeneral.pictures	Array.<uint64> for values see: Picture.id	A list of photos of this thing.
assetGeneral.processedUtc	datetime	When the was change procesed.
assetGeneral.reference Deprecated	string maximum-length: 100	A custom field used to refer to an external system. Use asset.references[AssetGeneral.REFERENCE] instead.
assetGeneral.references	Object.<string, string> maximum-count: 10 maximum-length of keys: 20 maximum-length of values: 100	Name/value collections of custom fields used to refer to external systems.
assetGeneral.updated		by: login, from: monster
assetGeneral.v	Array.<uint32>	Object version keys used to validate synchronization for all object properties.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"assetGeneral": {
		"company": number,
		"icon": number,
		"id": number,
		"kind": string,
		"labels": [
			string
		],
		"messagingAddress": string,
		"name": string,
		"notes": string,
		"pictures": [
			number
		],
		"processedUtc": string,
		"reference": string,
		"references": {
			string: string
		},
		"updated": {
		},
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a asset object, or it is invalid.
400	3	The asset object does not contain an id, or it is invalid.
401	5	You do not have permission to view this Asset.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	20	The Asset was not found by its unique identifier.

PATCH/assets/{assetId}/restore

Restores the specified Asset.

URL Parameters

Parameter	Type	Required	Description
assetId	uint64	required	Unique identifier of the Asset.

HTTP Request body description

Property	Type	Required	Description
asset	ParamId	always	An object to contain the "id" of the Asset.
asset.id	uint64	always	Identifier given as input for the command.
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"asset": {
		"id": number
	},
	"reqId": number
}

Response description

Property	Type	Description
asset	RespDeleted	An object which contains the Asset's id, owning Company id, and deleted status.
asset.company	uint64	Identifier of the Company to which this object belongs.
asset.deleted	boolean	Flag showing if the object is deleted.
asset.id	uint64?	Identifier given as input for the command.
asset.v	Array.<uint32>
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"asset": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a asset object, or it is invalid.
400	3	The asset object does not contain an id, or it is invalid.
401	5	You do not have permission to restore this Asset.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	20	The Asset was not found by its unique identifier.
400	21	The Asset was found, but is not marked as deleted.

PATCH/assets/{assetId}/revive

Revives (disables suspension on) an existing Asset.

URL Parameters

Parameter	Type	Required	Description
assetId	uint64	required	Unique identifier of the Asset.

HTTP Request body description

Property	Type	Required	Description
asset	ParamId	always	An object to contain the "id" of the Asset.
asset.id	uint64	always	Identifier given as input for the command.
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"asset": {
		"id": number
	},
	"reqId": number
}

Response description

Property	Type	Description
asset	RespSuspended	An object which contains the Asset's unique identifier and suspended status.
asset.company	uint64	Identifier of the Company to which this object belongs.
asset.id	uint64?	Identifier given as input for the command.
asset.suspended	boolean	Flag showing if the object is suspended.
asset.v	Array.<uint32>
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"asset": {
		"company": number,
		"id": number,
		"suspended": boolean,
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a asset object, or it is invalid.
400	3	The asset object does not contain an id, or it is invalid.
401	5	You do not have permission to revive this Asset.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	20	The Asset was not found by its unique identifier.
403	97	The Asset was found, but is not marked as suspended.

PATCH/assets/{assetId}/suspend

Suspends an existing Asset.

URL Parameters

Parameter	Type	Required	Description
assetId	uint64	required	Unique identifier of the Asset.

HTTP Request body description

Property	Type	Required	Description
asset	ParamId	always	An object to contain the "id" of the Asset.
asset.id	uint64	always	Identifier given as input for the command.
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"asset": {
		"id": number
	},
	"reqId": number
}

Response description

Property	Type	Description
asset	RespSuspended	An object which contains the Asset's unique identifier and suspended status.
asset.company	uint64	Identifier of the Company to which this object belongs.
asset.id	uint64?	Identifier given as input for the command.
asset.suspended	boolean	Flag showing if the object is suspended.
asset.v	Array.<uint32>
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"asset": {
		"company": number,
		"id": number,
		"suspended": boolean,
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a asset object, or it is invalid.
400	3	The asset object does not contain an id, or it is invalid.
401	5	You do not have permission to suspended this Asset.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	20	The Asset was not found by its unique identifier.
403	96	The Asset was not found, but it is already marked as suspended.
403	97	The Asset was previously revived within the minimum period. Returns an ErrorDetailLocked as the `errorDetails`.

GET/assets/advanceds?includeSuspended=boolean&includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

This request is an alias of /companies/{your-company-id}/assets/advanceds (when no additional query-string parameters are given) or /companies/{your-company-id}/assets/advanceds?{keys=values} (when at least one additional query-string key/value is given).

URL Parameters

Parameter	Type	Required	Default	Description
highest	uint64	optional		When using , sets the maximum id when listing from the database.
includeArchive	boolean	optional	`false`	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	`false`	False by default, but when true the command will also return deleted objects.
includeSuspended	boolean	optional	`true`	When true (default), the command will also return Assets marked as Asset.suspended.
limit	uint16	optional		When using , sets the maximum number of objects in this response.
lowest	uint64	optional		When using , sets the minimum id when listing from the database.
your-company-id	uint64	aliased	`{your-company-id}`	Your own Company's identifier.

GET/assets/advanceds?labels={string}&includeSuspended=boolean&includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

This request is an alias of /companies/{your-company-id}/assets/advanceds?labels={labels}.

URL Parameters

Parameter	Type	Required	Default	Description
highest	uint64	optional		When using , sets the maximum id when listing from the database.
includeArchive	boolean	optional	`false`	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	`false`	False by default, but when true the command will also return deleted objects.
includeSuspended	boolean	optional	`true`	When true (default), the command will also return Assets marked as Asset.suspended.
labels	string	optional		Labels to match the DispatchJob.
limit	uint16	optional		When using , sets the maximum number of objects in this response.
lowest	uint64	optional		When using , sets the minimum id when listing from the database.
your-company-id	uint64	aliased	`{your-company-id}`	Your own Company's identifier.

GET/assets/dispatches?includeSuspended=boolean&includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

This request is an alias of /companies/{your-company-id}/assets/dispatches (when no additional query-string parameters are given) or /companies/{your-company-id}/assets/dispatches?{keys=values} (when at least one additional query-string key/value is given).

URL Parameters

Parameter	Type	Required	Default	Description
highest	uint64	optional		When using , sets the maximum id when listing from the database.
includeArchive	boolean	optional	`false`	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	`false`	False by default, but when true the command will also return deleted objects.
includeSuspended	boolean	optional	`true`	When true (default), the command will also return Assets marked as Asset.suspended.
limit	uint16	optional		When using , sets the maximum number of objects in this response.
lowest	uint64	optional		When using , sets the minimum id when listing from the database.
your-company-id	uint64	aliased	`{your-company-id}`	Your own Company's identifier.

GET/assets/dispatches?labels={string}&includeSuspended=boolean&includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

This request is an alias of /companies/{your-company-id}/assets/dispatches?labels={labels}.

URL Parameters

Parameter	Type	Required	Default	Description
highest	uint64	optional		When using , sets the maximum id when listing from the database.
includeArchive	boolean	optional	`false`	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	`false`	False by default, but when true the command will also return deleted objects.
includeSuspended	boolean	optional	`true`	When true (default), the command will also return Assets marked as Asset.suspended.
labels	string	optional		Labels to match the DispatchJob.
limit	uint16	optional		When using , sets the maximum number of objects in this response.
lowest	uint64	optional		When using , sets the minimum id when listing from the database.
your-company-id	uint64	aliased	`{your-company-id}`	Your own Company's identifier.

GET/assets/generals?includeSuspended=boolean&includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

This request is an alias of /companies/{your-company-id}/assets/generals (when no additional query-string parameters are given) or /companies/{your-company-id}/assets/generals?{keys=values} (when at least one additional query-string key/value is given).

URL Parameters

Parameter	Type	Required	Default	Description
highest	uint64	optional		When using , sets the maximum id when listing from the database.
includeArchive	boolean	optional	`false`	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	`false`	False by default, but when true the command will also return deleted objects.
includeSuspended	boolean	optional	`true`	When true (default), the command will also return Assets marked as Asset.suspended.
limit	uint16	optional		When using , sets the maximum number of objects in this response.
lowest	uint64	optional		When using , sets the minimum id when listing from the database.
your-company-id	uint64	aliased	`{your-company-id}`	Your own Company's identifier.

GET/assets/generals?labels={string}&includeSuspended=boolean&includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

This request is an alias of /companies/{your-company-id}/assets/generals?labels={labels}.

URL Parameters

Parameter	Type	Required	Default	Description
highest	uint64	optional		When using , sets the maximum id when listing from the database.
includeArchive	boolean	optional	`false`	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	`false`	False by default, but when true the command will also return deleted objects.
includeSuspended	boolean	optional	`true`	When true (default), the command will also return Assets marked as Asset.suspended.
labels	string	optional		Labels to match the DispatchJob.
limit	uint16	optional		When using , sets the maximum number of objects in this response.
lowest	uint64	optional		When using , sets the minimum id when listing from the database.
your-company-id	uint64	aliased	`{your-company-id}`	Your own Company's identifier.

PATCH/assets/revive

Revives (disables suspension on) an existing Asset.

HTTP Request body description

Property	Type	Required	Description
asset	ParamId	always	An object to contain the "id" of the Asset.
asset.id	uint64	always	Identifier given as input for the command.
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"asset": {
		"id": number
	},
	"reqId": number
}

Response description

Property	Type	Description
asset	RespSuspended	An object which contains the Asset's unique identifier and suspended status.
asset.company	uint64	Identifier of the Company to which this object belongs.
asset.id	uint64?	Identifier given as input for the command.
asset.suspended	boolean	Flag showing if the object is suspended.
asset.v	Array.<uint32>
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"asset": {
		"company": number,
		"id": number,
		"suspended": boolean,
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a asset object, or it is invalid.
400	3	The asset object does not contain an id, or it is invalid.
401	5	You do not have permission to revive this Asset.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	20	The Asset was not found by its unique identifier.
403	97	The Asset was found, but is not marked as suspended.

PATCH/assets/suspend

Suspends an existing Asset.

HTTP Request body description

Property	Type	Required	Description
asset	ParamId	always	An object to contain the "id" of the Asset.
asset.id	uint64	always	Identifier given as input for the command.
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"asset": {
		"id": number
	},
	"reqId": number
}

Response description

Property	Type	Description
asset	RespSuspended	An object which contains the Asset's unique identifier and suspended status.
asset.company	uint64	Identifier of the Company to which this object belongs.
asset.id	uint64?	Identifier given as input for the command.
asset.suspended	boolean	Flag showing if the object is suspended.
asset.v	Array.<uint32>
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"asset": {
		"company": number,
		"id": number,
		"suspended": boolean,
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a asset object, or it is invalid.
400	3	The asset object does not contain an id, or it is invalid.
401	5	You do not have permission to suspended this Asset.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	20	The Asset was not found by its unique identifier.
403	96	The Asset was not found, but it is already marked as suspended.
403	97	The Asset was previously revived within the minimum period. Returns an ErrorDetailLocked as the `errorDetails`.

GET/assets?labels={string}&includeSuspended=boolean&includeMessages=boolean&includeTasks=boolean&includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

This request is an alias of /companies/{your-company-id}/assets?labels={labels}.

URL Parameters

Parameter	Type	Required	Default	Description
highest	uint64	optional		When using , sets the maximum id when listing from the database.
includeArchive	boolean	optional	`false`	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	`false`	False by default, but when true the command will also return deleted objects.
includeMessages	boolean	optional	`false`	False by default, but when true will include Asset.messages..
includeSuspended	boolean	optional	`true`	When true (default), the command will also return Assets marked as Asset.suspended.
includeTasks	boolean	optional	`false`	False by default, but when true will include Asset.tasks..
labels	string	optional		Labels to match the DispatchJob.
limit	uint16	optional		When using , sets the maximum number of objects in this response.
lowest	uint64	optional		When using , sets the minimum id when listing from the database.
your-company-id	uint64	aliased	`{your-company-id}`	Your own Company's identifier.

GET/companies/{companyId}/assets?includeSuspended=boolean&includeMessages=boolean&includeTasks=boolean&includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

Gets the list of Assets for the specified Company.

URL Parameters

Parameter	Type	Required	Default	Description
companyId	uint64	required		Unique identifier of the Company.
highest	uint64?	optional		When using , sets the largest valued id objects to retrieve.
includeArchive	boolean	optional		Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional		False by default, but when true, the command will also return deleted objects.
includeMessages	boolean	optional	`false`	False by default, but when true, the command will also return AssetMessages for the asset.
includeSuspended	boolean	optional	`true`	When true (default), the command will also return Assets marked as Asset.suspended.
includeTasks	boolean	optional	`false`	False by default, but when true, the command will also return the DispatchTasks for the asset.
limit	uint16?	optional		When using , sets the maximum number of objects retrieved from the archive.
lowest	uint64?	optional		When using , sets the smallest valued id objects to retrieve.

Response description

Property	Type	Description
assets	Array.<Asset>	The list of requested Assets.
company	RespId	An object to contain the "id" of the Company to which the array of Assets belong.
company.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"assets": [
		{
			"attributes": {
				string: {
					"asset": number,
					"complex": string,
					"dts": string,
					"global": boolean,
					"name": string,
					"provider": string,
					"raw": Object,
					"simple": string,
					"unit": string
				}
			},
			"company": number,
			"dispatch": {
				"company": number,
				"directions": [
					{
						"directions": [
							{ /* recursive DispatchDirection objects */ }
						],
						"distance": number,
						"duration": string,
						"instructions": string,
						"job": number,
						"path": string,
						"step": number
					}
				],
				"id": number,
				"jobs": [
					number
				],
				"lastDispatched": string,
				"processedUtc": string,
				"tasks": [
					{
						"address": string,
						"arrived": string,
						"asset": number,
						"attachments": [
							number
						],
						"company": number,
						"completed": string,
						"created": string,
						"duration": string,
						"eta": string,
						"id": number,
						"instructions": string,
						"latlng": {
							"lat": number,
							"lng": number
						},
						"name": string,
						"notes": string,
						"place": number,
						"processedUtc": string,
						"reference": string,
						"references": {
							string: string
						},
						"signatory": string,
						"signature": boolean,
						"status": string,
						"updated": {
						},
						"v": [
							number
						]
					}
				],
				"updated": {
				},
				"v": [
					number
				]
			},
			"icon": number,
			"id": number,
			"kind": string,
			"labels": [
				string
			],
			"messages": [
				{
					"asset": number,
					"body": string,
					"company": number,
					"delivered": string,
					"folder": string,
					"from": string,
					"id": number,
					"incoming": boolean,
					"kind": string,
					"processed": string,
					"processedUtc": string,
					"readBy": string,
					"status": string,
					"subject": string,
					"to": string,
					"updated": {
					},
					"user": string,
					"v": [
						number
					]
				}
			],
			"messagingAddress": string,
			"name": string,
			"notes": string,
			"odometer": number,
			"pictures": [
				number
			],
			"places": {
				string: {
					"enter": string,
					"kind": string,
					"latest": string
				}
			},
			"position": {
				"accuracy": number,
				"address": string,
				"altitude": number,
				"bearing": number,
				"dts": string,
				"lat": number,
				"lng": number,
				"origin": string,
				"speed": number,
				"speedLimit": number,
				"streetAddress": {
					"city": string,
					"country": string,
					"isToll": boolean,
					"number": string,
					"postal": string,
					"province": string,
					"region": string,
					"street": string
				}
			},
			"processedUtc": string,
			"providers": [
				string
			],
			"reference": string,
			"references": {
				string: string
			},
			"relationships": [
				number
			],
			"tags": [
				string
			],
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
401	5	You do not have permission to view any Assets for this Company.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company was not found by its unique identifier.

GET/companies/{companyId}/assets?{keys=values}?includeSuspended=boolean&includeMessages=boolean&includeTasks=boolean&includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number&{keys=values}

Gets the list of Assets for the specified Company only if one of the specified Asset.references fields match. If no references are specified, it will match any Asset with no references. If a reference value is null, it will match any Asset without that reference key.

URL Parameters

Parameter	Type	Required	Default	Description
companyId	uint64	required		Unique identifier of the Company.
highest	uint64?	optional		When using , sets the largest valued id objects to retrieve.
includeArchive	boolean	optional		Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional		False by default, but when true, the command will also return deleted objects.
includeMessages	boolean	optional	`false`	False by default, but when true, the command will also return AssetMessages for the asset.
includeSuspended	boolean	optional	`true`	When true (default), the command will also return Assets marked as Asset.suspended.
includeTasks	boolean	optional	`false`	False by default, but when true, the command will also return the DispatchTasks for the asset.
limit	uint16?	optional		When using , sets the maximum number of objects retrieved from the archive.
lowest	uint64?	optional		When using , sets the smallest valued id objects to retrieve.

Response description

Property	Type	Description
assets	Array.<Asset>	The list of requested Assets.
company	RespId	An object to contain the "id" of the Company to which the array of Assets belong.
company.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
references	Object.<string, string>	The reference string given as input.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"assets": [
		{
			"attributes": {
				string: {
					"asset": number,
					"complex": string,
					"dts": string,
					"global": boolean,
					"name": string,
					"provider": string,
					"raw": Object,
					"simple": string,
					"unit": string
				}
			},
			"company": number,
			"dispatch": {
				"company": number,
				"directions": [
					{
						"directions": [
							{ /* recursive DispatchDirection objects */ }
						],
						"distance": number,
						"duration": string,
						"instructions": string,
						"job": number,
						"path": string,
						"step": number
					}
				],
				"id": number,
				"jobs": [
					number
				],
				"lastDispatched": string,
				"processedUtc": string,
				"tasks": [
					{
						"address": string,
						"arrived": string,
						"asset": number,
						"attachments": [
							number
						],
						"company": number,
						"completed": string,
						"created": string,
						"duration": string,
						"eta": string,
						"id": number,
						"instructions": string,
						"latlng": {
							"lat": number,
							"lng": number
						},
						"name": string,
						"notes": string,
						"place": number,
						"processedUtc": string,
						"reference": string,
						"references": {
							string: string
						},
						"signatory": string,
						"signature": boolean,
						"status": string,
						"updated": {
						},
						"v": [
							number
						]
					}
				],
				"updated": {
				},
				"v": [
					number
				]
			},
			"icon": number,
			"id": number,
			"kind": string,
			"labels": [
				string
			],
			"messages": [
				{
					"asset": number,
					"body": string,
					"company": number,
					"delivered": string,
					"folder": string,
					"from": string,
					"id": number,
					"incoming": boolean,
					"kind": string,
					"processed": string,
					"processedUtc": string,
					"readBy": string,
					"status": string,
					"subject": string,
					"to": string,
					"updated": {
					},
					"user": string,
					"v": [
						number
					]
				}
			],
			"messagingAddress": string,
			"name": string,
			"notes": string,
			"odometer": number,
			"pictures": [
				number
			],
			"places": {
				string: {
					"enter": string,
					"kind": string,
					"latest": string
				}
			},
			"position": {
				"accuracy": number,
				"address": string,
				"altitude": number,
				"bearing": number,
				"dts": string,
				"lat": number,
				"lng": number,
				"origin": string,
				"speed": number,
				"speedLimit": number,
				"streetAddress": {
					"city": string,
					"country": string,
					"isToll": boolean,
					"number": string,
					"postal": string,
					"province": string,
					"region": string,
					"street": string
				}
			},
			"processedUtc": string,
			"providers": [
				string
			],
			"reference": string,
			"references": {
				string: string
			},
			"relationships": [
				number
			],
			"tags": [
				string
			],
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"references": {
		string: string
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
400	3	The references is not an object, or it is invalid.
401	5	You do not have permission to view any Assets for this Company.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company was not found by its unique identifier.

GET/companies/{companyId}/assets/advanceds?includeSuspended=boolean&includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

Gets the list of Assets for the specified Company.

URL Parameters

Parameter	Type	Required	Default	Description
companyId	uint64	required		Unique identifier of the Company.
highest	uint64?	optional		When using , sets the largest valued id objects to retrieve.
includeArchive	boolean	optional		Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional		False by default, but when true the command will also return deleted objects.
includeSuspended	boolean	optional	`true`	When true (default), the command will also return Assets marked as Asset.suspended.
limit	uint16?	optional		When using , sets the maximum number of objects retrieved from the archive.
lowest	uint64?	optional		When using , sets the smallest valued id objects to retrieve.

Response description

Property	Type	Description
assetAdvanceds	Array.<AssetAdvanced>	The list of requested Assets.
company	RespId	An object to contain the "id" of the Company to which the array of Assets belong.
company.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"assetAdvanceds": [
		{
			"attributes": {
				string: {
					"asset": number,
					"complex": string,
					"dts": string,
					"global": boolean,
					"name": string,
					"provider": string,
					"raw": Object,
					"simple": string,
					"unit": string
				}
			},
			"company": number,
			"id": number,
			"odometer": number,
			"places": {
				string: {
					"enter": string,
					"kind": string,
					"latest": string
				}
			},
			"position": {
				"accuracy": number,
				"address": string,
				"altitude": number,
				"bearing": number,
				"dts": string,
				"lat": number,
				"lng": number,
				"origin": string,
				"speed": number,
				"speedLimit": number,
				"streetAddress": {
					"city": string,
					"country": string,
					"isToll": boolean,
					"number": string,
					"postal": string,
					"province": string,
					"region": string,
					"street": string
				}
			},
			"processedUtc": string,
			"providers": [
				string
			],
			"relationships": [
				number
			],
			"tags": [
				string
			],
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
401	5	You do not have permission to view any Assets for this Company.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company was not found by its unique identifier.

GET/companies/{companyId}/assets/advanceds?{keys=values}?includeSuspended=boolean&includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number&{keys=values}

URL Parameters

Parameter	Type	Required	Default	Description
companyId	uint64	required		Unique identifier of the Company.
highest	uint64?	optional		When using , sets the largest valued id objects to retrieve.
includeArchive	boolean	optional		Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional		False by default, but when true the command will also return deleted objects.
includeSuspended	boolean	optional	`true`	When true (default), the command will also return Assets marked as Asset.suspended.
limit	uint16?	optional		When using , sets the maximum number of objects retrieved from the archive.
lowest	uint64?	optional		When using , sets the smallest valued id objects to retrieve.

Response description

Property	Type	Description
assetAdvanceds	Array.<AssetAdvanced>	The list of requested Assets.
company	RespId	An object to contain the "id" of the Company to which the array of Assets belong.
company.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
references	Object.<string, string>	The reference string given as input.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"assetAdvanceds": [
		{
			"attributes": {
				string: {
					"asset": number,
					"complex": string,
					"dts": string,
					"global": boolean,
					"name": string,
					"provider": string,
					"raw": Object,
					"simple": string,
					"unit": string
				}
			},
			"company": number,
			"id": number,
			"odometer": number,
			"places": {
				string: {
					"enter": string,
					"kind": string,
					"latest": string
				}
			},
			"position": {
				"accuracy": number,
				"address": string,
				"altitude": number,
				"bearing": number,
				"dts": string,
				"lat": number,
				"lng": number,
				"origin": string,
				"speed": number,
				"speedLimit": number,
				"streetAddress": {
					"city": string,
					"country": string,
					"isToll": boolean,
					"number": string,
					"postal": string,
					"province": string,
					"region": string,
					"street": string
				}
			},
			"processedUtc": string,
			"providers": [
				string
			],
			"relationships": [
				number
			],
			"tags": [
				string
			],
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"references": {
		string: string
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
400	3	The references is not an object, or it is invalid.
401	5	You do not have permission to view any Assets for this Company.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company was not found by its unique identifier.

GET/companies/{companyId}/assets/advanceds?labels={string}&includeSuspended=boolean&includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

Gets the list of Assets for the specified Company only if the Asset.labels matches all of the given labels.

URL Parameters

Parameter	Type	Required	Default	Description
companyId	uint64	required		Unique identifier of the Company.
highest	uint64?	optional		When using , sets the largest valued id objects to retrieve.
includeArchive	boolean	optional		Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional		False by default, but when true the command will also return deleted objects.
includeSuspended	boolean	optional	`true`	When true (default), the command will also return Assets marked as Asset.suspended.
labels	string	required		Labels to match the DispatchJob.
limit	uint16?	optional		When using , sets the maximum number of objects retrieved from the archive.
lowest	uint64?	optional		When using , sets the smallest valued id objects to retrieve.

Response description

Property	Type	Description
assetAdvanceds	Array.<AssetAdvanced>	The list of requested Assets.
company	RespId	An object to contain the "id" of the Company to which the array of Assets belong.
company.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
labels	Array.<string>	The labels given as input.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"assetAdvanceds": [
		{
			"attributes": {
				string: {
					"asset": number,
					"complex": string,
					"dts": string,
					"global": boolean,
					"name": string,
					"provider": string,
					"raw": Object,
					"simple": string,
					"unit": string
				}
			},
			"company": number,
			"id": number,
			"odometer": number,
			"places": {
				string: {
					"enter": string,
					"kind": string,
					"latest": string
				}
			},
			"position": {
				"accuracy": number,
				"address": string,
				"altitude": number,
				"bearing": number,
				"dts": string,
				"lat": number,
				"lng": number,
				"origin": string,
				"speed": number,
				"speedLimit": number,
				"streetAddress": {
					"city": string,
					"country": string,
					"isToll": boolean,
					"number": string,
					"postal": string,
					"province": string,
					"region": string,
					"street": string
				}
			},
			"processedUtc": string,
			"providers": [
				string
			],
			"relationships": [
				number
			],
			"tags": [
				string
			],
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"labels": [
		string
	],
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
400	3	The labels is not an array.
401	5	You do not have permission to view any Assets for this Company.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company was not found by its unique identifier.

GET/companies/{companyId}/assets/dispatches?includeSuspended=boolean&includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

Gets the list of Assets for the specified Company.

URL Parameters

Parameter	Type	Required	Default	Description
companyId	uint64	required		Unique identifier of the Company.
highest	uint64?	optional		When using , sets the largest valued id objects to retrieve.
includeArchive	boolean	optional		Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional		False by default, but when true the command will also return deleted objects.
includeSuspended	boolean	optional	`true`	When true (default), the command will also return Assets marked as Asset.suspended.
limit	uint16?	optional		When using , sets the maximum number of objects retrieved from the archive.
lowest	uint64?	optional		When using , sets the smallest valued id objects to retrieve.

Response description

Property	Type	Description
assetDispatches	Array.<AssetDispatch>	The list of requested Assets.
company	RespId	An object to contain the "id" of the Company to which the array of Assets belong.
company.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"assetDispatches": [
		{
			"company": number,
			"directions": [
				{
					"directions": [
						{ /* recursive DispatchDirection objects */ }
					],
					"distance": number,
					"duration": string,
					"instructions": string,
					"job": number,
					"path": string,
					"step": number
				}
			],
			"id": number,
			"jobs": [
				number
			],
			"lastDispatched": string,
			"processedUtc": string,
			"tasks": [
				{
					"address": string,
					"arrived": string,
					"asset": number,
					"attachments": [
						number
					],
					"company": number,
					"completed": string,
					"created": string,
					"duration": string,
					"eta": string,
					"id": number,
					"instructions": string,
					"latlng": {
						"lat": number,
						"lng": number
					},
					"name": string,
					"notes": string,
					"place": number,
					"processedUtc": string,
					"reference": string,
					"references": {
						string: string
					},
					"signatory": string,
					"signature": boolean,
					"status": string,
					"updated": {
					},
					"v": [
						number
					]
				}
			],
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
401	5	You do not have permission to view any Assets for this Company.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company was not found by its unique identifier.

GET/companies/{companyId}/assets/dispatches?{keys=values}?includeSuspended=boolean&includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number&{keys=values}

URL Parameters

Parameter	Type	Required	Default	Description
companyId	uint64	required		Unique identifier of the Company.
highest	uint64?	optional		When using , sets the largest valued id objects to retrieve.
includeArchive	boolean	optional		Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional		False by default, but when true the command will also return deleted objects.
includeSuspended	boolean	optional	`true`	When true (default), the command will also return Assets marked as Asset.suspended.
limit	uint16?	optional		When using , sets the maximum number of objects retrieved from the archive.
lowest	uint64?	optional		When using , sets the smallest valued id objects to retrieve.

Response description

Property	Type	Description
assetDispatches	Array.<AssetDispatch>	The list of requested Assets.
company	RespId	An object to contain the "id" of the Company to which the array of Assets belong.
company.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
references	Object.<string, string>	The reference string given as input.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"assetDispatches": [
		{
			"company": number,
			"directions": [
				{
					"directions": [
						{ /* recursive DispatchDirection objects */ }
					],
					"distance": number,
					"duration": string,
					"instructions": string,
					"job": number,
					"path": string,
					"step": number
				}
			],
			"id": number,
			"jobs": [
				number
			],
			"lastDispatched": string,
			"processedUtc": string,
			"tasks": [
				{
					"address": string,
					"arrived": string,
					"asset": number,
					"attachments": [
						number
					],
					"company": number,
					"completed": string,
					"created": string,
					"duration": string,
					"eta": string,
					"id": number,
					"instructions": string,
					"latlng": {
						"lat": number,
						"lng": number
					},
					"name": string,
					"notes": string,
					"place": number,
					"processedUtc": string,
					"reference": string,
					"references": {
						string: string
					},
					"signatory": string,
					"signature": boolean,
					"status": string,
					"updated": {
					},
					"v": [
						number
					]
				}
			],
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"references": {
		string: string
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
400	3	The references is not an object, or it is invalid.
401	5	You do not have permission to view any Assets for this Company.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company was not found by its unique identifier.

GET/companies/{companyId}/assets/dispatches?labels={string}&includeSuspended=boolean&includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

Gets the list of Assets for the specified Company only if the Asset.labels matches all of the given labels.

URL Parameters

Parameter	Type	Required	Default	Description
companyId	uint64	required		Unique identifier of the Company.
highest	uint64?	optional		When using , sets the largest valued id objects to retrieve.
includeArchive	boolean	optional		Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional		False by default, but when true the command will also return deleted objects.
includeSuspended	boolean	optional	`true`	When true (default), the command will also return Assets marked as Asset.suspended.
labels	string	required		Labels to match the DispatchJob.
limit	uint16?	optional		When using , sets the maximum number of objects retrieved from the archive.
lowest	uint64?	optional		When using , sets the smallest valued id objects to retrieve.

Response description

Property	Type	Description
assetDispatches	Array.<AssetDispatch>	The list of requested Assets.
company	RespId	An object to contain the "id" of the Company to which the array of Assets belong.
company.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
labels	Array.<string>	The labels given as input.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"assetDispatches": [
		{
			"company": number,
			"directions": [
				{
					"directions": [
						{ /* recursive DispatchDirection objects */ }
					],
					"distance": number,
					"duration": string,
					"instructions": string,
					"job": number,
					"path": string,
					"step": number
				}
			],
			"id": number,
			"jobs": [
				number
			],
			"lastDispatched": string,
			"processedUtc": string,
			"tasks": [
				{
					"address": string,
					"arrived": string,
					"asset": number,
					"attachments": [
						number
					],
					"company": number,
					"completed": string,
					"created": string,
					"duration": string,
					"eta": string,
					"id": number,
					"instructions": string,
					"latlng": {
						"lat": number,
						"lng": number
					},
					"name": string,
					"notes": string,
					"place": number,
					"processedUtc": string,
					"reference": string,
					"references": {
						string: string
					},
					"signatory": string,
					"signature": boolean,
					"status": string,
					"updated": {
					},
					"v": [
						number
					]
				}
			],
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"labels": [
		string
	],
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
400	3	The labels is not an array.
401	5	You do not have permission to view any Assets for this Company.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company was not found by its unique identifier.

GET/companies/{companyId}/assets/generals?includeSuspended=boolean&includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

Gets the list of Assets for the specified Company.

URL Parameters

Parameter	Type	Required	Default	Description
companyId	uint64	required		Unique identifier of the Company.
highest	uint64?	optional		When using , sets the largest valued id objects to retrieve.
includeArchive	boolean	optional		Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional		False by default, but when true the command will also return deleted objects.
includeSuspended	boolean	optional	`true`	When true (default), the command will also return Assets marked as Asset.suspended.
limit	uint16?	optional		When using , sets the maximum number of objects retrieved from the archive.
lowest	uint64?	optional		When using , sets the smallest valued id objects to retrieve.

Response description

Property	Type	Description
assetGenerals	Array.<AssetGeneral>	The list of requested Assets.
company	RespId	An object to contain the "id" of the Company to which the array of Assets belong.
company.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"assetGenerals": [
		{
			"company": number,
			"icon": number,
			"id": number,
			"kind": string,
			"labels": [
				string
			],
			"messagingAddress": string,
			"name": string,
			"notes": string,
			"pictures": [
				number
			],
			"processedUtc": string,
			"reference": string,
			"references": {
				string: string
			},
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
401	5	You do not have permission to view any Assets for this Company.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company was not found by its unique identifier.

GET/companies/{companyId}/assets/generals?{keys=values}?includeSuspended=boolean&includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number&{keys=values}

URL Parameters

Parameter	Type	Required	Default	Description
companyId	uint64	required		Unique identifier of the Company.
highest	uint64?	optional		When using , sets the largest valued id objects to retrieve.
includeArchive	boolean	optional		Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional		False by default, but when true the command will also return deleted objects.
includeSuspended	boolean	optional	`true`	When true (default), the command will also return Assets marked as Asset.suspended.
limit	uint16?	optional		When using , sets the maximum number of objects retrieved from the archive.
lowest	uint64?	optional		When using , sets the smallest valued id objects to retrieve.

Response description

Property	Type	Description
assetGenerals	Array.<AssetGeneral>	The list of requested Assets.
company	RespId	An object to contain the "id" of the Company to which the array of Assets belong.
company.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
references	Object.<string, string>	The reference string given as input.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"assetGenerals": [
		{
			"company": number,
			"icon": number,
			"id": number,
			"kind": string,
			"labels": [
				string
			],
			"messagingAddress": string,
			"name": string,
			"notes": string,
			"pictures": [
				number
			],
			"processedUtc": string,
			"reference": string,
			"references": {
				string: string
			},
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"references": {
		string: string
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
400	3	The references is not an object, or it is invalid.
401	5	You do not have permission to view any Assets for this Company.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company was not found by its unique identifier.

GET/companies/{companyId}/assets/generals?labels={string}&includeSuspended=boolean&includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

Gets the list of Assets for the specified Company only if the Asset.labels matches all of the given labels.

URL Parameters

Parameter	Type	Required	Default	Description
companyId	uint64	required		Unique identifier of the Company.
highest	uint64?	optional		When using , sets the largest valued id objects to retrieve.
includeArchive	boolean	optional		Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional		False by default, but when true the command will also return deleted objects.
includeSuspended	boolean	optional	`true`	When true (default), the command will also return Assets marked as Asset.suspended.
labels	string	required		Labels to match the DispatchJob.
limit	uint16?	optional		When using , sets the maximum number of objects retrieved from the archive.
lowest	uint64?	optional		When using , sets the smallest valued id objects to retrieve.

Response description

Property	Type	Description
assetGenerals	Array.<AssetGeneral>	The list of requested Assets.
company	RespId	An object to contain the "id" of the Company to which the array of Assets belong.
company.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
labels	Array.<string>	The labels given as input.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"assetGenerals": [
		{
			"company": number,
			"icon": number,
			"id": number,
			"kind": string,
			"labels": [
				string
			],
			"messagingAddress": string,
			"name": string,
			"notes": string,
			"pictures": [
				number
			],
			"processedUtc": string,
			"reference": string,
			"references": {
				string: string
			},
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"labels": [
		string
	],
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
400	3	The labels is not an array.
401	5	You do not have permission to view any Assets for this Company.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company was not found by its unique identifier.

GET/companies/{companyId}/assets?labels={string}&includeSuspended=boolean&includeMessages=boolean&includeTasks=boolean&includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

Gets the list of Assets for the specified Company only if the Asset.labels matches all of the given labels.

URL Parameters

Parameter	Type	Required	Default	Description
companyId	uint64	required		Unique identifier of the Company.
highest	uint64?	optional		When using , sets the largest valued id objects to retrieve.
includeArchive	boolean	optional		Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional		False by default, but when true the command will also return deleted objects.
includeMessages	boolean	optional	`false`	False by default, but when true the command will also return AssetMessages for the asset.
includeSuspended	boolean	optional	`true`	When true (default), the command will also return Assets marked as Asset.suspended.
includeTasks	boolean	optional	`false`	False by default, but when true the command will also return the DispatchTasks for the asset.
labels	string	required		Labels to match the DispatchJob.
limit	uint16?	optional		When using , sets the maximum number of objects retrieved from the archive.
lowest	uint64?	optional		When using , sets the smallest valued id objects to retrieve.

Response description

Property	Type	Description
assets	Array.<Asset>	The list of requested Assets.
company	RespId	An object to contain the "id" of the Company to which the array of Assets belong.
company.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
labels	Array.<string>	The labels given as input.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"assets": [
		{
			"attributes": {
				string: {
					"asset": number,
					"complex": string,
					"dts": string,
					"global": boolean,
					"name": string,
					"provider": string,
					"raw": Object,
					"simple": string,
					"unit": string
				}
			},
			"company": number,
			"dispatch": {
				"company": number,
				"directions": [
					{
						"directions": [
							{ /* recursive DispatchDirection objects */ }
						],
						"distance": number,
						"duration": string,
						"instructions": string,
						"job": number,
						"path": string,
						"step": number
					}
				],
				"id": number,
				"jobs": [
					number
				],
				"lastDispatched": string,
				"processedUtc": string,
				"tasks": [
					{
						"address": string,
						"arrived": string,
						"asset": number,
						"attachments": [
							number
						],
						"company": number,
						"completed": string,
						"created": string,
						"duration": string,
						"eta": string,
						"id": number,
						"instructions": string,
						"latlng": {
							"lat": number,
							"lng": number
						},
						"name": string,
						"notes": string,
						"place": number,
						"processedUtc": string,
						"reference": string,
						"references": {
							string: string
						},
						"signatory": string,
						"signature": boolean,
						"status": string,
						"updated": {
						},
						"v": [
							number
						]
					}
				],
				"updated": {
				},
				"v": [
					number
				]
			},
			"icon": number,
			"id": number,
			"kind": string,
			"labels": [
				string
			],
			"messages": [
				{
					"asset": number,
					"body": string,
					"company": number,
					"delivered": string,
					"folder": string,
					"from": string,
					"id": number,
					"incoming": boolean,
					"kind": string,
					"processed": string,
					"processedUtc": string,
					"readBy": string,
					"status": string,
					"subject": string,
					"to": string,
					"updated": {
					},
					"user": string,
					"v": [
						number
					]
				}
			],
			"messagingAddress": string,
			"name": string,
			"notes": string,
			"odometer": number,
			"pictures": [
				number
			],
			"places": {
				string: {
					"enter": string,
					"kind": string,
					"latest": string
				}
			},
			"position": {
				"accuracy": number,
				"address": string,
				"altitude": number,
				"bearing": number,
				"dts": string,
				"lat": number,
				"lng": number,
				"origin": string,
				"speed": number,
				"speedLimit": number,
				"streetAddress": {
					"city": string,
					"country": string,
					"isToll": boolean,
					"number": string,
					"postal": string,
					"province": string,
					"region": string,
					"street": string
				}
			},
			"processedUtc": string,
			"providers": [
				string
			],
			"reference": string,
			"references": {
				string: string
			},
			"relationships": [
				number
			],
			"tags": [
				string
			],
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"labels": [
		string
	],
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
400	3	The labels is not an array.
401	5	You do not have permission to view any Assets for this Company.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company was not found by its unique identifier.

GET/companies/{companyId}/assets?reference={string}&includeSuspended=boolean&includeMessages=boolean&includeTasks=boolean&includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

URL Parameters

Parameter	Type	Required	Default	Description
companyId	uint64	required		Unique identifier of the Company.
highest	uint64?	optional		When using , sets the largest valued id objects to retrieve.
includeArchive	boolean	optional		Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional		False by default, but when true the command will also return deleted objects.
includeMessages	boolean	optional	`false`	False by default, but when true the command will also return AssetMessages for the asset.
includeSuspended	boolean	optional	`true`	When true (default), the command will also return Assets marked as Asset.suspended.
includeTasks	boolean	optional	`false`	False by default, but when true the command will also return the DispatchTasks for the asset.
limit	uint16?	optional		When using , sets the maximum number of objects retrieved from the archive.
lowest	uint64?	optional		When using , sets the smallest valued id objects to retrieve.
reference	string	required		Value to search in the asset.reference["Reference"] field

Response description

Property	Type	Description
assets	Array.<Asset>	The list of requested Assets.
company	RespId	An object to contain the "id" of the Company to which the array of Assets belong.
company.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
references	Object.<string, string>	The reference string given as input.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"assets": [
		{
			"attributes": {
				string: {
					"asset": number,
					"complex": string,
					"dts": string,
					"global": boolean,
					"name": string,
					"provider": string,
					"raw": Object,
					"simple": string,
					"unit": string
				}
			},
			"company": number,
			"dispatch": {
				"company": number,
				"directions": [
					{
						"directions": [
							{ /* recursive DispatchDirection objects */ }
						],
						"distance": number,
						"duration": string,
						"instructions": string,
						"job": number,
						"path": string,
						"step": number
					}
				],
				"id": number,
				"jobs": [
					number
				],
				"lastDispatched": string,
				"processedUtc": string,
				"tasks": [
					{
						"address": string,
						"arrived": string,
						"asset": number,
						"attachments": [
							number
						],
						"company": number,
						"completed": string,
						"created": string,
						"duration": string,
						"eta": string,
						"id": number,
						"instructions": string,
						"latlng": {
							"lat": number,
							"lng": number
						},
						"name": string,
						"notes": string,
						"place": number,
						"processedUtc": string,
						"reference": string,
						"references": {
							string: string
						},
						"signatory": string,
						"signature": boolean,
						"status": string,
						"updated": {
						},
						"v": [
							number
						]
					}
				],
				"updated": {
				},
				"v": [
					number
				]
			},
			"icon": number,
			"id": number,
			"kind": string,
			"labels": [
				string
			],
			"messages": [
				{
					"asset": number,
					"body": string,
					"company": number,
					"delivered": string,
					"folder": string,
					"from": string,
					"id": number,
					"incoming": boolean,
					"kind": string,
					"processed": string,
					"processedUtc": string,
					"readBy": string,
					"status": string,
					"subject": string,
					"to": string,
					"updated": {
					},
					"user": string,
					"v": [
						number
					]
				}
			],
			"messagingAddress": string,
			"name": string,
			"notes": string,
			"odometer": number,
			"pictures": [
				number
			],
			"places": {
				string: {
					"enter": string,
					"kind": string,
					"latest": string
				}
			},
			"position": {
				"accuracy": number,
				"address": string,
				"altitude": number,
				"bearing": number,
				"dts": string,
				"lat": number,
				"lng": number,
				"origin": string,
				"speed": number,
				"speedLimit": number,
				"streetAddress": {
					"city": string,
					"country": string,
					"isToll": boolean,
					"number": string,
					"postal": string,
					"province": string,
					"region": string,
					"street": string
				}
			},
			"processedUtc": string,
			"providers": [
				string
			],
			"reference": string,
			"references": {
				string: string
			},
			"relationships": [
				number
			],
			"tags": [
				string
			],
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"references": {
		string: string
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
400	3	The references is not an object, or it is invalid.
401	5	You do not have permission to view any Assets for this Company.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company was not found by its unique identifier.

Behaviours

GET/behaviours?includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

This request is an alias of /companies/{your-company-id}/behaviours/.

URL Parameters

Parameter	Type	Required	Default	Description
highest	uint64	optional		When using , sets the maximum id when listing from the database.
includeArchive	boolean	optional	`false`	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	`false`	False by default, but when true the command will also return deleted objects.
limit	uint16	optional		When using , sets the maximum number of objects in this response.
lowest	uint64	optional		When using , sets the minimum id when listing from the database.
your-company-id	uint64	aliased	`{your-company-id}`	Your own Company's identifier.

PATCH/behaviours

Creates a new or updates an existing Behaviour.

HTTP Request body description

Property	Type	Required	Description
behaviour	Object.<string, ?>	always	A simple object to contain the Behaviour parameters.
behaviour.company	uint64?	create
behaviour.filters	expression	optional	A search pattern used to select the assets which will embed this Behaviour in their execution context.
behaviour.id	uint64?	update	The unique identifier of the Behaviour you want to update.
behaviour.name	string maximum-length: 100	create	Name for the Behaviour.
behaviour.notes	string	optional	Notes for the Behaviour.
behaviour.parameters	Object.<string, BehaviourParameter>	optional	The values needed to implement the script. Each key in this object is the name of a required script argument.
behaviour.priority	byte?	optional	The order in which this Behaviour is executed.
behaviour.script	uint64?	create	Identifier of the BehaviourScript to which this Behaviour belongs. After creation, this value is read-only.
behaviour.targets	expression	optional	A search pattern used to select the providers which can implement this Behaviour.
behaviour.v	Array.<int32>	optional
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"behaviour": {
		"company": number,
		"filters": string,
		"id": number,
		"name": string,
		"notes": string,
		"parameters": {
			string: {
				"context": string,
				"notes": string,
				"type": string,
				"value": string
			}
		},
		"priority": number,
		"script": number,
		"targets": string,
		"v": [
			number
		]
	},
	"reqId": number
}

Response description

Property	Type	Description
behaviour	RespIdScript	An object which contains the "id", "company", and "script" keys when there is no error.
behaviour.company	uint64	Identifier of the Company to which this object belongs.
behaviour.id	uint64?	Identifier given as input for the command.
behaviour.script	uint64	Identifier of the script to which this object belongs.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"behaviour": {
		"company": number,
		"id": number,
		"script": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a behaviour object, or it is invalid.
400	3	Not enough keys exist in the behaviour object.
400	3	During create: When creating a new Behaviour, a name was not given, or it is invalid.
400	3	During create: When creating a new Behaviour, a script was not given.
400	3	During create: When creating a new Behaviour, a company was not given.
400	3	During update: When updating a Behaviour, the id was invalid.
400	3	During update: When updating a Behaviour, the name was given as blank.
400	3	During update: When updating a Behaviour, the v was not an array, or contained too few numbers.
400	3	The targets was given as null or blank. The targets must always have a value, or you can not send the targets key. Returns an ErrorDetailInput as the `errorDetails`.
400	3	One of the behaviour.parameters was invalid. Returns an ErrorDetailInput as the `errorDetails`.
400	3	One of the behaviour.parameters keys was blank or white-space. Returns an ErrorDetailInput as the `errorDetails`.
401	5	You do not have permission to create a new Behaviour.
401	5	You do not have permission to update this Behaviour.
400	6	During update: When updating a Behaviour, an incorrect v value was given as input.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	23	During update: The BehaviourScript was not found by its unique identifier.
404	26	During update: The Behaviour was not found by its unique identifier.
409	130	There is one or more missing or invalid parameters required by the BehaviourScript. Returns an ErrorDetailBadKeys as the `errorDetails`.
409	130	During update: When updating a Behaviour, the behaviour.script can not be changed. Returns an ErrorDetailBadKeys as the `errorDetails`.
409	130	During update: When updating a Behaviour, the behaviour.company can not be changed. Returns an ErrorDetailBadKeys as the `errorDetails`.

DELETE/behaviours

Deletes a Behaviour.

Response description

Property	Type	Description
behaviour	RespDeleted	An object which contains the Behaviour's id, owning Company id, and deleted status.
behaviour.company	uint64	Identifier of the Company to which this object belongs.
behaviour.deleted	boolean	Flag showing if the object is deleted.
behaviour.id	uint64?	Identifier given as input for the command.
behaviour.v	Array.<uint32>
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"behaviour": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a behaviour object, or it is invalid.
400	3	The behaviour object does not contain an id, or it is invalid.
401	5	You do not have permission to delete this Behaviour.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	26	The Behaviour was not found by its unique identifier.

GET/behaviours/{behaviourId}?includeDeleted=boolean

Gets details of the specified Behaviour.

URL Parameters

Parameter	Type	Required	Description
behaviourId	uint64	required	Unique identifier of the Behaviour.
includeDeleted	boolean	optional	False by default, but when true the command will also return deleted objects.

Response description

Property	Type	Description
behaviour	Behaviour	The requested Behaviour.
behaviour.company	uint64 see: Company.id	The company to which this behaviour belongs.
behaviour.filters	expression	A search pattern used to filter the providers which can implement this behaviour.
behaviour.id	uint64	Unique identifier of this behaviour.
behaviour.name	string maximum-length: 100	The name of this behaviour.
behaviour.notes	string	Notes.
behaviour.parameters	Object.<string, BehaviourParameter>	The list of defined variable name/value pairs for the script requires.
behaviour.priority	byte	The priority flag allows you to define an execution order for all behaviours for a provider.
behaviour.processedUtc	datetime	When the was change procesed.
behaviour.script	uint64 see: BehaviourScript.id	The script which this behaviour implements.
behaviour.targets	expression	The search pattern used to target the assets which will embed this behaviour in their execution context.
behaviour.updated		by: login, from: monster
behaviour.v	Array.<uint32>	Object version keys used to validate synchronization for all object properties.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"behaviour": {
		"company": number,
		"filters": string,
		"id": number,
		"name": string,
		"notes": string,
		"parameters": {
			string: {
				"context": string,
				"notes": string,
				"type": string,
				"value": string
			}
		},
		"priority": number,
		"processedUtc": string,
		"script": number,
		"targets": string,
		"updated": {
		},
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a behaviour object, or it is invalid.
400	3	The behaviour object does not contain an id, or it is invalid.
401	5	You do not have permission to view this Behaviour.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	26	The Behaviour was not found by its unique identifier.

POST/behaviours/{behaviourId}

Creates a new or updates an existing Behaviour.

URL Parameters

Parameter	Type	Required	Description
behaviourId	uint64?	optional	Unique identifier of the Behaviour. This value is optional, and ignored by the command.

HTTP Request body description

Property	Type	Required	Description
behaviour	Object.<string, ?>	always	A simple object to contain the Behaviour parameters.
behaviour.company	uint64?	create
behaviour.filters	expression	optional	A search pattern used to select the assets which will embed this Behaviour in their execution context.
behaviour.id	uint64?	update	The unique identifier of the Behaviour you want to update.
behaviour.name	string maximum-length: 100	create	Name for the Behaviour.
behaviour.notes	string	optional	Notes for the Behaviour.
behaviour.parameters	Object.<string, BehaviourParameter>	optional	The values needed to implement the script. Each key in this object is the name of a required script argument.
behaviour.priority	byte?	optional	The order in which this Behaviour is executed.
behaviour.script	uint64?	create	Identifier of the BehaviourScript to which this Behaviour belongs. After creation, this value is read-only.
behaviour.targets	expression	optional	A search pattern used to select the providers which can implement this Behaviour.
behaviour.v	Array.<int32>	optional
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"behaviour": {
		"company": number,
		"filters": string,
		"id": number,
		"name": string,
		"notes": string,
		"parameters": {
			string: {
				"context": string,
				"notes": string,
				"type": string,
				"value": string
			}
		},
		"priority": number,
		"script": number,
		"targets": string,
		"v": [
			number
		]
	},
	"reqId": number
}

Response description

Property	Type	Description
behaviour	RespIdScript	An object which contains the "id", "company", and "script" keys when there is no error.
behaviour.company	uint64	Identifier of the Company to which this object belongs.
behaviour.id	uint64?	Identifier given as input for the command.
behaviour.script	uint64	Identifier of the script to which this object belongs.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"behaviour": {
		"company": number,
		"id": number,
		"script": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a behaviour object, or it is invalid.
400	3	Not enough keys exist in the behaviour object.
400	3	During create: When creating a new Behaviour, a name was not given, or it is invalid.
400	3	During create: When creating a new Behaviour, a script was not given.
400	3	During create: When creating a new Behaviour, a company was not given.
400	3	During update: When updating a Behaviour, the id was invalid.
400	3	During update: When updating a Behaviour, the name was given as blank.
400	3	During update: When updating a Behaviour, the v was not an array, or contained too few numbers.
400	3	The targets was given as null or blank. The targets must always have a value, or you can not send the targets key. Returns an ErrorDetailInput as the `errorDetails`.
400	3	One of the behaviour.parameters was invalid. Returns an ErrorDetailInput as the `errorDetails`.
400	3	One of the behaviour.parameters keys was blank or white-space. Returns an ErrorDetailInput as the `errorDetails`.
401	5	You do not have permission to create a new Behaviour.
401	5	You do not have permission to update this Behaviour.
400	6	During update: When updating a Behaviour, an incorrect v value was given as input.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	23	During update: The BehaviourScript was not found by its unique identifier.
404	26	During update: The Behaviour was not found by its unique identifier.
409	130	There is one or more missing or invalid parameters required by the BehaviourScript. Returns an ErrorDetailBadKeys as the `errorDetails`.
409	130	During update: When updating a Behaviour, the behaviour.script can not be changed. Returns an ErrorDetailBadKeys as the `errorDetails`.
409	130	During update: When updating a Behaviour, the behaviour.company can not be changed. Returns an ErrorDetailBadKeys as the `errorDetails`.

DELETE/behaviours/{behaviourId}

Deletes a Behaviour.

URL Parameters

Parameter	Type	Required	Description
behaviourId	uint64	required	Unique identifier of the Behaviour.

Response description

Property	Type	Description
behaviour	RespDeleted	An object which contains the Behaviour's id, owning Company id, and deleted status.
behaviour.company	uint64	Identifier of the Company to which this object belongs.
behaviour.deleted	boolean	Flag showing if the object is deleted.
behaviour.id	uint64?	Identifier given as input for the command.
behaviour.v	Array.<uint32>
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"behaviour": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a behaviour object, or it is invalid.
400	3	The behaviour object does not contain an id, or it is invalid.
401	5	You do not have permission to delete this Behaviour.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	26	The Behaviour was not found by its unique identifier.

GET/behaviours/{behaviourId}/logs?includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

Gets the list of BehaviourLog for the specified Behaviour.

URL Parameters

Parameter	Type	Required	Description
behaviourId	uint64	required	Unique identifier of the Behaviour.
highest	uint64?	optional	When using , sets the largest valued id objects to retrieve.
includeArchive	boolean	optional	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	False by default, but when true, the command will also return deleted objects.
limit	uint16?	optional	When using , sets the maximum number of objects retrieved from the archive.
lowest	uint64?	optional	When using , sets the smallest valued id objects to retrieve.

Response description

Property	Type	Description
behaviour	RespIdScript	An object to contain the "id" of the Behaviour to which the array of BehaviourLogs belong.
behaviour.company	uint64	Identifier of the Company to which this object belongs.
behaviour.id	uint64?	Identifier given as input for the command.
behaviour.script	uint64	Identifier of the script to which this object belongs.
behaviourLogs	Array.<BehaviourLog>	The list of requested BehaviourLogs.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"behaviour": {
		"company": number,
		"id": number,
		"script": number
	},
	"behaviourLogs": [
		{
			"asset": number,
			"behaviour": number,
			"character": number,
			"company": number,
			"dts": string,
			"id": number,
			"kind": string,
			"line": number,
			"message": string,
			"processedUtc": string,
			"script": number,
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a behaviour object, or it is invalid.
400	3	The behaviour object does not contain an id, or it is invalid.
401	5	You do not have permission to view BehaviourLogs for this Behaviour.
401	5	You do not have permission to view Behaviours for this Company.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	26	The Behaviour was not found by its unique identifier.

DELETE/behaviours/{behaviourId}/logs

Gets the list of BehaviourLogs for the specified Behaviour.

URL Parameters

Parameter	Type	Required	Description
behaviourId	uint64	required	Unique identifier of the Behaviour.

Response description

Property	Type	Description
behaviour	RespIdScript	An object to contain the "id" of the Behaviour to which the array of BehaviourLogs belong.
behaviour.company	uint64	Identifier of the Company to which this object belongs.
behaviour.id	uint64?	Identifier given as input for the command.
behaviour.script	uint64	Identifier of the script to which this object belongs.
count	int32	The total number of behaviour logs cleared.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"behaviour": {
		"company": number,
		"id": number,
		"script": number
	},
	"count": number,
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a behaviour object, or it is invalid.
400	3	The behaviour object does not contain an id, or it is invalid.
401	5	You do not have permission to view BehaviourLogs for this Behaviour.
401	5	You do not have permission to clear Behaviours for this Company.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	26	The Behaviour was not found by its unique identifier.

PATCH/behaviours/{behaviourId}/restore

Restores a deleted Behaviour.

URL Parameters

Parameter	Type	Required	Description
behaviourId	uint64	required	Unique identifier of the Behaviour.

HTTP Request body description

Property	Type	Required	Description
behaviour	ParamId	always	An object to contain the "id" key.
behaviour.id	uint64	always	Identifier given as input for the command.
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"behaviour": {
		"id": number
	},
	"reqId": number
}

Response description

Property	Type	Description
behaviour	RespDeleted	An object which contains the Behaviour's id, owning Company id, and deleted status.
behaviour.company	uint64	Identifier of the Company to which this object belongs.
behaviour.deleted	boolean	Flag showing if the object is deleted.
behaviour.id	uint64?	Identifier given as input for the command.
behaviour.v	Array.<uint32>
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"behaviour": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a behaviour object, or it is invalid.
400	3	The behaviour object does not contain an id, or it is invalid.
401	5	You do not have permission to restore this Behaviour.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	26	The Behaviour was not found by its unique identifier.
400	27	The Behaviour was found, but is not marked as deleted.

GET/behaviours/logs?asset={uint64}&includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

Gets the list of BehaviourLogs for the specified Asset.

URL Parameters

Parameter	Type	Required	Description
asset	uint64	required	Unique identifier of the Asset.
highest	uint64?	optional	When using , sets the largest valued id objects to retrieve.
includeArchive	boolean	optional	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	False by default, but when true, the command will also return deleted objects.
limit	uint16?	optional	When using , sets the maximum number of objects retrieved from the archive.
lowest	uint64?	optional	When using , sets the smallest valued id objects to retrieve.

Response description

Property	Type	Description
asset	RespIdCompany	An object to contain the "id" of the Asset to which the array of BehaviourLogs relates.
asset.company	uint64	Identifier of the Company to which this object belongs.
asset.id	uint64?	Identifier given as input for the command.
behaviourLogs	Array.<BehaviourLog>	The list of requested BehaviourLogs.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"asset": {
		"company": number,
		"id": number
	},
	"behaviourLogs": [
		{
			"asset": number,
			"behaviour": number,
			"character": number,
			"company": number,
			"dts": string,
			"id": number,
			"kind": string,
			"line": number,
			"message": string,
			"processedUtc": string,
			"script": number,
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a asset object, or it is invalid.
400	3	The asset object does not contain an id, or it is invalid.
401	5	You do not have permission to view this Asset.
401	5	You do not have permission to view BehaviourLogs for this Asset's Company.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	20	The Asset was not found by its unique identifier.

DELETE/behaviours/logs?asset={uint64}

Gets the list of BehaviourLogs for the specified Asset.

URL Parameters

Parameter	Type	Required	Description
asset	uint64	required	Unique identifier of the Asset.

Response description

Property	Type	Description
asset	RespIdCompany	An object to contain the "id" of the Asset to which the array of BehaviourLogs relates.
asset.company	uint64	Identifier of the Company to which this object belongs.
asset.id	uint64?	Identifier given as input for the command.
count	int32	The total number of behaviour logs cleared.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"asset": {
		"company": number,
		"id": number
	},
	"count": number,
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a asset object, or it is invalid.
400	3	The asset object does not contain an id, or it is invalid.
401	5	You do not have permission to view this Asset.
401	5	You do not have permission to clear Behaviours for this Asset.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	20	The Asset was not found by its unique identifier.

GET/behaviours/scripts?tree=boolean&includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

This request is an alias of /companies/{your-company-id}/behaviours/scripts?tree=true.

URL Parameters

Parameter	Type	Required	Default	Description
highest	uint64	optional		When using , sets the maximum id when listing from the database.
includeArchive	boolean	optional	`false`	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	`false`	False by default, but when true the command will also return deleted objects.
limit	uint16	optional		When using , sets the maximum number of objects in this response.
lowest	uint64	optional		When using , sets the minimum id when listing from the database.
tree	boolean	optional	`true`	Defaults to true for this alias.
your-company-id	uint64	aliased	`{your-company-id}`	Your own Company's identifier.

PATCH/behaviours/scripts

Creates a new or updates an existing BehaviourScript.

HTTP Request body description

Property	Type	Required	Description
behaviourScript	Object.<string, ?>	always	A simple object to contain the BehaviourScript parameters.
behaviourScript.company	uint64?	create	Identifier of the Company to which this BehaviourScript belongs. After creation, this value is read-only.
behaviourScript.fill	string	optional	Background and fill colour in the UI.
behaviourScript.filters	expression	optional	A search pattern used to select the providers.
behaviourScript.global	boolean	optional	When set to true, this Company as well as all child companies will be able to implement this BehaviourScript for that companies assets.
behaviourScript.graphic	string	optional	The name of the symbol shown in the UI.
behaviourScript.id	uint64?	update	The unique identifier of the BehaviourScript you want to update.
behaviourScript.name	string maximum-length: 100	create	Name for the BehaviourScript.
behaviourScript.notes	string	optional	Notes for the BehaviourScript.
behaviourScript.parameters	Object.<string, BehaviourParameter>	optional	The defined arguments for this BehaviourScript. Each key in the object is the name of an argument.
behaviourScript.source	string	create	Source code of the BehaviourScript.
behaviourScript.stroke	string	optional	Text and outline colour in the UI.
behaviourScript.v	Array.<int32>	optional
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"behaviourScript": {
		"company": number,
		"fill": string,
		"filters": string,
		"global": boolean,
		"graphic": string,
		"id": number,
		"name": string,
		"notes": string,
		"parameters": {
			string: {
				"context": string,
				"notes": string,
				"type": string,
				"value": string
			}
		},
		"source": string,
		"stroke": string,
		"v": [
			number
		]
	},
	"reqId": number
}

Response description

Property	Type	Description
behaviourScript	RespIdCompany	An object which contains the "id" and "company" keys when there is no error.
behaviourScript.company	uint64	Identifier of the Company to which this object belongs.
behaviourScript.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"behaviourScript": {
		"company": number,
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a behaviourScript object, or it is invalid.
400	3	Not enough keys exist in the behaviourScript object.
400	3	During create: When creating a new BehaviourScript, a name was not given, or it is invalid.
400	3	During create: When creating a new BehaviourScript, a company was not given.
400	3	During create: When creating a new BehaviourScript, the source was not given, or it is blank.
400	3	During update: When updating a BehaviourScript, the id was invalid.
400	3	During update: When updating a BehaviourScript, the name was given as blank.
400	3	During update: When updating a BehaviourScript, the v was not an array, or contained too few numbers.
400	3	One of the behaviourScript.parameters default values' was not valid. Returns an ErrorDetailBadKeys as the `errorDetails`.
400	3	One of the behaviourScript.parameters was invalid. Returns an ErrorDetailInput as the `errorDetails`.
400	3	One of the behaviourScript.parameters keys was blank or white-space. Returns an ErrorDetailInput as the `errorDetails`.
401	5	You do not have permission to create a new BehaviourScript.
401	5	You do not have permission to update this BehaviourScript.
400	6	During update: When updating a BehaviourScript, an incorrect v value was given as input.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	23	During update: The BehaviourScript was not found by its unique identifier.
409	25	During update: When updating a BehaviourScript which is marked as global, but is being set as private, but is implemented by Behaviours from child companies.. Returns an ErrorDetailCount as the `errorDetails`.
409	130	During update: When updating a BehaviourScript, the behaviourScript.company can not be changed.

DELETE/behaviours/scripts

Deletes an existing BehaviourScript.

Response description

Property	Type	Description
behaviourScript	RespDeleted	An object which contains the BehaviourScript's id, owning Company id, and deleted status.
behaviourScript.company	uint64	Identifier of the Company to which this object belongs.
behaviourScript.deleted	boolean	Flag showing if the object is deleted.
behaviourScript.id	uint64?	Identifier given as input for the command.
behaviourScript.v	Array.<uint32>
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"behaviourScript": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a behaviourScript object, or it is invalid.
400	3	The behaviourScript object does not contain an id, or it is invalid.
401	5	You do not have permission to delete this BehaviourScript.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	23	The BehaviourScript was not found by its unique identifier.
409	25	This BehaviourScript is still being used by one of more Behaviours. Returns an ErrorDetailCount as the `errorDetails`.

GET/behaviours/scripts/{scriptId}?includeDeleted=boolean

Gets details of the specified BehaviourScript.

URL Parameters

Parameter	Type	Required	Description
includeDeleted	boolean	optional	False by default, but when true the command will also return deleted objects.
scriptId	uint64	required	Unique identifier of the BehaviourScript.

Response description

Property	Type	Description
behaviourScript	BehaviourScript	The requested BehaviourScript.
behaviourScript.company	uint64 see: Company.id	The company to which this script belongs.
behaviourScript.compiles	boolean	Flag set by the compiler if this code compiles
behaviourScript.fill	colour maximum-length: 22	The background colour given to this script for easy visual identification.
behaviourScript.filters	expression	A list of targeting expressions. These expressions are defaults for derived Behaviours.
behaviourScript.global	boolean	Indicates whether this script is available to child companies.
behaviourScript.graphic	codified maximum-length: 22	The codified graphic name given to this script for easy visual identification.
behaviourScript.id	uint64	Unique identifier of this script.
behaviourScript.name	string maximum-length: 100	The nickname given to this script.
behaviourScript.notes	string	Usage notes and instructions for users on how best to setup this script.
behaviourScript.parameters	Object.<string, BehaviourParameter>	Listed parameters for the Behaviour function.
behaviourScript.processedUtc	datetime	When the was change procesed.
behaviourScript.source	string maximum-length: 8060	The source code.
behaviourScript.stroke	colour maximum-length: 22	The text/graphic colour given to this script for easy visual identification.
behaviourScript.updated		by: login, from: monster
behaviourScript.v	Array.<uint32>	Object version keys used to validate synchronization for all object properties.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"behaviourScript": {
		"company": number,
		"compiles": boolean,
		"fill": string,
		"filters": string,
		"global": boolean,
		"graphic": string,
		"id": number,
		"name": string,
		"notes": string,
		"parameters": {
			string: {
				"context": string,
				"notes": string,
				"type": string,
				"value": string
			}
		},
		"processedUtc": string,
		"source": string,
		"stroke": string,
		"updated": {
		},
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a behaviourScript object, or it is invalid.
400	3	The behaviourScript object does not contain an id, or it is invalid.
401	5	You do not have permission to view this BehaviourScript.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	23	The BehaviourScript was not found by its unique identifier.

POST/behaviours/scripts/{scriptId}

Creates a new or updates an existing BehaviourScript.

URL Parameters

Parameter	Type	Required	Description
scriptId	uint64?	optional	Unique identifier of the BehaviourScript. This value is optional, and ignored by the command.

HTTP Request body description

Property	Type	Required	Description
behaviourScript	Object.<string, ?>	always	A simple object to contain the BehaviourScript parameters.
behaviourScript.company	uint64?	create	Identifier of the Company to which this BehaviourScript belongs. After creation, this value is read-only.
behaviourScript.fill	string	optional	Background and fill colour in the UI.
behaviourScript.filters	expression	optional	A search pattern used to select the providers.
behaviourScript.global	boolean	optional	When set to true, this Company as well as all child companies will be able to implement this BehaviourScript for that companies assets.
behaviourScript.graphic	string	optional	The name of the symbol shown in the UI.
behaviourScript.id	uint64?	update	The unique identifier of the BehaviourScript you want to update.
behaviourScript.name	string maximum-length: 100	create	Name for the BehaviourScript.
behaviourScript.notes	string	optional	Notes for the BehaviourScript.
behaviourScript.parameters	Object.<string, BehaviourParameter>	optional	The defined arguments for this BehaviourScript. Each key in the object is the name of an argument.
behaviourScript.source	string	create	Source code of the BehaviourScript.
behaviourScript.stroke	string	optional	Text and outline colour in the UI.
behaviourScript.v	Array.<int32>	optional
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"behaviourScript": {
		"company": number,
		"fill": string,
		"filters": string,
		"global": boolean,
		"graphic": string,
		"id": number,
		"name": string,
		"notes": string,
		"parameters": {
			string: {
				"context": string,
				"notes": string,
				"type": string,
				"value": string
			}
		},
		"source": string,
		"stroke": string,
		"v": [
			number
		]
	},
	"reqId": number
}

Response description

Property	Type	Description
behaviourScript	RespIdCompany	An object which contains the "id" and "company" keys when there is no error.
behaviourScript.company	uint64	Identifier of the Company to which this object belongs.
behaviourScript.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"behaviourScript": {
		"company": number,
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a behaviourScript object, or it is invalid.
400	3	Not enough keys exist in the behaviourScript object.
400	3	During create: When creating a new BehaviourScript, a name was not given, or it is invalid.
400	3	During create: When creating a new BehaviourScript, a company was not given.
400	3	During create: When creating a new BehaviourScript, the source was not given, or it is blank.
400	3	During update: When updating a BehaviourScript, the id was invalid.
400	3	During update: When updating a BehaviourScript, the name was given as blank.
400	3	During update: When updating a BehaviourScript, the v was not an array, or contained too few numbers.
400	3	One of the behaviourScript.parameters default values' was not valid. Returns an ErrorDetailBadKeys as the `errorDetails`.
400	3	One of the behaviourScript.parameters was invalid. Returns an ErrorDetailInput as the `errorDetails`.
400	3	One of the behaviourScript.parameters keys was blank or white-space. Returns an ErrorDetailInput as the `errorDetails`.
401	5	You do not have permission to create a new BehaviourScript.
401	5	You do not have permission to update this BehaviourScript.
400	6	During update: When updating a BehaviourScript, an incorrect v value was given as input.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	23	During update: The BehaviourScript was not found by its unique identifier.
409	25	During update: When updating a BehaviourScript which is marked as global, but is being set as private, but is implemented by Behaviours from child companies.. Returns an ErrorDetailCount as the `errorDetails`.
409	130	During update: When updating a BehaviourScript, the behaviourScript.company can not be changed.

DELETE/behaviours/scripts/{scriptId}

Deletes an existing BehaviourScript.

URL Parameters

Parameter	Type	Required	Description
scriptId	uint64	required	Unique identifier of the BehaviourScript.

Response description

Property	Type	Description
behaviourScript	RespDeleted	An object which contains the BehaviourScript's id, owning Company id, and deleted status.
behaviourScript.company	uint64	Identifier of the Company to which this object belongs.
behaviourScript.deleted	boolean	Flag showing if the object is deleted.
behaviourScript.id	uint64?	Identifier given as input for the command.
behaviourScript.v	Array.<uint32>
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"behaviourScript": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a behaviourScript object, or it is invalid.
400	3	The behaviourScript object does not contain an id, or it is invalid.
401	5	You do not have permission to delete this BehaviourScript.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	23	The BehaviourScript was not found by its unique identifier.
409	25	This BehaviourScript is still being used by one of more Behaviours. Returns an ErrorDetailCount as the `errorDetails`.

GET/behaviours/scripts/{scriptId}/logs?includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

Gets the list of BehaviourLogs for the specified BehaviourScript.

URL Parameters

Parameter	Type	Required	Description
highest	uint64?	optional	When using , sets the largest valued id objects to retrieve.
includeArchive	boolean	optional	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	False by default, but when true, the command will also return deleted objects.
limit	uint16?	optional	When using , sets the maximum number of objects retrieved from the archive.
lowest	uint64?	optional	When using , sets the smallest valued id objects to retrieve.
scriptId	uint64	required	Unique identifier of the BehaviourScript.

Response description

Property	Type	Description
behaviourLogs	Array.<BehaviourLog>	The list of requested BehaviourLogs.
behaviourScript	RespIdCompany	An object to contain the "id" of the BehaviourScript to which the array of BehaviourLogs belong.
behaviourScript.company	uint64	Identifier of the Company to which this object belongs.
behaviourScript.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"behaviourLogs": [
		{
			"asset": number,
			"behaviour": number,
			"character": number,
			"company": number,
			"dts": string,
			"id": number,
			"kind": string,
			"line": number,
			"message": string,
			"processedUtc": string,
			"script": number,
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"behaviourScript": {
		"company": number,
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a behaviourScript object, or it is invalid.
400	3	The behaviourScript object does not contain an id, or it is invalid.
401	5	You do not have permission to view BehaviourLogs for the BehaviourScript's Company.
401	5	You do not have permission to view BehaviourScripts for this Company.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	23	The BehaviourScript was not found by its unique identifier.

DELETE/behaviours/scripts/{scriptId}/logs

Gets the list of BehaviourLogs for the specified BehaviourScript.

URL Parameters

Parameter	Type	Required	Description
scriptId	uint64	required	Unique identifier of the BehaviourScript.

Response description

Property	Type	Description
behaviourScript	RespIdCompany	An object to contain the "id" of the BehaviourScript to which the array of BehaviourLogs belong.
behaviourScript.company	uint64	Identifier of the Company to which this object belongs.
behaviourScript.id	uint64?	Identifier given as input for the command.
count	int32	The total number of behaviour logs cleared.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"behaviourScript": {
		"company": number,
		"id": number
	},
	"count": number,
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a behaviourScript object, or it is invalid.
400	3	The behaviourScript object does not contain an id, or it is invalid.
401	5	You do not have permission to view BehaviourLogs for the BehaviourScript's Company.
401	5	You do not have permission to clear behaviours for this BehaviourScript.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	23	The BehaviourScript was not found by its unique identifier.

PATCH/behaviours/scripts/{scriptId}/restore

Restores the specified BehaviourScript.

URL Parameters

Parameter	Type	Required	Description
scriptId	uint64	required	Unique identifier of the BehaviourScript.

HTTP Request body description

Property	Type	Required	Description
behaviourScript	ParamId	always	An object to contain the "id" key.
behaviourScript.id	uint64	always	Identifier given as input for the command.
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"behaviourScript": {
		"id": number
	},
	"reqId": number
}

Response description

Property	Type	Description
behaviourScript	RespDeleted	An object which contains the BehaviourScript's id, owning Company id, and deleted status.
behaviourScript.company	uint64	Identifier of the Company to which this object belongs.
behaviourScript.deleted	boolean	Flag showing if the object is deleted.
behaviourScript.id	uint64?	Identifier given as input for the command.
behaviourScript.v	Array.<uint32>
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"behaviourScript": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a behaviourScript object, or it is invalid.
400	3	The behaviourScript object does not contain an id, or it is invalid.
401	5	You do not have permission to restore this BehaviourScript.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	23	The BehaviourScript was not found by its unique identifier.
400	24	The BehaviourScript was found, but is not marked as deleted.

GET/behaviours?script={uint64}&includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

Gets the list of Behaviours for the specified Company.

URL Parameters

Parameter	Type	Required	Description
highest	uint64?	optional	When using , sets the largest valued id objects to retrieve.
includeArchive	boolean	optional	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	False by default, but when true, the command will also return deleted objects.
limit	uint16?	optional	When using , sets the maximum number of objects retrieved from the archive.
lowest	uint64?	optional	When using , sets the smallest valued id objects to retrieve.
script	uint64	required	Unique identifier of the BehaviourScript.

Response description

Property	Type	Description
behaviours	Array.<Behaviour>	The list of reqested Behaviours.
behaviourScript	RespIdCompany	An object to contain the "id" of the Company to which the array of Behaviours belong.
behaviourScript.company	uint64	Identifier of the Company to which this object belongs.
behaviourScript.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"behaviours": [
		{
			"company": number,
			"filters": string,
			"id": number,
			"name": string,
			"notes": string,
			"parameters": {
				string: {
					"context": string,
					"notes": string,
					"type": string,
					"value": string
				}
			},
			"priority": number,
			"processedUtc": string,
			"script": number,
			"targets": string,
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"behaviourScript": {
		"company": number,
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a behaviourScript object, or it is invalid.
400	3	The behaviourScript object does not contain an id, or it is invalid.
401	5	You do not have permission to view Behaviours for this Company.
401	5	You do not have permission to view BehaviourScripts for this Company.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	23	The BehaviourScript was not found by its unique identifier.

GET/companies/{companyId}/behaviours?includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

Gets the list of Behaviours for the specified Company.

URL Parameters

Parameter	Type	Required	Description
companyId	uint64	required	Unique identifier of the Company.
highest	uint64?	optional	When using , sets the largest valued id objects to retrieve.
includeArchive	boolean	optional	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	False by default, but when true, the command will also return deleted objects.
limit	uint16?	optional	When using , sets the maximum number of objects retrieved from the archive.
lowest	uint64?	optional	When using , sets the smallest valued id objects to retrieve.

Response description

Property	Type	Description
behaviours	Array.<Behaviour>	The list of reqested Behaviours.
company	RespId	An object to contain the "id" of the Company to which the array of Behaviours belong.
company.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"behaviours": [
		{
			"company": number,
			"filters": string,
			"id": number,
			"name": string,
			"notes": string,
			"parameters": {
				string: {
					"context": string,
					"notes": string,
					"type": string,
					"value": string
				}
			},
			"priority": number,
			"processedUtc": string,
			"script": number,
			"targets": string,
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
401	5	You do not have permission to view this Company.
401	5	You do not have permission to view Behaviours for this Company.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company was not found by its unique identifier.

GET/companies/{companyId}/behaviours/scripts?tree=boolean&includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

Gets the list of BehaviourScripts for the specified Company.

URL Parameters

Parameter	Type	Required	Default	Description
companyId	uint64	required		Unique identifier of the Company
highest	uint64?	optional		When using , sets the largest valued id objects to retrieve.
includeArchive	boolean	optional		Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional		False by default, but when true, the command will also return deleted objects.
limit	uint16?	optional		When using , sets the maximum number of objects retrieved from the archive.
lowest	uint64?	optional		When using , sets the smallest valued id objects to retrieve.
tree	boolean	optional	`true`	When true (default) the getter to retrieve the given Company's list of BehaviourScripts as well as any publicly available BehaviourScripts for the Company's parent(s).

Response description

Property	Type	Description
behaviourScripts	Array.<BehaviourScript>	The list of requested BehaviourScripts.
company	RespId	An object to contain the "id" of the Company to which the array of BehaviourScripts belong.
company.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"behaviourScripts": [
		{
			"company": number,
			"compiles": boolean,
			"fill": string,
			"filters": string,
			"global": boolean,
			"graphic": string,
			"id": number,
			"name": string,
			"notes": string,
			"parameters": {
				string: {
					"context": string,
					"notes": string,
					"type": string,
					"value": string
				}
			},
			"processedUtc": string,
			"source": string,
			"stroke": string,
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
401	5	You do not have permission to view BehaviourScripts for this Company.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company was not found by its unique identifier.

Billing

GET/billing/profiles?includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

This request is an alias of /companies/{your-company-id}/billing/profiles.

URL Parameters

Parameter	Type	Required	Default	Description
your-company-id	uint64	aliased	`{your-company-id}`	Your own Company's identifier.

PATCH/billing/profiles

Creates new or updates an existing BillingProfile.

HTTP Request body description

Property	Type	Required	Description
billingProfile	Object.<string, ?>	always	A simple object to contain the BillingProfile parameters.
billingProfile.billee	uint64?	optional	Unique identifier of the Company receiving the bill.
billingProfile.company	uint64?	optional	Unique identifier of the Company that owns this BillingProfile and is sending the bill.
billingProfile.currency	BillingCurrency?	optional	Kind of money.
billingProfile.cycle	BillingCycle?	optional	Repeating cycle used for generating bills.
billingProfile.cycleEnd	datetime	optional	When should the cycle end (customer cancelled); null means it never ends.
billingProfile.cyclePostDated	boolean	optional	Pro-rated, or post-dated.
billingProfile.cycleStart	datetime	optional	When is the first day of the billing cycle.
billingProfile.googleServicesEnabled	boolean	optional	Are the Google services available to be proxied by the service?
billingProfile.id	uint64?	optional	Unique identifier of the BillingProfile you want to update.
billingProfile.messages	Array.<BillableSmsProfile>	optional	SMS messaging tiers.
billingProfile.name	string	optional	Name for the BillingProfile
billingProfile.notes	string	optional	Notes about the BillingProfile for the billee or target.
billingProfile.target	uint64?	optional	Unique identifier of the Company to which this rule pertains.
billingProfile.v	Array.<int32>	optional
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"billingProfile": {
		"billee": number,
		"company": number,
		"currency": string,
		"cycle": string,
		"cycleEnd": string,
		"cyclePostDated": boolean,
		"cycleStart": string,
		"googleServicesEnabled": boolean,
		"id": number,
		"messages": [
			{
				"amount": number,
				"limit": number
			}
		],
		"name": string,
		"notes": string,
		"target": number,
		"v": [
			number
		]
	},
	"reqId": number
}

Response description

Property	Type	Description
billingProfile	RespIdCompany	An object which contains the "id", "company", and "profile" keys.
billingProfile.company	uint64	Identifier of the Company to which this object belongs.
billingProfile.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"billingProfile": {
		"company": number,
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a billingProfile object, or it is invalid.
400	3	Not enough keys exist in the billingProfile object.
400	3	The messages are invalid.
400	3	The cycle is invalid.
400	3	The currency is invalid.
400	3	The cycleStart date is invalid.
400	3	The cycleEnd date is invalid.
400	3	During create: When creating a new BillingProfile, start date is invalid.
400	3	During create: When creating a new BillingProfile, end date is invalid.
400	3	During create: When creating a new BillingProfile, kind is invalid.
400	3	During create: When creating a new BillingProfile, a name was not given, or it is invalid.
400	3	During create: When creating a new BillingProfile, company is invalid.
400	3	During create: When creating a new BillingProfile, target is invalid.
400	3	During create: When creating a new BillingProfile, billee is invalid.
400	3	During update: When updating a BillingProfile, the name was invalid.
400	3	During update: When updating a BillingProfile, the v was invalid.
401	5	During create: You do not have permission to create new BillingProfile.
401	5	During update: You do not have permission to update BillingProfile.
400	6	During update: When updating a BillingProfile, the v was not an array, or contained too few numbers.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The company was not found by its unique identifier.
404	28	The target was not found by its unique identifier.
404	28	The billee was not found by its unique identifier.
404	111	The BillingProfile was not found by its unique identifier. If you receive this error, please contact technical support.
409	130	During update: When updating a BillingProfile, the billingProfile.company can not be changed.

DELETE/billing/profiles

Deletes an existing BillingProfile.

Response description

Property	Type	Description
billingProfile	RespDeleted	An object which contains the BillingProfile's unique identifier and deleted status.
billingProfile.company	uint64	Identifier of the Company to which this object belongs.
billingProfile.deleted	boolean	Flag showing if the object is deleted.
billingProfile.id	uint64?	Identifier given as input for the command.
billingProfile.v	Array.<uint32>
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"billingProfile": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred, the BillingProfile was not deleted. If you receive this error, please contact technical support.
400	3	The request does not contain a billingProfile object, or it is invalid.
400	3	The requested billingProfile id was invalid.
401	5	You do not have permission to delete this Company's BillingProfiles.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	111	The BillingProfile was not found by its unique identifier.

GET/billing/profiles/{profileId}?includeDeleted=boolean

Gets details of the specified BillingProfile.

URL Parameters

Parameter	Type	Required	Description
includeDeleted	boolean	optional	False by default, but when true the command will also return deleted objects.
profileId	uint64	required	Unique identifier of the BillingProfile.

Response description

Property	Type	Description
billingProfile	BillingProfile	The requested BillingProfile.
billingProfile.billee	uint64 see: Company.id	Unique identifier of the Company receiving the bill. Most of the time, this value is the same as the target.
billingProfile.company	uint64 see: Company.id	Unique identifier of the Company that owns this profile and is sending the bill.
billingProfile.currency	BillingCurrency	kind of money
billingProfile.cycle	BillingCycle	Repeating cycle used for generating bills
billingProfile.cycleEnd	datetime	When should the cycle end (customer cancelled)
billingProfile.cyclePostDated	boolean	Pro-rated, or post-dated.
billingProfile.cycleStart	datetime	When is the first day of the billing cycle
billingProfile.googleServicesEnabled	boolean	Are the Google services available to be proxied by the service?
billingProfile.id	uint64	Unique identifier of this billing profile
billingProfile.messages	Array.<BillableSmsProfile>	SMS messaging tiers
billingProfile.name	string maximum-length: 254	The name for this profile
billingProfile.notes	string maximum-length: 1000	Notes about the billing profile for the billee or target.
billingProfile.processedUtc	datetime	When the was change procesed.
billingProfile.target	uint64 see: Company.id	Unique identifier of the Company to which this rule pertains.
billingProfile.updated		by: login, from: monster
billingProfile.v	Array.<uint32>	Object version keys used to validate synchronization for all object properties.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"billingProfile": {
		"billee": number,
		"company": number,
		"currency": string,
		"cycle": string,
		"cycleEnd": string,
		"cyclePostDated": boolean,
		"cycleStart": string,
		"googleServicesEnabled": boolean,
		"id": number,
		"messages": [
			{
				"amount": number,
				"limit": number
			}
		],
		"name": string,
		"notes": string,
		"processedUtc": string,
		"target": number,
		"updated": {
		},
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a billingProfile object, or it is invalid.
400	3	The requested billingProfile id was invalid.
401	5	You do not have permission to view this Company's BillingProfiles.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	111	The BillingProfile was not found by its unique identifier.

POST/billing/profiles/{profileId}

Creates new or updates an existing BillingProfile.

URL Parameters

Parameter	Type	Required	Description
profileId	uint64?	optional	Unique identifier of the BillingProfile. This value is optional, and ignored by the command.

HTTP Request body description

Property	Type	Required	Description
billingProfile	Object.<string, ?>	always	A simple object to contain the BillingProfile parameters.
billingProfile.billee	uint64?	optional	Unique identifier of the Company receiving the bill.
billingProfile.company	uint64?	optional	Unique identifier of the Company that owns this BillingProfile and is sending the bill.
billingProfile.currency	BillingCurrency?	optional	Kind of money.
billingProfile.cycle	BillingCycle?	optional	Repeating cycle used for generating bills.
billingProfile.cycleEnd	datetime	optional	When should the cycle end (customer cancelled); null means it never ends.
billingProfile.cyclePostDated	boolean	optional	Pro-rated, or post-dated.
billingProfile.cycleStart	datetime	optional	When is the first day of the billing cycle.
billingProfile.googleServicesEnabled	boolean	optional	Are the Google services available to be proxied by the service?
billingProfile.id	uint64?	optional	Unique identifier of the BillingProfile you want to update.
billingProfile.messages	Array.<BillableSmsProfile>	optional	SMS messaging tiers.
billingProfile.name	string	optional	Name for the BillingProfile
billingProfile.notes	string	optional	Notes about the BillingProfile for the billee or target.
billingProfile.target	uint64?	optional	Unique identifier of the Company to which this rule pertains.
billingProfile.v	Array.<int32>	optional
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"billingProfile": {
		"billee": number,
		"company": number,
		"currency": string,
		"cycle": string,
		"cycleEnd": string,
		"cyclePostDated": boolean,
		"cycleStart": string,
		"googleServicesEnabled": boolean,
		"id": number,
		"messages": [
			{
				"amount": number,
				"limit": number
			}
		],
		"name": string,
		"notes": string,
		"target": number,
		"v": [
			number
		]
	},
	"reqId": number
}

Response description

Property	Type	Description
billingProfile	RespIdCompany	An object which contains the "id", "company", and "profile" keys.
billingProfile.company	uint64	Identifier of the Company to which this object belongs.
billingProfile.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"billingProfile": {
		"company": number,
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a billingProfile object, or it is invalid.
400	3	Not enough keys exist in the billingProfile object.
400	3	The messages are invalid.
400	3	The cycle is invalid.
400	3	The currency is invalid.
400	3	The cycleStart date is invalid.
400	3	The cycleEnd date is invalid.
400	3	During create: When creating a new BillingProfile, start date is invalid.
400	3	During create: When creating a new BillingProfile, end date is invalid.
400	3	During create: When creating a new BillingProfile, kind is invalid.
400	3	During create: When creating a new BillingProfile, a name was not given, or it is invalid.
400	3	During create: When creating a new BillingProfile, company is invalid.
400	3	During create: When creating a new BillingProfile, target is invalid.
400	3	During create: When creating a new BillingProfile, billee is invalid.
400	3	During update: When updating a BillingProfile, the name was invalid.
400	3	During update: When updating a BillingProfile, the v was invalid.
401	5	During create: You do not have permission to create new BillingProfile.
401	5	During update: You do not have permission to update BillingProfile.
400	6	During update: When updating a BillingProfile, the v was not an array, or contained too few numbers.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The company was not found by its unique identifier.
404	28	The target was not found by its unique identifier.
404	28	The billee was not found by its unique identifier.
404	111	The BillingProfile was not found by its unique identifier. If you receive this error, please contact technical support.
409	130	During update: When updating a BillingProfile, the billingProfile.company can not be changed.

DELETE/billing/profiles/{profileId}

Deletes an existing BillingProfile.

URL Parameters

Parameter	Type	Required	Description
profileId	uint64	required	Unique identifier of the BillingProfile.

Response description

Property	Type	Description
billingProfile	RespDeleted	An object which contains the BillingProfile's unique identifier and deleted status.
billingProfile.company	uint64	Identifier of the Company to which this object belongs.
billingProfile.deleted	boolean	Flag showing if the object is deleted.
billingProfile.id	uint64?	Identifier given as input for the command.
billingProfile.v	Array.<uint32>
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"billingProfile": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred, the BillingProfile was not deleted. If you receive this error, please contact technical support.
400	3	The request does not contain a billingProfile object, or it is invalid.
400	3	The requested billingProfile id was invalid.
401	5	You do not have permission to delete this Company's BillingProfiles.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	111	The BillingProfile was not found by its unique identifier.

GET/billing/profiles/{profileId}/licenses?includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

Gets the list of BillableHostingLicenses for the specified BillingProfile.

URL Parameters

Parameter	Type	Required	Description
highest	uint64?	optional	When using , sets the largest valued id objects to retrieve.
includeArchive	boolean	optional	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	False by default, but when true, the command will also return deleted objects.
limit	uint16?	optional	When using , sets the maximum number of objects retrieved from the archive.
lowest	uint64?	optional	When using , sets the smallest valued id objects to retrieve.
profileId	uint64	required	Unique identifier of the BillingProfile.

Response description

Property	Type	Description
billingProfile	RespIdCompany	An object to contain the "id" of the BillingProfile to which the array of BillableHostingLicenses belong.
billingProfile.company	uint64	Identifier of the Company to which this object belongs.
billingProfile.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
hostingLicenses	Array.<BillableHostingLicense>	The list of BillableHostingLicenses.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"billingProfile": {
		"company": number,
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"hostingLicenses": [
		{
			"amount": number,
			"company": number,
			"end": string,
			"id": number,
			"kind": string,
			"limit": number,
			"name": string,
			"notes": string,
			"processedUtc": string,
			"profile": number,
			"reference": string,
			"sku": string,
			"start": string,
			"suspended": boolean,
			"targets": string,
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a billingProfile object, or it is invalid.
400	3	The billingProfile object does not contain an id, or it is invalid.
401	5	You do not have permission to view this Company's BillableHostingLicenses.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company was not found by its unique identifier. If you receive this error, please contact technical support.
404	111	The BillingProfile was not found by its unique identifier.

GET/billing/profiles/{profileId}/reports?includeDeleted=boolean&includeArchive=boolean&limit=number&after=string&before=string

Gets the list of BillingReports for the specified BillingProfile.

URL Parameters

Parameter	Type	Required	Description
after	datetime	optional	When using , sets the earliest objects (by dts) to retrieve from the archive.
before	datetime	optional	When using , sets the most recent objects (by dts) to retrieve from the archive.
includeArchive	boolean	optional	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	False by default, but when true, the command will also return deleted objects.
limit	uint16?	optional	When using , sets the maximum number of objects retrieved from the archive.
profileId	uint64	required	Unique identifier of the BillingProfile.

Response description

Property	Type	Description
billingProfile	RespIdCompany	An object to contain the "id" of the BillingProfile to which the array of BillableHostingRules belong.
billingProfile.company	uint64	Identifier of the Company to which this object belongs.
billingProfile.id	uint64?	Identifier given as input for the command.
billingReports	Array.<BillingReport>	The list of requested BillingReports.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"billingProfile": {
		"company": number,
		"id": number
	},
	"billingReports": [
		{
			"billee": number,
			"breakdown": [
				{
					"licenses": [
						{
							"billableDays": number,
							"cost": number,
							"created": string,
							"deleted": string,
							"firmware": string,
							"kind": string,
							"name": string,
							"notes": string,
							"phoneNumber": number,
							"provider": string,
							"total": number
						}
					],
					"services": [
						{
							"asset": number,
							"billableDays": number,
							"cost": number,
							"created": string,
							"deleted": string,
							"kind": string,
							"labels": [
								string
							],
							"name": string,
							"notes": string,
							"phoneNumbers": [
								number
							],
							"providers": [
								string
							],
							"restored": string,
							"revived": string,
							"suspended": string,
							"suspendedCost": number,
							"suspendedDays": number,
							"total": number,
							"updatedDts": string
						}
					],
					"target": number
				}
			],
			"company": number,
			"currency": string,
			"endDate": string,
			"error": string,
			"id": number,
			"name": string,
			"notes": string,
			"processedUtc": string,
			"profile": number,
			"startDate": string,
			"status": string,
			"summary": [
				{
					"hosting": [
						{
							"cost": number,
							"count": number,
							"sku": string,
							"total": number
						}
					],
					"name": string,
					"notes": string,
					"parent": number,
					"target": number
				}
			],
			"total": number,
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a billingProfile object, or it is invalid.
400	3	The billingProfile object does not contain an id, or it is invalid.
401	5	You do not have permission to view this Company's BillingReports.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company was not found by its unique identifier.
404	111	The BillingProfile was not found by its unique identifier.

PATCH/billing/profiles/{profileId}/restore

Restores the specified BillingProfile to its previous version.

URL Parameters

Parameter	Type	Required	Description
profileId	uint64	required	Unique identifier of the BillingProfile.

HTTP Request body description

Property	Type	Required	Description
billingProfile	ParamId	always	An object to contain the "id" of the BillingProfile.
billingProfile.id	uint64	always	Identifier given as input for the command.
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"billingProfile": {
		"id": number
	},
	"reqId": number
}

Response description

Property	Type	Description
billingProfile	RespDeleted	An object which contains the BillingProfile's unique identifier and deleted status.
billingProfile.company	uint64	Identifier of the Company to which this object belongs.
billingProfile.deleted	boolean	Flag showing if the object is deleted.
billingProfile.id	uint64?	Identifier given as input for the command.
billingProfile.v	Array.<uint32>
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"billingProfile": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a billingProfile object, or it is invalid.
400	3	The requested billingProfile id was invalid.
401	5	You do not have permission to restore BillingProfiles.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	111	The BillingProfile was not found by its unique identifier.
400	112	The BillingProfile was found, but is not marked as deleted.

GET/billing/profiles/{profileId}/rules?includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

Gets the list of BillableHostingRule for the specified BillingProfile.

URL Parameters

Parameter	Type	Required	Description
highest	uint64?	optional	When using , sets the largest valued id objects to retrieve.
includeArchive	boolean	optional	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	False by default, but when true, the command will also return deleted objects.
limit	uint16?	optional	When using , sets the maximum number of objects retrieved from the archive.
lowest	uint64?	optional	When using , sets the smallest valued id objects to retrieve.
profileId	uint64	required	Unique identifier of the BillingProfile.

Response description

Property	Type	Description
billingProfile	RespIdCompany	An object to contain the "id" of the BillingProfile to which the array of BillableHostingRules belong.
billingProfile.company	uint64	Identifier of the Company to which this object belongs.
billingProfile.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
hostingRules	Array.<BillableHostingRule>	The list of requested BillableHostingRules.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"billingProfile": {
		"company": number,
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"hostingRules": [
		{
			"amount": number,
			"company": number,
			"end": string,
			"id": number,
			"limit": number,
			"name": string,
			"notes": string,
			"processedUtc": string,
			"profile": number,
			"reference": string,
			"service": string,
			"sku": string,
			"start": string,
			"suspended": boolean,
			"targets": string,
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a billingProfile object, or it is invalid.
400	3	The billingProfile object does not contain an id, or it is invalid.
401	5	You do not have permission to view this Company's BillableHostingRules.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company was not found by its unique identifier. If you receive this error, please contact technical support.
404	111	The BillingProfile was not found by its unique identifier.

PATCH/billing/profiles/licenses

Creates new or updates an existing BillableHostingLicense.

HTTP Request body description

Property	Type	Required	Description
hostingLicense	Object.<string, ?>	always	A simple object to contain the BillableHostingLicense parameters.
hostingLicense.amount	double?	optional	Cost per cycle for this plan
hostingLicense.end	datetime	optional	Date this BillableHostingLicense is applied until; null means it never ends.
hostingLicense.id	uint64?	update	Unique identifier of the BillableHostingLicense you want to update.
hostingLicense.kind	BillableLicenseType?	create	The type of hardware BillableLicenseType.
hostingLicense.limit	uint32?	optional	The number of units to which this BillableHostingLicense applies. Should be a non-zero value; null means unlimited
hostingLicense.name	string	create	Name for the BillableHostingLicense
hostingLicense.notes	string	optional	Notes about the BillableHostingLicense.
hostingLicense.profile	uint64?	create	Unique identifier of this BillableHostingLicense's BillingProfile.
hostingLicense.reference	string	optional	A custom field used to refer to an external system. Examples are a cost codes, SOCs, discount plans...
hostingLicense.start	datetime	optional	Date this BillableHostingLicense takes effect.
hostingLicense.suspended	boolean	optional	Does this BillableHostingLicense apply to suspended resources
hostingLicense.targets	expression	optional	Which assets are targetted by this BillableHostingLicense
hostingLicense.v	Array.<int32>	optional
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"hostingLicense": {
		"amount": number,
		"end": string,
		"id": number,
		"kind": string,
		"limit": number,
		"name": string,
		"notes": string,
		"profile": number,
		"reference": string,
		"start": string,
		"suspended": boolean,
		"targets": string,
		"v": [
			number
		]
	},
	"reqId": number
}

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
hostingLicense	RespIdBillingProfile	An object which contains the "id", "company", and "profile" keys.
hostingLicense.company	uint64	Identifier of the Company to which this object belongs.
hostingLicense.id	uint64?	Identifier given as input for the command.
hostingLicense.profile	uint64	Identifier of the BillingProfile to which this object belongs
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"hostingLicense": {
		"company": number,
		"id": number,
		"profile": number
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a hostingLicense object, or it is invalid.
400	3	Not enough keys exist in the hostingLicense object.
400	3	During create: When creating a new BillableHostingLicense, start date is invalid.
400	3	During create: When creating a new BillableHostingLicense, end date is invalid.
400	3	During create: When creating a new BillableHostingLicense, kind is invalid.
400	3	During create: When creating a new BillableHostingLicense, a name was not given, or it is invalid.
400	3	During create: When creating a new BillableHostingLicense, profile is invalid.
400	3	During update: When updating a BillableHostingLicense, the name was invalid.
400	3	During update: When updating a BillableHostingLicense, the v was invalid.
401	5	During create: You do not have permission to create new BillableHostingLicenses.
401	5	During update: You do not have permission to update BillableHostingLicenses.
400	6	During update: When updating a BillableHostingLicense, the v was not an array, or contained too few numbers.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	111	The BillingProfile was not found by its unique identifier. If you receive this error, please contact technical support.
404	117	During update: The BillableHostingLicense was not found by its unique identifier.
409	130	During update: When updating a BillableHostingLicense, the hostingLicense.profile can not be changed.

DELETE/billing/profiles/licenses

Deletes an existing BillableHostingLicense.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
hostingLicense	RespDeleted	An object which contains the BillableHostingLicense's unique identifier and deleted status.
hostingLicense.company	uint64	Identifier of the Company to which this object belongs.
hostingLicense.deleted	boolean	Flag showing if the object is deleted.
hostingLicense.id	uint64?	Identifier given as input for the command.
hostingLicense.v	Array.<uint32>
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"hostingLicense": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred, the BillableHostingLicense was not deleted. If you receive this error, please contact technical support.
400	3	The request does not contain a hostingLicense object, or it is invalid.
400	3	The requested hostingLicense id was invalid.
401	5	You do not have permission to delete this Company's BillableHostingLicenses.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	117	The BillableHostingLicense was not found by its unique identifier.

GET/billing/profiles/licenses/{licenseId}?includeDeleted=boolean

Gets details of the specified BillableHostingLicense.

URL Parameters

Parameter	Type	Required	Description
includeDeleted	boolean	optional	False by default, but when true the command will also return deleted objects.
licenseId	uint64	required	Unique identifier of the BillableHostingLicense.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
hostingLicense	BillableHostingLicense	The requested BillableHostingLicense.
hostingLicense.amount	double	Cost per cycle for this plan
hostingLicense.company	uint64 see: Company.id	Unique identifier of the Company that owns this hosting rule.
hostingLicense.end	datetime	Date this billing rule is applied until; null means it never ends. These dates are used to determine how much of the cycle is billed.
hostingLicense.id	uint64	Unique identifier of this hosting rule.
hostingLicense.kind	BillableLicenseType	The type of hardware license
hostingLicense.limit	uint32?	The number of units to which this billing rule applies. Should be a non-zero value; null means unlimited
hostingLicense.name	string maximum-length: 254	The name of this billing rule.
hostingLicense.notes	string	Notes about billing this rule.
hostingLicense.processedUtc	datetime	When the was change procesed.
hostingLicense.profile	uint64 see: BillingProfile.id	Unique identifier of this rule's billing profile.
hostingLicense.reference	string maximum-length: 100	A custom field used to refer to an external system. Examples are a cost codes, SOCs, discount plans...
hostingLicense.sku	string maximum-length: 20	SKU or SOC code
hostingLicense.start	datetime	Date this billing rule takes effect. These dates are used to determine how much of the cycle is billed.
hostingLicense.suspended	boolean	Does this hosting rule apply to suspended resources
hostingLicense.targets	expression	Which assets are targeted by this hosting rule
hostingLicense.updated		by: login, from: monster
hostingLicense.v	Array.<uint32>	Object version keys used to validate synchronization for all object properties.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"hostingLicense": {
		"amount": number,
		"company": number,
		"end": string,
		"id": number,
		"kind": string,
		"limit": number,
		"name": string,
		"notes": string,
		"processedUtc": string,
		"profile": number,
		"reference": string,
		"sku": string,
		"start": string,
		"suspended": boolean,
		"targets": string,
		"updated": {
		},
		"v": [
			number
		]
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a hostingLicense object, or it is invalid.
400	3	The requested hostingLicense id was invalid.
401	5	You do not have permission to view this Company's BillableHostingLicenses.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	117	The BillableHostingLicense was not found by its unique identifier.

POST/billing/profiles/licenses/{licenseId}

Creates new or updates an existing BillableHostingLicense.

URL Parameters

Parameter	Type	Required	Description
licenseId	uint64?	optional	Unique identifier of the BillableHostingLicense. This value is optional, and ignored by the command.

HTTP Request body description

Property	Type	Required	Description
hostingLicense	Object.<string, ?>	always	A simple object to contain the BillableHostingLicense parameters.
hostingLicense.amount	double?	optional	Cost per cycle for this plan
hostingLicense.end	datetime	optional	Date this BillableHostingLicense is applied until; null means it never ends.
hostingLicense.id	uint64?	update	Unique identifier of the BillableHostingLicense you want to update.
hostingLicense.kind	BillableLicenseType?	create	The type of hardware BillableLicenseType.
hostingLicense.limit	uint32?	optional	The number of units to which this BillableHostingLicense applies. Should be a non-zero value; null means unlimited
hostingLicense.name	string	create	Name for the BillableHostingLicense
hostingLicense.notes	string	optional	Notes about the BillableHostingLicense.
hostingLicense.profile	uint64?	create	Unique identifier of this BillableHostingLicense's BillingProfile.
hostingLicense.reference	string	optional	A custom field used to refer to an external system. Examples are a cost codes, SOCs, discount plans...
hostingLicense.start	datetime	optional	Date this BillableHostingLicense takes effect.
hostingLicense.suspended	boolean	optional	Does this BillableHostingLicense apply to suspended resources
hostingLicense.targets	expression	optional	Which assets are targetted by this BillableHostingLicense
hostingLicense.v	Array.<int32>	optional
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"hostingLicense": {
		"amount": number,
		"end": string,
		"id": number,
		"kind": string,
		"limit": number,
		"name": string,
		"notes": string,
		"profile": number,
		"reference": string,
		"start": string,
		"suspended": boolean,
		"targets": string,
		"v": [
			number
		]
	},
	"reqId": number
}

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
hostingLicense	RespIdBillingProfile	An object which contains the "id", "company", and "profile" keys.
hostingLicense.company	uint64	Identifier of the Company to which this object belongs.
hostingLicense.id	uint64?	Identifier given as input for the command.
hostingLicense.profile	uint64	Identifier of the BillingProfile to which this object belongs
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"hostingLicense": {
		"company": number,
		"id": number,
		"profile": number
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a hostingLicense object, or it is invalid.
400	3	Not enough keys exist in the hostingLicense object.
400	3	During create: When creating a new BillableHostingLicense, start date is invalid.
400	3	During create: When creating a new BillableHostingLicense, end date is invalid.
400	3	During create: When creating a new BillableHostingLicense, kind is invalid.
400	3	During create: When creating a new BillableHostingLicense, a name was not given, or it is invalid.
400	3	During create: When creating a new BillableHostingLicense, profile is invalid.
400	3	During update: When updating a BillableHostingLicense, the name was invalid.
400	3	During update: When updating a BillableHostingLicense, the v was invalid.
401	5	During create: You do not have permission to create new BillableHostingLicenses.
401	5	During update: You do not have permission to update BillableHostingLicenses.
400	6	During update: When updating a BillableHostingLicense, the v was not an array, or contained too few numbers.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	111	The BillingProfile was not found by its unique identifier. If you receive this error, please contact technical support.
404	117	During update: The BillableHostingLicense was not found by its unique identifier.
409	130	During update: When updating a BillableHostingLicense, the hostingLicense.profile can not be changed.

DELETE/billing/profiles/licenses/{licenseId}

Deletes an existing BillableHostingLicense.

URL Parameters

Parameter	Type	Required	Description
licenseId	uint64	required	Unique identifier of the BillableHostingLicense.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
hostingLicense	RespDeleted	An object which contains the BillableHostingLicense's unique identifier and deleted status.
hostingLicense.company	uint64	Identifier of the Company to which this object belongs.
hostingLicense.deleted	boolean	Flag showing if the object is deleted.
hostingLicense.id	uint64?	Identifier given as input for the command.
hostingLicense.v	Array.<uint32>
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"hostingLicense": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred, the BillableHostingLicense was not deleted. If you receive this error, please contact technical support.
400	3	The request does not contain a hostingLicense object, or it is invalid.
400	3	The requested hostingLicense id was invalid.
401	5	You do not have permission to delete this Company's BillableHostingLicenses.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	117	The BillableHostingLicense was not found by its unique identifier.

PATCH/billing/profiles/licenses/{licenseId}/restore

Restores the specified BillableHostingLicense to its previous version.

URL Parameters

Parameter	Type	Required	Description
licenseId	uint64	required	Unique identifier of the BillableHostingLicense.

HTTP Request body description

Property	Type	Required	Description
hostingLicense	ParamId	always	An object to contain the "id" of the BillableHostingLicense.
hostingLicense.id	uint64	always	Identifier given as input for the command.
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"hostingLicense": {
		"id": number
	},
	"reqId": number
}

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
hostingLicense	RespDeleted	An object which contains the BillableHostingLicense's unique identifier and deleted status.
hostingLicense.company	uint64	Identifier of the Company to which this object belongs.
hostingLicense.deleted	boolean	Flag showing if the object is deleted.
hostingLicense.id	uint64?	Identifier given as input for the command.
hostingLicense.v	Array.<uint32>
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"hostingLicense": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a hostingLicense object, or it is invalid.
400	3	The requested hostingLicense id was invalid.
401	5	You do not have permission to delete BillableHostingLicenses.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	117	The BillableHostingLicense was not found by its unique identifier.
400	118	The BillableHostingLicense was found, but is not marked as deleted.

GET/billing/profiles/reports?includeDeleted=boolean&includeArchive=boolean&limit=number&after=string&before=string

This request is an alias of /companies/{your-company-id}/billing/profiles/reports.

URL Parameters

Parameter	Type	Required	Default	Description
after	datetime	optional		When using , sets the earliest objects (by dts) to retrieve from the archive.
before	datetime	optional		When using , sets the most recent objects (by dts) to retrieve from the archive.
includeArchive	boolean	optional	`false`	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	`false`	False by default, but when true the command will also return deleted objects.
limit	uint16	optional		When using , sets the maximum number of objects retrieved from the archive.
your-company-id	uint64	aliased	`{your-company-id}`	Your own Company's identifier.

DELETE/billing/profiles/reports

Deletes an existing BillingReport.

Response description

Property	Type	Description
billingReport	RespDeleted	An object which contains the BillingReport's unique identifier and deleted status.
billingReport.company	uint64	Identifier of the Company to which this object belongs.
billingReport.deleted	boolean	Flag showing if the object is deleted.
billingReport.id	uint64?	Identifier given as input for the command.
billingReport.v	Array.<uint32>
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"billingReport": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred, the BillingReport was not deleted. If you receive this error, please contact technical support.
400	3	The request does not contain a billingReport object, or it is invalid.
400	3	The requested billingReport id was invalid.
401	5	You do not have permission to delete this Company's BillingReports.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	119	The BillingReport was not found by its unique identifier.

GET/billing/profiles/reports/{reportId}?includeDeleted=boolean

Gets details of the specified BillingReport.

URL Parameters

Parameter	Type	Required	Description
includeDeleted	boolean	optional	False by default, but when true the command will also return deleted objects.
reportId	uint64	required	Unique identifier of the BillingReport.

Response description

Property	Type	Description
billingReport	BillingReport	The requested BillingReport.
billingReport.billee	uint64 see: Company.id	Unique identifier of the Company receiving the bill.
billingReport.breakdown	Array.<BillingReportBreakdown>	Individual amounts per company, used to calculate the results of the report.
billingReport.company	uint64 see: Company.id	The company to which this report belongs and is sending the bill.
billingReport.currency	BillingCurrency	Currency being billed in
billingReport.endDate	datetime	Last day of the billing cycle
billingReport.error	string see: BillingReportStatus maximum-length: 250	A field which contains report error details if the BillingReport.status is BillingReportStatus.failed.
billingReport.id	uint64	Unique identifier
billingReport.name	string maximum-length: 100	Name of this report.
billingReport.notes	string	Notes about this report.
billingReport.processedUtc	datetime	When the was change procesed.
billingReport.profile	uint64 see: BillingProfile.id	The profile to which this report belongs
billingReport.startDate	datetime	First day of the billing cycle
billingReport.status	BillingReportStatus	The processing status of this report.
billingReport.summary	Array.<BillingReportSummary>	Summary contains totals per target for this billee
billingReport.total	double	Total amount being billed.
billingReport.updated		by: login, from: monster
billingReport.v	Array.<uint32>	Object version keys used to validate synchronization for all object properties.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"billingReport": {
		"billee": number,
		"breakdown": [
			{
				"licenses": [
					{
						"billableDays": number,
						"cost": number,
						"created": string,
						"deleted": string,
						"firmware": string,
						"kind": string,
						"name": string,
						"notes": string,
						"phoneNumber": number,
						"provider": string,
						"total": number
					}
				],
				"services": [
					{
						"asset": number,
						"billableDays": number,
						"cost": number,
						"created": string,
						"deleted": string,
						"kind": string,
						"labels": [
							string
						],
						"name": string,
						"notes": string,
						"phoneNumbers": [
							number
						],
						"providers": [
							string
						],
						"restored": string,
						"revived": string,
						"suspended": string,
						"suspendedCost": number,
						"suspendedDays": number,
						"total": number,
						"updatedDts": string
					}
				],
				"target": number
			}
		],
		"company": number,
		"currency": string,
		"endDate": string,
		"error": string,
		"id": number,
		"name": string,
		"notes": string,
		"processedUtc": string,
		"profile": number,
		"startDate": string,
		"status": string,
		"summary": [
			{
				"hosting": [
					{
						"cost": number,
						"count": number,
						"sku": string,
						"total": number
					}
				],
				"name": string,
				"notes": string,
				"parent": number,
				"target": number
			}
		],
		"total": number,
		"updated": {
		},
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a billingReport object, or it is invalid.
400	3	The requested billingReport id was invalid.
401	5	You do not have permission to view this Company's BillingReports.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	119	The BillingReport was not found by its unique identifier.

DELETE/billing/profiles/reports/{reportId}

Deletes an existing BillingReport.

URL Parameters

Parameter	Type	Required	Description
reportId	uint64	required	Unique identifier of the BillingReport.

Response description

Property	Type	Description
billingReport	RespDeleted	An object which contains the BillingReport's unique identifier and deleted status.
billingReport.company	uint64	Identifier of the Company to which this object belongs.
billingReport.deleted	boolean	Flag showing if the object is deleted.
billingReport.id	uint64?	Identifier given as input for the command.
billingReport.v	Array.<uint32>
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"billingReport": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred, the BillingReport was not deleted. If you receive this error, please contact technical support.
400	3	The request does not contain a billingReport object, or it is invalid.
400	3	The requested billingReport id was invalid.
401	5	You do not have permission to delete this Company's BillingReports.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	119	The BillingReport was not found by its unique identifier.

PATCH/billing/profiles/reports/{reportId}/restore

Restores the specified BillingReport to its previous version.

URL Parameters

Parameter	Type	Required	Description
reportId	uint64	required	Unique identifier of the BillingReport.

HTTP Request body description

Property	Type	Required	Description
billingReport	ParamId	always	An object to contain the "id" of the BillingReport.
billingReport.id	uint64	always	Identifier given as input for the command.
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"billingReport": {
		"id": number
	},
	"reqId": number
}

Response description

Property	Type	Description
billingReport	RespDeleted	An object which contains the BillingReport's unique identifier and deleted status.
billingReport.company	uint64	Identifier of the Company to which this object belongs.
billingReport.deleted	boolean	Flag showing if the object is deleted.
billingReport.id	uint64?	Identifier given as input for the command.
billingReport.v	Array.<uint32>
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"billingReport": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a billingReport object, or it is invalid.
400	3	The requested billingReport id was invalid.
401	5	You do not have permission to restore BillingReports.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	119	The BillingReport was not found by its unique identifier.
400	120	The BillingReport was found, but is not marked as deleted.

PATCH/billing/profiles/rules

Creates new or updates an existing BillableHostingRule.

HTTP Request body description

Property	Type	Required	Description
hostingRule	Object.<string, ?>	always	A simple object to contain the BillableHostingRule parameters.
hostingRule.amount	double?	optional	Cost per cycle for this plan
hostingRule.end	datetime	create	Date this BillableHostingRule is applied until; null means it never ends.
hostingRule.id	uint64?	update	Unique identifier of the BillableHostingRule you want to update.
hostingRule.limit	uint32?	optional	The number of units to which this BillableHostingRule applies. Should be a non-zero value; null means unlimited
hostingRule.name	string	create	Name for the BillableHostingRule
hostingRule.notes	string	optional	Notes about the BillableHostingRule.
hostingRule.profile	uint64?	create	Unique identifier of this BillableHostingRule's BillingProfile.
hostingRule.reference	string	optional	A custom field used to refer to an external system. Examples are a cost codes, SOCs, discount plans...
hostingRule.service	BillableHostingType?	create	The type of service being billed.
hostingRule.start	datetime	create	Date this BillableHostingRule takes effect.
hostingRule.suspended	boolean	optional	Does this BillableHostingRule apply to suspended resources
hostingRule.targets	expression	optional	Which assets are targetted by this BillableHostingRule
hostingRule.v	Array.<int32>	optional
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"hostingRule": {
		"amount": number,
		"end": string,
		"id": number,
		"limit": number,
		"name": string,
		"notes": string,
		"profile": number,
		"reference": string,
		"service": string,
		"start": string,
		"suspended": boolean,
		"targets": string,
		"v": [
			number
		]
	},
	"reqId": number
}

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
hostingRule	RespIdBillingProfile	An object which contains the "id", "company", and "profile" keys.
hostingRule.company	uint64	Identifier of the Company to which this object belongs.
hostingRule.id	uint64?	Identifier given as input for the command.
hostingRule.profile	uint64	Identifier of the BillingProfile to which this object belongs
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"hostingRule": {
		"company": number,
		"id": number,
		"profile": number
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a hostingRule object, or it is invalid.
400	3	Not enough keys exist in the hostingRule object.
400	3	During create: When creating a new BillableHostingRule, start date is invalid.
400	3	During create: When creating a new BillableHostingRule, end date is invalid.
400	3	During create: When creating a new BillableHostingRule, a name was not given, or it is invalid.
400	3	During create: When creating a new BillableHostingRule, profile is invalid.
400	3	During create: When creating a new BillableHostingRule, service is invalid.
400	3	During update: When updating a BillableHostingRule, the name was invalid.
400	3	During update: When updating a BillableHostingRule, the v was invalid.
401	5	During create: You do not have permission to create new BillableHostingRules.
401	5	During update: You do not have permission to update BillableHostingRules.
400	6	During update: When updating a BillableHostingRule, the v was not an array, or contained too few numbers.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	111	The BillingProfile was not found by its unique identifier. If you receive this error, please contact technical support.
404	113	During update: The BillableHostingRule was not found by its unique identifier.
409	130	During update: When updating a BillableHostingRule, the hostingRule.profile can not be changed.

DELETE/billing/profiles/rules

Deletes an existing BillableHostingRule.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
hostingRule	RespDeleted	An object which contains the BillableHostingRule's unique identifier and deleted status.
hostingRule.company	uint64	Identifier of the Company to which this object belongs.
hostingRule.deleted	boolean	Flag showing if the object is deleted.
hostingRule.id	uint64?	Identifier given as input for the command.
hostingRule.v	Array.<uint32>
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"hostingRule": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred, the BillableHostingRule was not deleted. If you receive this error, please contact technical support.
400	3	The request does not contain a hostingRule object, or it is invalid.
400	3	The requested hostingRule id was invalid.
401	5	You do not have permission to delete this Company's BillableHostingRules.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	113	The BillableHostingRule was not found by its unique identifier.

GET/billing/profiles/rules/{ruleId}?includeDeleted=boolean

Gets details of the specified BillableHostingRule.

URL Parameters

Parameter	Type	Required	Description
includeDeleted	boolean	optional	False by default, but when true the command will also return deleted objects.
ruleId	uint64	required	Unique identifier of the BillableHostingRule.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
hostingRule	BillableHostingRule	The requested BillableHostingRule.
hostingRule.amount	double	Cost per cycle for this plan
hostingRule.company	uint64 see: Company.id	Unique identifier of the Company that owns this hosting rule.
hostingRule.end	datetime	Date this billing rule is applied until; null means it never ends. These dates are used to determine how much of the cycle is billed.
hostingRule.id	uint64	Unique identifier of this hosting rule.
hostingRule.limit	uint32?	The number of units to which this billing rule applies. Should be a non-zero value; null means unlimited
hostingRule.name	string maximum-length: 254	The name of this billing rule.
hostingRule.notes	string	Notes about billing this rule.
hostingRule.processedUtc	datetime	When the was change procesed.
hostingRule.profile	uint64 see: BillingProfile.id	Unique identifier of this rule's billing profile.
hostingRule.reference	string maximum-length: 100	A custom field used to refer to an external system. Examples are a cost codes, SOCs, discount plans...
hostingRule.service	BillableHostingType	The type of service being billed.
hostingRule.sku	string maximum-length: 20	SKU or SOC code
hostingRule.start	datetime	Date this billing rule takes effect. These dates are used to determine how much of the cycle is billed.
hostingRule.suspended	boolean	Does this hosting rule apply to suspended resources
hostingRule.targets	expression	Which assets are targeted by this hosting rule
hostingRule.updated		by: login, from: monster
hostingRule.v	Array.<uint32>	Object version keys used to validate synchronization for all object properties.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"hostingRule": {
		"amount": number,
		"company": number,
		"end": string,
		"id": number,
		"limit": number,
		"name": string,
		"notes": string,
		"processedUtc": string,
		"profile": number,
		"reference": string,
		"service": string,
		"sku": string,
		"start": string,
		"suspended": boolean,
		"targets": string,
		"updated": {
		},
		"v": [
			number
		]
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a hostingRule object, or it is invalid.
400	3	The requested hostingRule id was invalid.
401	5	You do not have permission to view this Company's BillableHostingRules.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	113	The BillableHostingRule was not found by its unique identifier.

POST/billing/profiles/rules/{ruleId}

Creates new or updates an existing BillableHostingRule.

URL Parameters

Parameter	Type	Required	Description
ruleId	uint64?	optional	Unique identifier of the BillableHostingRule. This value is optional, and ignored by the command.

HTTP Request body description

Property	Type	Required	Description
hostingRule	Object.<string, ?>	always	A simple object to contain the BillableHostingRule parameters.
hostingRule.amount	double?	optional	Cost per cycle for this plan
hostingRule.end	datetime	create	Date this BillableHostingRule is applied until; null means it never ends.
hostingRule.id	uint64?	update	Unique identifier of the BillableHostingRule you want to update.
hostingRule.limit	uint32?	optional	The number of units to which this BillableHostingRule applies. Should be a non-zero value; null means unlimited
hostingRule.name	string	create	Name for the BillableHostingRule
hostingRule.notes	string	optional	Notes about the BillableHostingRule.
hostingRule.profile	uint64?	create	Unique identifier of this BillableHostingRule's BillingProfile.
hostingRule.reference	string	optional	A custom field used to refer to an external system. Examples are a cost codes, SOCs, discount plans...
hostingRule.service	BillableHostingType?	create	The type of service being billed.
hostingRule.start	datetime	create	Date this BillableHostingRule takes effect.
hostingRule.suspended	boolean	optional	Does this BillableHostingRule apply to suspended resources
hostingRule.targets	expression	optional	Which assets are targetted by this BillableHostingRule
hostingRule.v	Array.<int32>	optional
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"hostingRule": {
		"amount": number,
		"end": string,
		"id": number,
		"limit": number,
		"name": string,
		"notes": string,
		"profile": number,
		"reference": string,
		"service": string,
		"start": string,
		"suspended": boolean,
		"targets": string,
		"v": [
			number
		]
	},
	"reqId": number
}

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
hostingRule	RespIdBillingProfile	An object which contains the "id", "company", and "profile" keys.
hostingRule.company	uint64	Identifier of the Company to which this object belongs.
hostingRule.id	uint64?	Identifier given as input for the command.
hostingRule.profile	uint64	Identifier of the BillingProfile to which this object belongs
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"hostingRule": {
		"company": number,
		"id": number,
		"profile": number
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a hostingRule object, or it is invalid.
400	3	Not enough keys exist in the hostingRule object.
400	3	During create: When creating a new BillableHostingRule, start date is invalid.
400	3	During create: When creating a new BillableHostingRule, end date is invalid.
400	3	During create: When creating a new BillableHostingRule, a name was not given, or it is invalid.
400	3	During create: When creating a new BillableHostingRule, profile is invalid.
400	3	During create: When creating a new BillableHostingRule, service is invalid.
400	3	During update: When updating a BillableHostingRule, the name was invalid.
400	3	During update: When updating a BillableHostingRule, the v was invalid.
401	5	During create: You do not have permission to create new BillableHostingRules.
401	5	During update: You do not have permission to update BillableHostingRules.
400	6	During update: When updating a BillableHostingRule, the v was not an array, or contained too few numbers.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	111	The BillingProfile was not found by its unique identifier. If you receive this error, please contact technical support.
404	113	During update: The BillableHostingRule was not found by its unique identifier.
409	130	During update: When updating a BillableHostingRule, the hostingRule.profile can not be changed.

DELETE/billing/profiles/rules/{ruleId}

Deletes an existing BillableHostingRule.

URL Parameters

Parameter	Type	Required	Description
ruleId	uint64	required	Unique identifier of the BillableHostingRule.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
hostingRule	RespDeleted	An object which contains the BillableHostingRule's unique identifier and deleted status.
hostingRule.company	uint64	Identifier of the Company to which this object belongs.
hostingRule.deleted	boolean	Flag showing if the object is deleted.
hostingRule.id	uint64?	Identifier given as input for the command.
hostingRule.v	Array.<uint32>
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"hostingRule": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred, the BillableHostingRule was not deleted. If you receive this error, please contact technical support.
400	3	The request does not contain a hostingRule object, or it is invalid.
400	3	The requested hostingRule id was invalid.
401	5	You do not have permission to delete this Company's BillableHostingRules.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	113	The BillableHostingRule was not found by its unique identifier.

PATCH/billing/profiles/rules/{ruleId}/restore

Restores the specified BillableHostingRule to its previous version.

URL Parameters

Parameter	Type	Required	Description
ruleId	uint64	required	Unique identifier of the BillableHostingRule.

HTTP Request body description

Property	Type	Required	Description
hostingRule	ParamId	always	An object to contain the "id" of the BillableHostingRule.
hostingRule.id	uint64	always	Identifier given as input for the command.
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"hostingRule": {
		"id": number
	},
	"reqId": number
}

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
hostingRule	RespDeleted	An object which contains the BillableHostingRule's unique identifier and deleted status.
hostingRule.company	uint64	Identifier of the Company to which this object belongs.
hostingRule.deleted	boolean	Flag showing if the object is deleted.
hostingRule.id	uint64?	Identifier given as input for the command.
hostingRule.v	Array.<uint32>
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"hostingRule": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a hostingRule object, or it is invalid.
400	3	The requested hostingRule id was invalid.
401	5	You do not have permission to restore BillableHostingRules.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	113	The BillableHostingRule was not found by its unique identifier.
400	114	The BillableHostingRule was found, but is not marked as deleted.

GET/companies/{companyId}/billing/profiles?includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

Gets the list of BillingProfiles for the specified Company.

URL Parameters

Parameter	Type	Required	Description
companyId	uint64	required	Unique identifier of the Company.
highest	uint64?	optional	When using , sets the largest valued id objects to retrieve.
includeArchive	boolean	optional	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	False by default, but when true, the command will also return deleted objects.
limit	uint16?	optional	When using , sets the maximum number of objects retrieved from the archive.
lowest	uint64?	optional	When using , sets the smallest valued id objects to retrieve.

Response description

Property	Type	Description
billingProfiles	Array.<BillingProfile>	The list of requested BillingProfiles.
company	RespId	An object to contain the "id" of the Company to which the array of BillingProfiles belong.
company.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"billingProfiles": [
		{
			"billee": number,
			"company": number,
			"currency": string,
			"cycle": string,
			"cycleEnd": string,
			"cyclePostDated": boolean,
			"cycleStart": string,
			"googleServicesEnabled": boolean,
			"id": number,
			"messages": [
				{
					"amount": number,
					"limit": number
				}
			],
			"name": string,
			"notes": string,
			"processedUtc": string,
			"target": number,
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
401	5	You do not have permission to view this Company's BillingProfiles.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company was not found by its unique identifier.

GET/companies/{companyId}/billing/profiles/reports?includeDeleted=boolean&includeArchive=boolean&limit=number&after=string&before=string

Gets the list of BillingReports for the specified Company.

URL Parameters

Parameter	Type	Required	Description
after	datetime	optional	When using , sets the earliest objects (by dts) to retrieve from the archive.
before	datetime	optional	When using , sets the most recent objects (by dts) to retrieve from the archive.
companyId	uint64	required	Unique identifier of the Company.
includeArchive	boolean	optional	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	False by default, but when true, the command will also return deleted objects.
limit	uint16?	optional	When using , sets the maximum number of objects retrieved from the archive.

Response description

Property	Type	Description
billingReports	Array.<BillingReport>	The list of requested BillingReports.
company	RespId	An object to contain the "id" of the Company to which the array of BillingReports belong.
company.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"billingReports": [
		{
			"billee": number,
			"breakdown": [
				{
					"licenses": [
						{
							"billableDays": number,
							"cost": number,
							"created": string,
							"deleted": string,
							"firmware": string,
							"kind": string,
							"name": string,
							"notes": string,
							"phoneNumber": number,
							"provider": string,
							"total": number
						}
					],
					"services": [
						{
							"asset": number,
							"billableDays": number,
							"cost": number,
							"created": string,
							"deleted": string,
							"kind": string,
							"labels": [
								string
							],
							"name": string,
							"notes": string,
							"phoneNumbers": [
								number
							],
							"providers": [
								string
							],
							"restored": string,
							"revived": string,
							"suspended": string,
							"suspendedCost": number,
							"suspendedDays": number,
							"total": number,
							"updatedDts": string
						}
					],
					"target": number
				}
			],
			"company": number,
			"currency": string,
			"endDate": string,
			"error": string,
			"id": number,
			"name": string,
			"notes": string,
			"processedUtc": string,
			"profile": number,
			"startDate": string,
			"status": string,
			"summary": [
				{
					"hosting": [
						{
							"cost": number,
							"count": number,
							"sku": string,
							"total": number
						}
					],
					"name": string,
					"notes": string,
					"parent": number,
					"target": number
				}
			],
			"total": number,
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
401	5	You do not have permission to view this Company's BillingReports.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company was not found by its unique identifier.

Companies

GET/companies?parent=number&tree=boolean&includeParent=boolean&includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

Gets the list of child-companies for the specified Company. By default the full tree of companies is returned, but this can be overridden using tree. By default it does not include the parent Company, but this can be overridden using includeParent.

URL Parameters

Parameter	Type	Required	Default	Description
highest	uint64?	optional		When using , sets the largest valued id objects to retrieve.
includeArchive	boolean	optional		Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional		False by default, but when true, the command will also return deleted objects.
includeParent	boolean	optional	`true`	When set to true (default), the parent Company is included in the results.
limit	uint16?	optional		When using , sets the maximum number of objects retrieved from the archive.
lowest	uint64?	optional		When using , sets the smallest valued id objects to retrieve.
parent	uint64?	optional	`{your-company-id}`	Unique identifier of the Company.
tree	boolean	optional	`true`	When set to true, the full tree of companies is returned. Otherwise, only the first-level child-companies are included.

Response description

Property	Type	Description
companies	Array.<CompanyGeneral>	The list of requested companies.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"companies": [
		{
			"id": number,
			"name": string,
			"notes": string,
			"parent": number,
			"processedUtc": string,
			"references": {
				string: string
			},
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
401	5	You do not have permission to view this Company or child companies.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company was not found by its unique identifier.

GET/companies?{keys=values}?parent=number&tree=boolean&includeParent=boolean&includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number&{keys=values}

Gets the list of companies only if one of the specified Company.references fields match. If no references are specified, it will match any Company with no references. If a reference value is null, it will match any Company without that reference key. By default the full tree of companies is returned, but this can be overridden using tree. By default it does not include the parent Company, but this can be overridden using includeParent.

URL Parameters

Parameter	Type	Required	Default	Description
highest	uint64?	optional		When using , sets the largest valued id objects to retrieve.
includeArchive	boolean	optional		Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional		False by default, but when true, the command will also return deleted objects.
includeParent	boolean	optional	`true`	When set to true (default), the parent Company is included in the results.
limit	uint16?	optional		When using , sets the maximum number of objects retrieved from the archive.
lowest	uint64?	optional		When using , sets the smallest valued id objects to retrieve.
parent	uint64?	optional	`{your-company-id}`	Unique identifier of the Company.
tree	boolean	optional	`true`	When set to true, the full tree of companies is returned. Otherwise, only the first-level child-companies are included.

Response description

Property	Type	Description
companies	Array.<CompanyGeneral>	The list of requested companies.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
references	Object.<string, string>	The reference string given as input.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"companies": [
		{
			"id": number,
			"name": string,
			"notes": string,
			"parent": number,
			"processedUtc": string,
			"references": {
				string: string
			},
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"references": {
		string: string
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
400	3	The references is not an object, or it is invalid.
401	5	You do not have permission to view this Company or child companies.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company was not found by its unique identifier.

PATCH/companies

Creates a new or updates an existing Company.

HTTP Request body description

Property	Type	Required	Description
company	Object.<string, ?>	always	A simple object to contain the company parameters.
company.directory	Object.<string, Array.<uint64>> for value-values see: Contact.id	optional	The list of Contacts from this and other companies broken down by contact role.
company.id	uint64?	update	Unique identifier of the Company.
company.labels	Object.<string, LabelStyle>	optional	The styles for labels added to Assets, Places, and other things.
company.name	string maximum-length: 100	create	The organizational name.
company.notes	string	optional	Notes.
company.parent	uint64?	create	The unique identifier of this company's parent organization.
company.passwordPolicy	Object.<string, ?>	always	The password complexity and expiry policy.
company.passwordPolicy.expireMode	PasswordExpiryMode?	optional	Defines how passwords expire.
company.passwordPolicy.expireThreshold	byte?	optional	The threshold for expiry (in days).
company.passwordPolicy.includeLetters	boolean	optional	Do passwords require alphabetical characters.
company.passwordPolicy.includeNumbers	boolean	optional	Do passwords require numeric characters.
company.passwordPolicy.includeSpecial	boolean	optional	Do passwords require non-alphanumeric characters.
company.passwordPolicy.includeUpperLower	boolean	optional	Do passwords require upper-case and lower-case letters.
company.passwordPolicy.minimumLength	byte?	optional	The minimum number of characters required.
company.references	Object.<string, string>	optional	Name/value collections of custom fields used to refer to external systems. If the value is null, the references are removed from the Company.
company.sessionPolicy	Object.<string, ?>	always	The session lifetime policy.
company.sessionPolicy.applications	Array.<string>	optional	The list of applications users are allowed to use to create sessions.
company.sessionPolicy.expireTimeout	uint16?	optional	The lifetime duration of a session in minutes.
company.sessionPolicy.idleAllowed	boolean	optional	Defines whether a session should be automatically killed when the connection breaks.
company.sessionPolicy.ipv4Ranges	Array.<ipv4> maximum-length of values: 19	optional	Restrict session creation to only the provided IPv4 ranges (using CIDR slash-notation). Leave blank for Internet access.
company.sessionPolicy.maxSessions	byte?	optional	The maximum number of sessions allowed per user.
company.sessionPolicy.multiUser	SessionMultiUser?	optional	Defines the behaviour of the system when a user creates multiple sessions.
company.tags	Object.<string, LabelStyle>	optional	The styles for status tags added to Assets.
company.v	Array.<int32>	optional
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"company": {
		"directory": {
			string: [
				number
			]
		},
		"id": number,
		"labels": {
			string: {
				"code": string,
				"fill": string,
				"graphic": string,
				"name": string,
				"notes": string,
				"stroke": string
			}
		},
		"name": string,
		"notes": string,
		"parent": number,
		"passwordPolicy": {
			"expireMode": string,
			"expireThreshold": number,
			"includeLetters": boolean,
			"includeNumbers": boolean,
			"includeSpecial": boolean,
			"includeUpperLower": boolean,
			"minimumLength": number
		},
		"references": {
			string: string
		},
		"sessionPolicy": {
			"applications": [
				string
			],
			"expireTimeout": number,
			"idleAllowed": boolean,
			"ipv4Ranges": [
				string
			],
			"maxSessions": number,
			"multiUser": string
		},
		"tags": {
			string: {
				"code": string,
				"fill": string,
				"graphic": string,
				"name": string,
				"notes": string,
				"stroke": string
			}
		},
		"v": [
			number
		]
	},
	"reqId": number
}

Response description

Property	Type	Description
company	RespIdParent	An object which contains the "id" and "parent" keys.
company.id	uint64?	Identifier given as input for the command.
company.parent	uint64?	Identifier of the parent to which this company belongs
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"company": {
		"id": number,
		"parent": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a company object, or it is invalid.
400	3	No valid changes would be performed.
400	3	One of the keys in the company.labels object is blank.
400	3	One of the values in the company.labels object is not valid.
400	3	One of the keys in the company.tags object is blank.
400	3	One of the values in the company.tags object is not valid.
400	3	One of the keys in the company.directory object is blank.
400	3	One of the values in the company.directory object is not an array.
400	3	One of the arrays in the company.directory object contains an invalid value.
400	3	One of the values in the company.sessionPolicy.applications array contains an invalid regular expression.
400	3	One of the values in the company.sessionPolicy.ipv4Ranges array contains an invalid IP address or CIDR range.
400	3	The given value for the company.sessionPolicy.multiUser is invalid.
400	3	The given value for the company.sessionPolicy.expireTimeout is invalid.
400	3	The given value for the company.sessionPolicy.maxSessions is invalid.
400	3	The given value for the company.passwordPolicy.minimumLength is invalid.
400	3	The given value for the company.passwordPolicy.expireMode is invalid.
400	3	The given value for the company.passwordPolicy.expireThreshold is invalid.
400	3	The company.passwordPolicy.expireThreshold is zero, and the company.passwordPolicy.expireMode is anything but PasswordExpiryMode.never.
400	3	The company.references were not provided as null or an object.
400	3	During create: When creating a new Company, a name was not given.
400	3	During update: When updating a Company, the name was given as null or blank.
400	3	During update: When updating a Company, the v was not an array, or contained too few numbers.
400	3	During create: When creating a new Company, too many company.references were given as input. Returns an ErrorDetailMinMax as the `errorDetails`.
401	5	You do not have permission to create a new Company.
401	5	You do not have permission to update the CompanyGeneral.
401	5	You do not have permission to update the CompanyDirectory.
401	5	You do not have permission to update the CompanyStyles.
401	5	You do not have permission to update the CompanyPolicies.
400	6	During update: When updating a Company, an incorrect v value was given as input.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	During update: The Company was not found by its unique identifier.
409	130	The given parent cannot be the same as the Company id. Returns an ErrorDetailParent as the `errorDetails`.
409	130	The given parent would create a circular reference in the Company tree. Returns an ErrorDetailParent as the `errorDetails`.
409	130	During update: When updating an Company, the resulting number of company.references would be too high. Returns an ErrorDetailParent as the `errorDetails`.

DELETE/companies

Deletes an existing Company.

Response description

Property	Type	Description
company	RespParentDeleted	An object which contains the Company's unique identifier and deleted status.
company.deleted	boolean	Flag showing if the object is deleted.
company.id	uint64?	Identifier given as input for the command.
company.parent	uint64	Identifier of the parent to which the Company is a child.
company.v	Array.<uint32>
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"company": {
		"deleted": boolean,
		"id": number,
		"parent": number,
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
401	5	You do not have permission to delete this Company.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company was not found by its unique identifier.

GET/companies/{companyId}?includeDeleted=boolean

Gets details of the specified Company.

URL Parameters

Parameter	Type	Required	Description
companyId	uint64	required	Unique identifier of the Company.
includeDeleted	boolean	optional	False by default, but when true the command will also return deleted objects.

Response description

Property	Type	Description
company	Company	The requested Company.
company.directory	Object.<string, Array.<uint64>> for value-values see: Contact.id	The list of Contacts from this and other companies broken down by contact role.
company.id	uint64	Unique identifier of the Company.
company.labels	Object.<codified, LabelStyle> for keys see: LabelStyle.code	The styles for labels added to Assets, Places, and other things.
company.name	string maximum-length: 100	The organizational name.
company.notes	string	Notes.
company.parent	uint64 see: Company.id	The unique identifier of this company's parent organization.
company.passwordPolicy	PasswordPolicy	The password complexity and expiry policy.
company.passwordPolicy.expireMode	PasswordExpiryMode	Defines how passwords expire.
company.passwordPolicy.expireThreshold	byte	The threshold for expiry.
company.passwordPolicy.includeLetters	boolean	Do passwords require alphabetical characters.
company.passwordPolicy.includeNumbers	boolean	Do passwords require numeric characters.
company.passwordPolicy.includeSpecial	boolean	Do passwords require non-alphanumeric characters.
company.passwordPolicy.includeUpperLower	boolean	Do passwords require upper-case and lower-case letters.
company.passwordPolicy.minimumLength	byte	The minimum number of characters required.
company.processedUtc	datetime	When the was change procesed.
company.references	Object.<string, string> maximum-count: 10 maximum-length of keys: 20 maximum-length of values: 100	Name/value collections of custom fields used to refer to external systems.
company.reseller	CompanyReseller	If this company is a reseller, then they have their own theme, support and billing information.
company.reseller.contactInfo	Object.<string, uint64> see: Contact.id maximum-count of keys: 100 for values see: Contact.id	A list of Contacts for company specific things like Technical Support, Billing, etc...
company.reseller.domain	string maximum-length: 100	The URN and path to the instance of v4. It does not contain the protocol because all instances are required to be HTTPS.
company.reseller.favourite	string maximum-length: 200	The name of the icon file used for browser bookmarks.
company.reseller.gamut	Object.<string, ColourStyle> maximum-length of keys: 25	Colours used as templates for status tags, labels, and places.
company.reseller.graphics	Object.<string, codified> maximum-length of keys: 25 maximum-length of values: 30	A list of symbol names and their corresponding FontAwesome icon names.
company.reseller.icon	string maximum-length: 200	The name of the image uploaded as the logo (used for collapsed/mobile view).
company.reseller.id	uint64 see: Company.id	Unique identifier of the Company.
company.reseller.languages	Array.<codified> maximum-length of values: 5	A list of supported languages for your customers.
company.reseller.logo	string maximum-length: 200	The name of the image uploaded as the logo (used for regular view).
company.reseller.notifyEmail	NotificationServerEmail	The server used for notification and conversational email messages sent and received by the system.
company.reseller.notifyEmail.incomingAddress	string	The domain or IP address of the incoming email server.
company.reseller.notifyEmail.incomingLogin	string	The username used to login to the incoming email server.
company.reseller.notifyEmail.incomingMessageNumber	uint32	IMAP message sequence number so only recent messages are retrieved.
company.reseller.notifyEmail.incomingPort	uint16	The port number of the incoming email server.
company.reseller.notifyEmail.incomingSecure	boolean	Is the incoming email server using a secure SSL/TLS connection (it should).
company.reseller.notifyEmail.incomingType	string	The type of incoming protocol to use (IMAP or POP3).
company.reseller.notifyEmail.outgoingAddress	string	The domain or IP address of the outgoing email server.
company.reseller.notifyEmail.outgoingLogin	string	The username used to login to the outgoing email server.
company.reseller.notifyEmail.outgoingPort	uint16	The port number of the outgoing email server.
company.reseller.notifyEmail.outgoingReplyTo	email	An optional field which can be set as the "sent from" and/or "reply-to" address.
company.reseller.notifyEmail.outgoingSecure	boolean	Is the outgoing email server using a secure SSL/TLS connection (it should).
company.reseller.notifyEmail.outgoingType	string	The type of outgoing protocol to use (only SMTP).
company.reseller.notifySms	NotificationServerSms	Definition for load-balanced outbound SMS numbers for the reseller.
company.reseller.notifySms.notifyLimit	uint16	A per-number/per-day limit on the amount of Notifications sent.
company.reseller.notifySms.phoneNumbers	Object.<string, Array.<phone>> fixed length of keys: 2	All phone numbers listed by the country (using two-digit ISO 3166-1 alpha-2 country codes) they each serve.
company.reseller.parent	uint64 see: Company.id	The unique identifier of this company's parent organization.
company.reseller.processedUtc	datetime	When the was change procesed.
company.reseller.recoverBody	string	The body of the email sent to a user requesting a password reset.
company.reseller.recoverIsHtml	boolean
company.reseller.recoverSubject	string	The subject of the email sent to a user requesting a password reset.
company.reseller.serviceName	string maximum-length: 150	The name of the branded service being provided to the seller's customers.
company.reseller.termsPreamble	string	A preamble to the general terms and conditions offered by Fleet Freedom.
company.reseller.termsUpdated	datetime	The date and time when the terms were updated. This will promt users who are logging-in to re-agree to the new terms
company.reseller.updated		by: login, from: monster
company.reseller.v	Array.<uint32>	Object version keys used to validate synchronization for all object properties.
company.reseller.website	Object.<string, colour> maximum-length of keys: 25 maximum-length of values: 22	Themed colours used in the web-based UI.
company.sessionPolicy	SessionPolicy	The session lifetime policy.
company.sessionPolicy.applications	Array.<string>	The list of applications users are allowed to use to create sessions.
company.sessionPolicy.expireTimeout	uint16	The lifetime duration of a session in minutes.
company.sessionPolicy.idleAllowed	boolean	Defines whether a session should be automatically killed when the connection breaks.
company.sessionPolicy.ipv4Ranges	Array.<ipv4> maximum-length of values: 19	Restrict session creation to only the provided IPv4 ranges (using CIDR slash-notation). Leave blank for Internet access.
company.sessionPolicy.maxSessions	byte	The maximum number of sessions allowed per user.
company.sessionPolicy.multiUser	SessionMultiUser	Defines the behaviour of the system when a user creates multiple sessions.
company.tags	Object.<codified, LabelStyle> for keys see: LabelStyle.code	The styles for status tags added to Assets.
company.updated		by: login, from: monster
company.userGroups	Array.<UserGroup>	A list of user groups that belong to this company. A user can only belong to groups from their own company.
company.v	Array.<int32> fixed count: 6	Object version keys used to validate synchronization for all object properties.
company.v[0]	int32	The first element is for the general properties
company.v[1]	int32	The second element is not used (yet)
company.v[2]	int32	The third element is not used (yet)
company.v[3]	int32	The fourth element is for the style properties
company.v[4]	int32	The fifth element is for the policy properties
company.v[5]	int32	The sixth element is for the reseller properties
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"company": {
		"directory": {
			string: [
				number
			]
		},
		"id": number,
		"labels": {
			string: {
				"code": string,
				"fill": string,
				"graphic": string,
				"name": string,
				"notes": string,
				"stroke": string
			}
		},
		"name": string,
		"notes": string,
		"parent": number,
		"passwordPolicy": {
			"expireMode": string,
			"expireThreshold": number,
			"includeLetters": boolean,
			"includeNumbers": boolean,
			"includeSpecial": boolean,
			"includeUpperLower": boolean,
			"minimumLength": number
		},
		"processedUtc": string,
		"references": {
			string: string
		},
		"reseller": {
			"contactInfo": {
				string: number
			},
			"domain": string,
			"favourite": string,
			"gamut": {
				string: {
					"fill": string,
					"stroke": string
				}
			},
			"graphics": {
				string: string
			},
			"icon": string,
			"id": number,
			"languages": [
				string
			],
			"logo": string,
			"notifyEmail": {
				"incomingAddress": string,
				"incomingLogin": string,
				"incomingMessageNumber": number,
				"incomingPort": number,
				"incomingSecure": boolean,
				"incomingType": string,
				"outgoingAddress": string,
				"outgoingLogin": string,
				"outgoingPort": number,
				"outgoingReplyTo": string,
				"outgoingSecure": boolean,
				"outgoingType": string
			},
			"notifySms": {
				"notifyLimit": number,
				"phoneNumbers": {
					string: [
						number
					]
				}
			},
			"parent": number,
			"processedUtc": string,
			"recoverBody": string,
			"recoverIsHtml": boolean,
			"recoverSubject": string,
			"serviceName": string,
			"termsPreamble": string,
			"termsUpdated": string,
			"updated": {
			},
			"v": [
				number
			],
			"website": {
				string: string
			}
		},
		"sessionPolicy": {
			"applications": [
				string
			],
			"expireTimeout": number,
			"idleAllowed": boolean,
			"ipv4Ranges": [
				string
			],
			"maxSessions": number,
			"multiUser": string
		},
		"tags": {
			string: {
				"code": string,
				"fill": string,
				"graphic": string,
				"name": string,
				"notes": string,
				"stroke": string
			}
		},
		"updated": {
		},
		"userGroups": [
			{
				"company": number,
				"id": number,
				"name": string,
				"notes": string,
				"permissions": [
					{
						"company": number,
						"kind": string,
						"labels": [
							string
						],
						"level": string,
						"method": string,
						"type": string
					}
				],
				"processedUtc": string,
				"updated": {
				},
				"v": [
					number
				]
			}
		],
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
401	5	You do not have permission to view this Company.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company was not found by its unique identifier.

POST/companies/{companyId}

Creates a new or updates an existing Company.

URL Parameters

Parameter	Type	Required	Description
companyId	uint64?	optional	Unique identifier of the Company. This value is optional, and ignored by the command.

HTTP Request body description

Property	Type	Required	Description
company	Object.<string, ?>	always	A simple object to contain the company parameters.
company.directory	Object.<string, Array.<uint64>> for value-values see: Contact.id	optional	The list of Contacts from this and other companies broken down by contact role.
company.id	uint64?	update	Unique identifier of the Company.
company.labels	Object.<string, LabelStyle>	optional	The styles for labels added to Assets, Places, and other things.
company.name	string maximum-length: 100	create	The organizational name.
company.notes	string	optional	Notes.
company.parent	uint64?	create	The unique identifier of this company's parent organization.
company.passwordPolicy	Object.<string, ?>	always	The password complexity and expiry policy.
company.passwordPolicy.expireMode	PasswordExpiryMode?	optional	Defines how passwords expire.
company.passwordPolicy.expireThreshold	byte?	optional	The threshold for expiry (in days).
company.passwordPolicy.includeLetters	boolean	optional	Do passwords require alphabetical characters.
company.passwordPolicy.includeNumbers	boolean	optional	Do passwords require numeric characters.
company.passwordPolicy.includeSpecial	boolean	optional	Do passwords require non-alphanumeric characters.
company.passwordPolicy.includeUpperLower	boolean	optional	Do passwords require upper-case and lower-case letters.
company.passwordPolicy.minimumLength	byte?	optional	The minimum number of characters required.
company.references	Object.<string, string>	optional	Name/value collections of custom fields used to refer to external systems. If the value is null, the references are removed from the Company.
company.sessionPolicy	Object.<string, ?>	always	The session lifetime policy.
company.sessionPolicy.applications	Array.<string>	optional	The list of applications users are allowed to use to create sessions.
company.sessionPolicy.expireTimeout	uint16?	optional	The lifetime duration of a session in minutes.
company.sessionPolicy.idleAllowed	boolean	optional	Defines whether a session should be automatically killed when the connection breaks.
company.sessionPolicy.ipv4Ranges	Array.<ipv4> maximum-length of values: 19	optional	Restrict session creation to only the provided IPv4 ranges (using CIDR slash-notation). Leave blank for Internet access.
company.sessionPolicy.maxSessions	byte?	optional	The maximum number of sessions allowed per user.
company.sessionPolicy.multiUser	SessionMultiUser?	optional	Defines the behaviour of the system when a user creates multiple sessions.
company.tags	Object.<string, LabelStyle>	optional	The styles for status tags added to Assets.
company.v	Array.<int32>	optional
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"company": {
		"directory": {
			string: [
				number
			]
		},
		"id": number,
		"labels": {
			string: {
				"code": string,
				"fill": string,
				"graphic": string,
				"name": string,
				"notes": string,
				"stroke": string
			}
		},
		"name": string,
		"notes": string,
		"parent": number,
		"passwordPolicy": {
			"expireMode": string,
			"expireThreshold": number,
			"includeLetters": boolean,
			"includeNumbers": boolean,
			"includeSpecial": boolean,
			"includeUpperLower": boolean,
			"minimumLength": number
		},
		"references": {
			string: string
		},
		"sessionPolicy": {
			"applications": [
				string
			],
			"expireTimeout": number,
			"idleAllowed": boolean,
			"ipv4Ranges": [
				string
			],
			"maxSessions": number,
			"multiUser": string
		},
		"tags": {
			string: {
				"code": string,
				"fill": string,
				"graphic": string,
				"name": string,
				"notes": string,
				"stroke": string
			}
		},
		"v": [
			number
		]
	},
	"reqId": number
}

Response description

Property	Type	Description
company	RespIdParent	An object which contains the "id" and "parent" keys.
company.id	uint64?	Identifier given as input for the command.
company.parent	uint64?	Identifier of the parent to which this company belongs
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"company": {
		"id": number,
		"parent": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a company object, or it is invalid.
400	3	No valid changes would be performed.
400	3	One of the keys in the company.labels object is blank.
400	3	One of the values in the company.labels object is not valid.
400	3	One of the keys in the company.tags object is blank.
400	3	One of the values in the company.tags object is not valid.
400	3	One of the keys in the company.directory object is blank.
400	3	One of the values in the company.directory object is not an array.
400	3	One of the arrays in the company.directory object contains an invalid value.
400	3	One of the values in the company.sessionPolicy.applications array contains an invalid regular expression.
400	3	One of the values in the company.sessionPolicy.ipv4Ranges array contains an invalid IP address or CIDR range.
400	3	The given value for the company.sessionPolicy.multiUser is invalid.
400	3	The given value for the company.sessionPolicy.expireTimeout is invalid.
400	3	The given value for the company.sessionPolicy.maxSessions is invalid.
400	3	The given value for the company.passwordPolicy.minimumLength is invalid.
400	3	The given value for the company.passwordPolicy.expireMode is invalid.
400	3	The given value for the company.passwordPolicy.expireThreshold is invalid.
400	3	The company.passwordPolicy.expireThreshold is zero, and the company.passwordPolicy.expireMode is anything but PasswordExpiryMode.never.
400	3	The company.references were not provided as null or an object.
400	3	During create: When creating a new Company, a name was not given.
400	3	During update: When updating a Company, the name was given as null or blank.
400	3	During update: When updating a Company, the v was not an array, or contained too few numbers.
400	3	During create: When creating a new Company, too many company.references were given as input. Returns an ErrorDetailMinMax as the `errorDetails`.
401	5	You do not have permission to create a new Company.
401	5	You do not have permission to update the CompanyGeneral.
401	5	You do not have permission to update the CompanyDirectory.
401	5	You do not have permission to update the CompanyStyles.
401	5	You do not have permission to update the CompanyPolicies.
400	6	During update: When updating a Company, an incorrect v value was given as input.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	During update: The Company was not found by its unique identifier.
409	130	The given parent cannot be the same as the Company id. Returns an ErrorDetailParent as the `errorDetails`.
409	130	The given parent would create a circular reference in the Company tree. Returns an ErrorDetailParent as the `errorDetails`.
409	130	During update: When updating an Company, the resulting number of company.references would be too high. Returns an ErrorDetailParent as the `errorDetails`.

DELETE/companies/{companyId}

Deletes an existing Company.

URL Parameters

Parameter	Type	Required	Description
companyId	uint64	required	Unique identifier of the Company.

Response description

Property	Type	Description
company	RespParentDeleted	An object which contains the Company's unique identifier and deleted status.
company.deleted	boolean	Flag showing if the object is deleted.
company.id	uint64?	Identifier given as input for the command.
company.parent	uint64	Identifier of the parent to which the Company is a child.
company.v	Array.<uint32>
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"company": {
		"deleted": boolean,
		"id": number,
		"parent": number,
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
401	5	You do not have permission to delete this Company.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company was not found by its unique identifier.

GET/companies/{companyId}/directories?includeDeleted=boolean

Gets details of the specified CompanyDirectory.

URL Parameters

Parameter	Type	Required	Description
companyId	uint64	required	Unique identifier of the Company.
includeDeleted	boolean	optional	False by default, but when true the command will also return deleted objects.

Response description

Property	Type	Description
companyDirectory		The requested CompanyDirectory.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"companyDirectory": {
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
401	5	You do not have permission to view this Company.
401	5	You do not have permission to view this CompanyDirectory.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company was not found by its unique identifier.
404	28	The CompanyDirectory was not found by its unique identifier.

GET/companies/{companyId}/generals?includeDeleted=boolean

Gets details of the specified CompanyGeneral.

URL Parameters

Parameter	Type	Required	Description
companyId	uint64	required	Unique identifier of the Company.
includeDeleted	boolean	optional	False by default, but when true the command will also return deleted objects.

Response description

Property	Type	Description
companyGeneral	CompanyGeneral	The requested CompanyGeneral.
companyGeneral.id	uint64 see: Company.id	Unique identifier of the Company.
companyGeneral.name	string maximum-length: 100	The organizational name.
companyGeneral.notes	string	Notes.
companyGeneral.parent	uint64 see: Company.id	The unique identifier of this company's parent organization.
companyGeneral.processedUtc	datetime	When the was change procesed.
companyGeneral.references	Object.<string, string> maximum-count: 10 maximum-length of keys: 20 maximum-length of values: 100	Name/value collections of custom fields used to refer to external systems.
companyGeneral.updated		by: login, from: monster
companyGeneral.v	Array.<uint32>	Object version keys used to validate synchronization for all object properties.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"companyGeneral": {
		"id": number,
		"name": string,
		"notes": string,
		"parent": number,
		"processedUtc": string,
		"references": {
			string: string
		},
		"updated": {
		},
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
401	5	You do not have permission to view this Company.
401	5	You do not have permission to view this CompanyGeneral.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company was not found by its unique identifier.
404	28	The CompanyGeneral was not found by its unique identifier.

GET/companies/{companyId}/policies?includeDeleted=boolean

Gets details of the specified CompanyPolicies.

URL Parameters

Parameter	Type	Required	Description
companyId	uint64	required	Unique identifier of the Company.
includeDeleted	boolean	optional	False by default, but when true the command will also return deleted objects.

Response description

Property	Type	Description
companyPolicies	CompanyPolicies	The requested CompanyPolicies.
companyPolicies.id	uint64 see: Company.id	Unique identifier of the Company.
companyPolicies.parent	uint64 see: Company.id	The unique identifier of this company's parent organization.
companyPolicies.passwordPolicy	PasswordPolicy	The password complexity and expiry policy.
companyPolicies.passwordPolicy.expireMode	PasswordExpiryMode	Defines how passwords expire.
companyPolicies.passwordPolicy.expireThreshold	byte	The threshold for expiry.
companyPolicies.passwordPolicy.includeLetters	boolean	Do passwords require alphabetical characters.
companyPolicies.passwordPolicy.includeNumbers	boolean	Do passwords require numeric characters.
companyPolicies.passwordPolicy.includeSpecial	boolean	Do passwords require non-alphanumeric characters.
companyPolicies.passwordPolicy.includeUpperLower	boolean	Do passwords require upper-case and lower-case letters.
companyPolicies.passwordPolicy.minimumLength	byte	The minimum number of characters required.
companyPolicies.processedUtc	datetime	When the was change procesed.
companyPolicies.sessionPolicy	SessionPolicy	The session lifetime policy.
companyPolicies.sessionPolicy.applications	Array.<string>	The list of applications users are allowed to use to create sessions.
companyPolicies.sessionPolicy.expireTimeout	uint16	The lifetime duration of a session in minutes.
companyPolicies.sessionPolicy.idleAllowed	boolean	Defines whether a session should be automatically killed when the connection breaks.
companyPolicies.sessionPolicy.ipv4Ranges	Array.<ipv4> maximum-length of values: 19	Restrict session creation to only the provided IPv4 ranges (using CIDR slash-notation). Leave blank for Internet access.
companyPolicies.sessionPolicy.maxSessions	byte	The maximum number of sessions allowed per user.
companyPolicies.sessionPolicy.multiUser	SessionMultiUser	Defines the behaviour of the system when a user creates multiple sessions.
companyPolicies.updated		by: login, from: monster
companyPolicies.v	Array.<uint32>	Object version keys used to validate synchronization for all object properties.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"companyPolicies": {
		"id": number,
		"parent": number,
		"passwordPolicy": {
			"expireMode": string,
			"expireThreshold": number,
			"includeLetters": boolean,
			"includeNumbers": boolean,
			"includeSpecial": boolean,
			"includeUpperLower": boolean,
			"minimumLength": number
		},
		"processedUtc": string,
		"sessionPolicy": {
			"applications": [
				string
			],
			"expireTimeout": number,
			"idleAllowed": boolean,
			"ipv4Ranges": [
				string
			],
			"maxSessions": number,
			"multiUser": string
		},
		"updated": {
		},
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
401	5	You do not have permission to view this Company.
401	5	You do not have permission to view this CompanyPolicies.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company was not found by its unique identifier.
404	28	The CompanyPolicies was not found by its unique identifier.

PATCH/companies/{companyId}/restore

Restores the specified Company.

URL Parameters

Parameter	Type	Required	Description
companyId	uint64	required	Unique identifier of the Company.

HTTP Request body description

Property	Type	Required	Description
company	ParamId	always	An object to contain the "id" key.
company.id	uint64	always	Identifier given as input for the command.
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"company": {
		"id": number
	},
	"reqId": number
}

Response description

Property	Type	Description
company	RespParentDeleted	An object which contains the Company's unique identifier and deleted status.
company.deleted	boolean	Flag showing if the object is deleted.
company.id	uint64?	Identifier given as input for the command.
company.parent	uint64	Identifier of the parent to which the Company is a child.
company.v	Array.<uint32>
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"company": {
		"deleted": boolean,
		"id": number,
		"parent": number,
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
401	5	You do not have permission to restore this Company.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company was not found by its unique identifier.
400	29	The Company was found, but is not marked as deleted.

GET/companies/{companyId}/styles?includeDeleted=boolean

Gets details of the specified CompanyStyles.

URL Parameters

Parameter	Type	Required	Description
companyId	uint64	required	Unique identifier of the Company.
includeDeleted	boolean	optional	False by default, but when true the command will also return deleted objects.

Response description

Property	Type	Description
companyLabels	CompanyStyles	The requested CompanyStyles.
companyLabels.id	uint64 see: Company.id	Unique identifier of the Company.
companyLabels.labels	Object.<codified, LabelStyle> for keys see: LabelStyle.code	The styles for labels added to Assets, Places, and other things.
companyLabels.parent	uint64 see: Company.id	The unique identifier of this company's parent organization.
companyLabels.processedUtc	datetime	When the was change procesed.
companyLabels.tags	Object.<codified, LabelStyle> for keys see: LabelStyle.code	The styles for status tags added to Assets.
companyLabels.updated		by: login, from: monster
companyLabels.v	Array.<uint32>	Object version keys used to validate synchronization for all object properties.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"companyLabels": {
		"id": number,
		"labels": {
			string: {
				"code": string,
				"fill": string,
				"graphic": string,
				"name": string,
				"notes": string,
				"stroke": string
			}
		},
		"parent": number,
		"processedUtc": string,
		"tags": {
			string: {
				"code": string,
				"fill": string,
				"graphic": string,
				"name": string,
				"notes": string,
				"stroke": string
			}
		},
		"updated": {
		},
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
401	5	You do not have permission to view this Company.
401	5	You do not have permission to view this CompanyStyles.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company was not found by its unique identifier.
404	28	The CompanyStyles was not found by its unique identifier.

Deprecated GET/companies/{companyId}/tree?tree=boolean&includeParent=boolean&includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

This request is an alias of /companies?parent={your-company-id}&tree=true&includeParent=true (when no additional query-string parameters are given) or /companies?parent={your-company-id}&tree=true&includeParent=true?{keys=values} (when at least one additional query-string key/value is given).

URL Parameters

Parameter	Type	Required	Default	Description
highest	uint64	optional		When using , sets the maximum id when listing from the database.
includeArchive	boolean	optional	`false`	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	`false`	False by default, but when true the command will also return deleted objects.
includeParent	boolean	optional	`true`	Defaults to true for this alias.
limit	uint16	optional		When using , sets the maximum number of objects in this response.
lowest	uint64	optional		When using , sets the minimum id when listing from the database.
tree	boolean	optional	`true`	Defaults to true for this alias.
your-company-id	uint64	aliased	`{your-company-id}`	Your own Company's identifier.

GET/companies/directories?parent=number&tree=boolean&includeParent=boolean&includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

URL Parameters

Parameter	Type	Required	Default	Description
highest	uint64?	optional		When using , sets the largest valued id objects to retrieve.
includeArchive	boolean	optional		Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional		False by default, but when true, the command will also return deleted objects.
includeParent	boolean	optional	`true`	When set to true (default), the parent Company is included in the results.
limit	uint16?	optional		When using , sets the maximum number of objects retrieved from the archive.
lowest	uint64?	optional		When using , sets the smallest valued id objects to retrieve.
parent	uint64?	optional	`{your-company-id}`	Unique identifier of the Company.
tree	boolean	optional	`true`	When set to true, the full tree of companies is returned. Otherwise, only the first-level child-companies are included.

Response description

Property	Type	Description
companyDirectories	Array.<>	The list of requested companies.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"companyDirectories": [
		{
		}
	],
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
401	5	You do not have permission to view this Company or child companies.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company was not found by its unique identifier.

GET/companies/directories?{keys=values}?parent=number&tree=boolean&includeParent=boolean&includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number&{keys=values}

URL Parameters

Parameter	Type	Required	Default	Description
highest	uint64?	optional		When using , sets the largest valued id objects to retrieve.
includeArchive	boolean	optional		Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional		False by default, but when true, the command will also return deleted objects.
includeParent	boolean	optional	`true`	When set to true (default), the parent Company is included in the results.
limit	uint16?	optional		When using , sets the maximum number of objects retrieved from the archive.
lowest	uint64?	optional		When using , sets the smallest valued id objects to retrieve.
parent	uint64?	optional	`{your-company-id}`	Unique identifier of the Company.
tree	boolean	optional	`true`	When set to true, the full tree of companies is returned. Otherwise, only the first-level child-companies are included.

Response description

Property	Type	Description
companyDirectories	Array.<>	The list of requested companies.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
references	Object.<string, string>	The reference string given as input.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"companyDirectories": [
		{
		}
	],
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"references": {
		string: string
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
400	3	The references is not an object, or it is invalid.
401	5	You do not have permission to view this Company or child companies.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company was not found by its unique identifier.

GET/companies/generals?parent=number&tree=boolean&includeParent=boolean&includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

URL Parameters

Parameter	Type	Required	Default	Description
highest	uint64?	optional		When using , sets the largest valued id objects to retrieve.
includeArchive	boolean	optional		Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional		False by default, but when true, the command will also return deleted objects.
includeParent	boolean	optional	`true`	When set to true (default), the parent Company is included in the results.
limit	uint16?	optional		When using , sets the maximum number of objects retrieved from the archive.
lowest	uint64?	optional		When using , sets the smallest valued id objects to retrieve.
parent	uint64?	optional	`{your-company-id}`	Unique identifier of the Company.
tree	boolean	optional	`true`	When set to true, the full tree of companies is returned. Otherwise, only the first-level child-companies are included.

Response description

Property	Type	Description
companies	Array.<CompanyGeneral>	The list of requested companies.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"companies": [
		{
			"id": number,
			"name": string,
			"notes": string,
			"parent": number,
			"processedUtc": string,
			"references": {
				string: string
			},
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
401	5	You do not have permission to view this Company or child companies.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company was not found by its unique identifier.

GET/companies/generals?{keys=values}?parent=number&tree=boolean&includeParent=boolean&includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number&{keys=values}

URL Parameters

Parameter	Type	Required	Default	Description
highest	uint64?	optional		When using , sets the largest valued id objects to retrieve.
includeArchive	boolean	optional		Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional		False by default, but when true, the command will also return deleted objects.
includeParent	boolean	optional	`true`	When set to true (default), the parent Company is included in the results.
limit	uint16?	optional		When using , sets the maximum number of objects retrieved from the archive.
lowest	uint64?	optional		When using , sets the smallest valued id objects to retrieve.
parent	uint64?	optional	`{your-company-id}`	Unique identifier of the Company.
tree	boolean	optional	`true`	When set to true, the full tree of companies is returned. Otherwise, only the first-level child-companies are included.

Response description

Property	Type	Description
companies	Array.<CompanyGeneral>	The list of requested companies.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
references	Object.<string, string>	The reference string given as input.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"companies": [
		{
			"id": number,
			"name": string,
			"notes": string,
			"parent": number,
			"processedUtc": string,
			"references": {
				string: string
			},
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"references": {
		string: string
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
400	3	The references is not an object, or it is invalid.
401	5	You do not have permission to view this Company or child companies.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company was not found by its unique identifier.

GET/companies/policies?parent=number&tree=boolean&includeParent=boolean&includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

URL Parameters

Parameter	Type	Required	Default	Description
highest	uint64?	optional		When using , sets the largest valued id objects to retrieve.
includeArchive	boolean	optional		Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional		False by default, but when true, the command will also return deleted objects.
includeParent	boolean	optional	`true`	When set to true (default), the parent Company is included in the results.
limit	uint16?	optional		When using , sets the maximum number of objects retrieved from the archive.
lowest	uint64?	optional		When using , sets the smallest valued id objects to retrieve.
parent	uint64?	optional	`{your-company-id}`	Unique identifier of the Company.
tree	boolean	optional	`true`	When set to true, the full tree of companies is returned. Otherwise, only the first-level child-companies are included.

Response description

Property	Type	Description
companyPolicies	Array.<CompanyPolicies>	The list of requested companies.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"companyPolicies": [
		{
			"id": number,
			"parent": number,
			"passwordPolicy": {
				"expireMode": string,
				"expireThreshold": number,
				"includeLetters": boolean,
				"includeNumbers": boolean,
				"includeSpecial": boolean,
				"includeUpperLower": boolean,
				"minimumLength": number
			},
			"processedUtc": string,
			"sessionPolicy": {
				"applications": [
					string
				],
				"expireTimeout": number,
				"idleAllowed": boolean,
				"ipv4Ranges": [
					string
				],
				"maxSessions": number,
				"multiUser": string
			},
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
401	5	You do not have permission to view this Company or child companies.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company was not found by its unique identifier.

GET/companies/policies?{keys=values}?parent=number&tree=boolean&includeParent=boolean&includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number&{keys=values}

URL Parameters

Parameter	Type	Required	Default	Description
highest	uint64?	optional		When using , sets the largest valued id objects to retrieve.
includeArchive	boolean	optional		Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional		False by default, but when true, the command will also return deleted objects.
includeParent	boolean	optional	`true`	When set to true (default), the parent Company is included in the results.
limit	uint16?	optional		When using , sets the maximum number of objects retrieved from the archive.
lowest	uint64?	optional		When using , sets the smallest valued id objects to retrieve.
parent	uint64?	optional	`{your-company-id}`	Unique identifier of the Company.
tree	boolean	optional	`true`	When set to true, the full tree of companies is returned. Otherwise, only the first-level child-companies are included.

Response description

Property	Type	Description
companyPolicies	Array.<CompanyPolicies>	The list of requested companies.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
references	Object.<string, string>	The reference string given as input.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"companyPolicies": [
		{
			"id": number,
			"parent": number,
			"passwordPolicy": {
				"expireMode": string,
				"expireThreshold": number,
				"includeLetters": boolean,
				"includeNumbers": boolean,
				"includeSpecial": boolean,
				"includeUpperLower": boolean,
				"minimumLength": number
			},
			"processedUtc": string,
			"sessionPolicy": {
				"applications": [
					string
				],
				"expireTimeout": number,
				"idleAllowed": boolean,
				"ipv4Ranges": [
					string
				],
				"maxSessions": number,
				"multiUser": string
			},
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"references": {
		string: string
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
400	3	The references is not an object, or it is invalid.
401	5	You do not have permission to view this Company or child companies.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company was not found by its unique identifier.

GET/companies/styles?parent=number&tree=boolean&includeParent=boolean&includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

URL Parameters

Parameter	Type	Required	Default	Description
highest	uint64?	optional		When using , sets the largest valued id objects to retrieve.
includeArchive	boolean	optional		Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional		False by default, but when true, the command will also return deleted objects.
includeParent	boolean	optional	`true`	When set to true (default), the parent Company is included in the results.
limit	uint16?	optional		When using , sets the maximum number of objects retrieved from the archive.
lowest	uint64?	optional		When using , sets the smallest valued id objects to retrieve.
parent	uint64?	optional	`{your-company-id}`	Unique identifier of the Company.
tree	boolean	optional	`true`	When set to true, the full tree of companies is returned. Otherwise, only the first-level child-companies are included.

Response description

Property	Type	Description
companyLabels	Array.<CompanyStyles>	The list of requested companies.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"companyLabels": [
		{
			"id": number,
			"labels": {
				string: {
					"code": string,
					"fill": string,
					"graphic": string,
					"name": string,
					"notes": string,
					"stroke": string
				}
			},
			"parent": number,
			"processedUtc": string,
			"tags": {
				string: {
					"code": string,
					"fill": string,
					"graphic": string,
					"name": string,
					"notes": string,
					"stroke": string
				}
			},
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
401	5	You do not have permission to view this Company or child companies.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company was not found by its unique identifier.

GET/companies/styles?{keys=values}?parent=number&tree=boolean&includeParent=boolean&includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number&{keys=values}

URL Parameters

Parameter	Type	Required	Default	Description
highest	uint64?	optional		When using , sets the largest valued id objects to retrieve.
includeArchive	boolean	optional		Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional		False by default, but when true, the command will also return deleted objects.
includeParent	boolean	optional	`true`	When set to true (default), the parent Company is included in the results.
limit	uint16?	optional		When using , sets the maximum number of objects retrieved from the archive.
lowest	uint64?	optional		When using , sets the smallest valued id objects to retrieve.
parent	uint64?	optional	`{your-company-id}`	Unique identifier of the Company.
tree	boolean	optional	`true`	When set to true, the full tree of companies is returned. Otherwise, only the first-level child-companies are included.

Response description

Property	Type	Description
companyLabels	Array.<CompanyStyles>	The list of requested companies.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
references	Object.<string, string>	The reference string given as input.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"companyLabels": [
		{
			"id": number,
			"labels": {
				string: {
					"code": string,
					"fill": string,
					"graphic": string,
					"name": string,
					"notes": string,
					"stroke": string
				}
			},
			"parent": number,
			"processedUtc": string,
			"tags": {
				string: {
					"code": string,
					"fill": string,
					"graphic": string,
					"name": string,
					"notes": string,
					"stroke": string
				}
			},
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"references": {
		string: string
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
400	3	The references is not an object, or it is invalid.
401	5	You do not have permission to view this Company or child companies.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company was not found by its unique identifier.

Deprecated GET/companies/tree?tree=boolean&includeParent=boolean&includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

URL Parameters

Parameter	Type	Required	Default	Description
highest	uint64	optional		When using , sets the maximum id when listing from the database.
includeArchive	boolean	optional	`false`	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	`false`	False by default, but when true the command will also return deleted objects.
includeParent	boolean	optional	`true`	Defaults to true for this alias.
limit	uint16	optional		When using , sets the maximum number of objects in this response.
lowest	uint64	optional		When using , sets the minimum id when listing from the database.
tree	boolean	optional	`true`	Defaults to true for this alias.
your-company-id	uint64	aliased	`{your-company-id}`	Your own Company's identifier.

Dispatch

POST/assets/{assetId}/dispatch

Updates an existing AssetDispatch.

URL Parameters

Parameter	Type	Required	Description
assetId	uint64?	optional	Unique identifier of the Asset. This value is optional, and ignored by the command.

HTTP Request body description

Property	Type	Required	Description
assetDispatch	Object.<string, ?>	always	A simple object to contain the AssetDispatch parameters.
assetDispatch.directions	Array.<DispatchDirection>	optional	Driving directions and route path details.
assetDispatch.id	uint64	always	The unique identifier of the asset you want to update.
assetDispatch.jobs	Array.<uint64> see: DispatchJob	optional	The list of DispatchJobs to be assigned to this asset.
assetDispatch.optimize	boolean	optional	Indicates whether the jobs should be optimized based on distance and priority.
assetDispatch.v	Array.<int32>	optional
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"assetDispatch": {
		"directions": [
			{
				"directions": [
					{ /* recursive DispatchDirection objects */ }
				],
				"distance": number,
				"duration": string,
				"instructions": string,
				"job": number,
				"path": string,
				"step": number
			}
		],
		"id": number,
		"jobs": [
			number
		],
		"optimize": boolean,
		"v": [
			number
		]
	},
	"reqId": number
}

Response description

Property	Type	Description
assetDispatch	RespIdCompany	An object which contains the "id" and "company" keys.
assetDispatch.company	uint64	Identifier of the Company to which this object belongs.
assetDispatch.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"assetDispatch": {
		"company": number,
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain an assetDispatch object, or it is invalid.
400	3	Not enough keys exist in the assetDispatch object.
400	3	The assetDispatch.id is invalid.
400	3	The v was not an array, or contained too few numbers.
400	3	One of the assetDispatch.jobs given in the array cannot be parsed, or is a value less than zero. Returns an ErrorDetailInput as the `errorDetails`.
400	3	One of the assetDispatch.directions given in the array cannot be parsed. Returns an ErrorDetailInput as the `errorDetails`.
401	5	You do not have permission to update the AssetDispatch.
401	5	You do not have permission to view this Asset.
400	6	During update: When updating an AssetDispatch, the wrong version key was given.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	20	This Asset was not found by its unique identifier.
404	20	The Asset for one of the assetDispatch.jobs was not found.
502	82	An error occured while optimizing the job steps.
403	96	This Asset is suspended. Before updating AssetDispatch, it must be reactivated.
403	96	The Asset for one of the assetDispatch.jobs is suspended.
409	130	One or more of the assetDispatch.jobs cannot be re-assigned to this Asset as they are completed.
409	130	One or more of the assetDispatch.jobs don't belong to the same Company as this Asset
409	130	One or more of the assetDispatch.jobs don't have any matching labels with this Asset
404	139	One of the assetDispatch.jobs was not found.
404	141	One or more of the assetDispatch.jobs given as input in the jobs array was not found. Returns an ErrorDetailBadIds as the `errorDetails`.

GET/assets/{assetId}/dispatch/jobs?includeDeleted=boolean&includeArchive=boolean&limit=number&after=string&before=string

Gets the list of DispatchJobs for the specified Asset.

URL Parameters

Parameter	Type	Required	Description
after	datetime	optional	When using , sets the earliest objects (by dts) to retrieve from the archive.
assetId	uint64	required	Unique identifier of the Asset.
before	datetime	optional	When using , sets the most recent objects (by dts) to retrieve from the archive.
includeArchive	boolean	optional	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	False by default, but when true the command will also return deleted objects.
limit	uint16?	optional	When using , sets the maximum number of objects retrieved from the archive.

Response description

Property	Type	Description
asset	RespIdCompany	An object to contain the "id" of the Asset to which the array of DispatchJobs belong.
asset.company	uint64	Identifier of the Company to which this object belongs.
asset.id	uint64?	Identifier given as input for the command.
dispatchJobs	Array.<DispatchJob>	The list of requested DispatchJobs.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"asset": {
		"company": number,
		"id": number
	},
	"dispatchJobs": [
		{
			"asset": number,
			"attachments": [
				number
			],
			"company": number,
			"created": string,
			"driver": string,
			"forms": [
				number
			],
			"id": number,
			"instructions": string,
			"labels": [
				string
			],
			"name": string,
			"priority": string,
			"processedUtc": string,
			"references": {
				string: string
			},
			"steps": [
				{
					"address": string,
					"duration": string,
					"eta": string,
					"id": number,
					"latlng": {
						"lat": number,
						"lng": number
					},
					"name": string,
					"notes": string,
					"place": number,
					"signatory": string,
					"signature": boolean,
					"states": {
						string: {
							"latlng": {
								"lat": number,
								"lng": number
							},
							"updated": string
						}
					}
				}
			],
			"tags": [
				string
			],
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a asset object, or it is invalid.
400	3	The asset object does not contain an id, or it is invalid.
401	5	You do not have permission to view DispatchJobs.
401	5	You do not have permission to view the associated Asset.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	20	The Asset was not found by its unique identifier.
404	28	The Company containing the DispatchJobs was not found.
403	96	The Asset was found, but it is suspended. Before using any Asset resources, it must be reactivated.

GET/assets/{assetId}/dispatch/jobs?{keys=values}?includeDeleted=boolean&includeArchive=boolean&limit=number&after=string&before=string&{keys=values}

Gets the list of DispatchJobs for the specified Asset only if the specified reference fields match. If no references are specified, it will match any DispatchJob with no references. If a reference value is null, it will match any DispatchJob without that reference key.

URL Parameters

Parameter	Type	Required	Description
after	datetime	optional	When using , sets the earliest objects (by dts) to retrieve from the archive.
assetId	uint64	required	Unique identifier of the Asset.
before	datetime	optional	When using , sets the most recent objects (by dts) to retrieve from the archive.
includeArchive	boolean	optional	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	False by default, but when true the command will also return deleted objects.
limit	uint16?	optional	When using , sets the maximum number of objects retrieved from the archive.

Response description

Property	Type	Description
asset	RespIdCompany	An object to contain the "id" of the Asset to which the array of DispatchJobs belong.
asset.company	uint64	Identifier of the Company to which this object belongs.
asset.id	uint64?	Identifier given as input for the command.
dispatchJobs	Array.<DispatchJob>	The list of requested DispatchJobs.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
references	Object.<string, string>	The reference string given as input.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"asset": {
		"company": number,
		"id": number
	},
	"dispatchJobs": [
		{
			"asset": number,
			"attachments": [
				number
			],
			"company": number,
			"created": string,
			"driver": string,
			"forms": [
				number
			],
			"id": number,
			"instructions": string,
			"labels": [
				string
			],
			"name": string,
			"priority": string,
			"processedUtc": string,
			"references": {
				string: string
			},
			"steps": [
				{
					"address": string,
					"duration": string,
					"eta": string,
					"id": number,
					"latlng": {
						"lat": number,
						"lng": number
					},
					"name": string,
					"notes": string,
					"place": number,
					"signatory": string,
					"signature": boolean,
					"states": {
						string: {
							"latlng": {
								"lat": number,
								"lng": number
							},
							"updated": string
						}
					}
				}
			],
			"tags": [
				string
			],
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"references": {
		string: string
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a asset object, or it is invalid.
400	3	The request does not contain a references object, or it is invalid.
400	3	The asset object does not contain an id, or it is invalid.
401	5	You do not have permission to view DispatchJobs.
401	5	You do not have permission to view the associated Asset.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	20	The Asset was not found by its unique identifier.
404	28	The Company containing the DispatchJobs was not found.
403	96	The Asset was found, but it is suspended. Before using any Asset resources, it must be reactivated.

GET/assets/{assetId}/dispatch/tasks?includeDeleted=boolean&includeArchive=boolean&limit=number&after=string&before=string

Gets the list of DispatchTasks for the specified Asset.

URL Parameters

Parameter	Type	Required	Description
after	datetime	optional	When using , sets the earliest objects (by dts) to retrieve from the archive.
assetId	uint64	required	Unique identifier of the Asset.
before	datetime	optional	When using , sets the most recent objects (by dts) to retrieve from the archive.
includeArchive	boolean	optional	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	False by default, but when true the command will also return deleted objects.
limit	uint16?	optional	When using , sets the maximum number of objects retrieved from the archive.

Response description

Property	Type	Description
asset	RespIdCompany	An object to contain the "id" of the Asset to which the array of DispatchTasks belong.
asset.company	uint64	Identifier of the Company to which this object belongs.
asset.id	uint64?	Identifier given as input for the command.
dispatchTasks	Array.<DispatchTask>	The list of requested DispatchTasks.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"asset": {
		"company": number,
		"id": number
	},
	"dispatchTasks": [
		{
			"address": string,
			"arrived": string,
			"asset": number,
			"attachments": [
				number
			],
			"company": number,
			"completed": string,
			"created": string,
			"duration": string,
			"eta": string,
			"id": number,
			"instructions": string,
			"latlng": {
				"lat": number,
				"lng": number
			},
			"name": string,
			"notes": string,
			"place": number,
			"processedUtc": string,
			"reference": string,
			"references": {
				string: string
			},
			"signatory": string,
			"signature": boolean,
			"status": string,
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a asset object, or it is invalid.
400	3	The asset object does not contain an id, or it is invalid.
401	5	You do not have permission to view DispatchTasks.
401	5	You do not have permission to view the associated Asset.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	20	The Asset was not found by its unique identifier.
404	28	The Company containing the DispatchTasks was not found.
403	96	The Asset was found, but it is suspended. Before using any Asset resources, it must be reactivated.

GET/assets/{assetId}/dispatch/tasks?{keys=values}?includeDeleted=boolean&includeArchive=boolean&limit=number&after=string&before=string&{keys=values}

Gets the list of DispatchTasks for the specified Asset only if the specified reference fields match. If no references are specified, it will match any DispatchTask with no references. If a reference value is null, it will match any DispatchTask without that reference key.

URL Parameters

Parameter	Type	Required	Description
after	datetime	optional	When using , sets the earliest objects (by dts) to retrieve from the archive.
assetId	uint64	required	Unique identifier of the Asset.
before	datetime	optional	When using , sets the most recent objects (by dts) to retrieve from the archive.
includeArchive	boolean	optional	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	False by default, but when true the command will also return deleted objects.
limit	uint16?	optional	When using , sets the maximum number of objects retrieved from the archive.

Response description

Property	Type	Description
asset	RespIdCompany	An object to contain the "id" of the Asset to which the array of DispatchTasks belong.
asset.company	uint64	Identifier of the Company to which this object belongs.
asset.id	uint64?	Identifier given as input for the command.
dispatchTasks	Array.<DispatchTask>	The list of requested DispatchTasks.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
references	Object.<string, string>	The reference string given as input.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"asset": {
		"company": number,
		"id": number
	},
	"dispatchTasks": [
		{
			"address": string,
			"arrived": string,
			"asset": number,
			"attachments": [
				number
			],
			"company": number,
			"completed": string,
			"created": string,
			"duration": string,
			"eta": string,
			"id": number,
			"instructions": string,
			"latlng": {
				"lat": number,
				"lng": number
			},
			"name": string,
			"notes": string,
			"place": number,
			"processedUtc": string,
			"reference": string,
			"references": {
				string: string
			},
			"signatory": string,
			"signature": boolean,
			"status": string,
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"references": {
		string: string
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a asset object, or it is invalid.
400	3	The request does not contain a references object, or it is invalid.
400	3	The asset object does not contain an id, or it is invalid.
401	5	You do not have permission to view DispatchTasks.
401	5	You do not have permission to view the associated Asset.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	20	The Asset was not found by its unique identifier.
404	28	The Company containing the DispatchTasks was not found.
403	96	The Asset was found, but it is suspended. Before using any Asset resources, it must be reactivated.

PATCH/assets/dispatch

Updates an existing AssetDispatch.

HTTP Request body description

Property	Type	Required	Description
assetDispatch	Object.<string, ?>	always	A simple object to contain the AssetDispatch parameters.
assetDispatch.directions	Array.<DispatchDirection>	optional	Driving directions and route path details.
assetDispatch.id	uint64	always	The unique identifier of the asset you want to update.
assetDispatch.jobs	Array.<uint64> see: DispatchJob	optional	The list of DispatchJobs to be assigned to this asset.
assetDispatch.optimize	boolean	optional	Indicates whether the jobs should be optimized based on distance and priority.
assetDispatch.v	Array.<int32>	optional
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"assetDispatch": {
		"directions": [
			{
				"directions": [
					{ /* recursive DispatchDirection objects */ }
				],
				"distance": number,
				"duration": string,
				"instructions": string,
				"job": number,
				"path": string,
				"step": number
			}
		],
		"id": number,
		"jobs": [
			number
		],
		"optimize": boolean,
		"v": [
			number
		]
	},
	"reqId": number
}

Response description

Property	Type	Description
assetDispatch	RespIdCompany	An object which contains the "id" and "company" keys.
assetDispatch.company	uint64	Identifier of the Company to which this object belongs.
assetDispatch.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"assetDispatch": {
		"company": number,
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain an assetDispatch object, or it is invalid.
400	3	Not enough keys exist in the assetDispatch object.
400	3	The assetDispatch.id is invalid.
400	3	The v was not an array, or contained too few numbers.
400	3	One of the assetDispatch.jobs given in the array cannot be parsed, or is a value less than zero. Returns an ErrorDetailInput as the `errorDetails`.
400	3	One of the assetDispatch.directions given in the array cannot be parsed. Returns an ErrorDetailInput as the `errorDetails`.
401	5	You do not have permission to update the AssetDispatch.
401	5	You do not have permission to view this Asset.
400	6	During update: When updating an AssetDispatch, the wrong version key was given.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	20	This Asset was not found by its unique identifier.
404	20	The Asset for one of the assetDispatch.jobs was not found.
502	82	An error occured while optimizing the job steps.
403	96	This Asset is suspended. Before updating AssetDispatch, it must be reactivated.
403	96	The Asset for one of the assetDispatch.jobs is suspended.
409	130	One or more of the assetDispatch.jobs cannot be re-assigned to this Asset as they are completed.
409	130	One or more of the assetDispatch.jobs don't belong to the same Company as this Asset
409	130	One or more of the assetDispatch.jobs don't have any matching labels with this Asset
404	139	One of the assetDispatch.jobs was not found.
404	141	One or more of the assetDispatch.jobs given as input in the jobs array was not found. Returns an ErrorDetailBadIds as the `errorDetails`.

GET/companies/{companyId}/assets/dispatch/jobs?{keys=values}?includeDeleted=boolean&includeArchive=boolean&limit=number&after=string&before=string&{keys=values}

Gets the list of DispatchJobs for the specified Company only if the specified reference fields match. If no references are specified, it will match any DispatchJob with no references. If a reference value is null, it will match any DispatchJob without that reference key.

URL Parameters

Parameter	Type	Required	Description
after	datetime	optional	When using , sets the earliest objects (by dts) to retrieve from the archive.
before	datetime	optional	When using , sets the most recent objects (by dts) to retrieve from the archive.
companyId	uint64	required	Unique identifier of the Company.
includeArchive	boolean	optional	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	False by default, but when true the command will also return deleted objects.
limit	uint16?	optional	When using , sets the maximum number of objects retrieved from the archive.

Response description

Property	Type	Description
company	RespId	An object to contain the "id" of the Company to which the array of DispatchJobs belong.
company.id	uint64?	Identifier given as input for the command.
dispatchJobs	Array.<DispatchJob>	The list of requested DispatchJobs.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
references	Object.<string, string>	The reference string given as input.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"company": {
		"id": number
	},
	"dispatchJobs": [
		{
			"asset": number,
			"attachments": [
				number
			],
			"company": number,
			"created": string,
			"driver": string,
			"forms": [
				number
			],
			"id": number,
			"instructions": string,
			"labels": [
				string
			],
			"name": string,
			"priority": string,
			"processedUtc": string,
			"references": {
				string: string
			},
			"steps": [
				{
					"address": string,
					"duration": string,
					"eta": string,
					"id": number,
					"latlng": {
						"lat": number,
						"lng": number
					},
					"name": string,
					"notes": string,
					"place": number,
					"signatory": string,
					"signature": boolean,
					"states": {
						string: {
							"latlng": {
								"lat": number,
								"lng": number
							},
							"updated": string
						}
					}
				}
			],
			"tags": [
				string
			],
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"references": {
		string: string
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a company object, or it is invalid.
400	3	The request does not contain a references object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
401	5	You do not have permission to view DispatchJobs.
401	5	You do not have permission to view Assets.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company containing the DispatchJobs was not found.

GET/companies/{companyId}/assets/dispatch/jobs?includeDeleted=boolean&includeArchive=boolean&limit=number&after=string&before=string

Gets the list of DispatchJobs for the specified Company.

URL Parameters

Parameter	Type	Required	Description
after	datetime	optional	When using , sets the earliest objects (by dts) to retrieve from the archive.
before	datetime	optional	When using , sets the most recent objects (by dts) to retrieve from the archive.
companyId	uint64	required	Unique identifier of the Company.
includeArchive	boolean	optional	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	False by default, but when true the command will also return deleted objects.
limit	uint16?	optional	When using , sets the maximum number of objects retrieved from the archive.

Response description

Property	Type	Description
company	RespId	An object to contain the "id" of the Company to which the array of DispatchJobs belong.
company.id	uint64?	Identifier given as input for the command.
dispatchJobs	Array.<DispatchJob>	The list of requested DispatchJobs.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"company": {
		"id": number
	},
	"dispatchJobs": [
		{
			"asset": number,
			"attachments": [
				number
			],
			"company": number,
			"created": string,
			"driver": string,
			"forms": [
				number
			],
			"id": number,
			"instructions": string,
			"labels": [
				string
			],
			"name": string,
			"priority": string,
			"processedUtc": string,
			"references": {
				string: string
			},
			"steps": [
				{
					"address": string,
					"duration": string,
					"eta": string,
					"id": number,
					"latlng": {
						"lat": number,
						"lng": number
					},
					"name": string,
					"notes": string,
					"place": number,
					"signatory": string,
					"signature": boolean,
					"states": {
						string: {
							"latlng": {
								"lat": number,
								"lng": number
							},
							"updated": string
						}
					}
				}
			],
			"tags": [
				string
			],
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
401	5	You do not have permission to view DispatchJobs.
401	5	You do not have permission to view Assets.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company containing the DispatchJobs was not found.

GET/companies/{companyId}/assets/dispatch/jobs?labels={string}&includeDeleted=boolean&includeArchive=boolean&limit=number&after=string&before=string

Gets the list of DispatchJobs for the specified Company only if the DispatchJob.labels matches all of the given labels.

URL Parameters

Parameter	Type	Required	Description
after	datetime	optional	When using , sets the earliest objects (by dts) to retrieve from the archive.
before	datetime	optional	When using , sets the most recent objects (by dts) to retrieve from the archive.
companyId	uint64	required	Unique identifier of the Company.
includeArchive	boolean	optional	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	False by default, but when true the command will also return deleted objects.
labels	string	required	Labels to match the DispatchJob.
limit	uint16?	optional	When using , sets the maximum number of objects retrieved from the archive.

Response description

Property	Type	Description
company	RespId	An object to contain the "id" of the Company to which the array of DispatchJobs belong.
company.id	uint64?	Identifier given as input for the command.
dispatchJobs	Array.<DispatchJob>	The list of requested DispatchJobs.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
labels	Array.<string>	The labels given as input.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"company": {
		"id": number
	},
	"dispatchJobs": [
		{
			"asset": number,
			"attachments": [
				number
			],
			"company": number,
			"created": string,
			"driver": string,
			"forms": [
				number
			],
			"id": number,
			"instructions": string,
			"labels": [
				string
			],
			"name": string,
			"priority": string,
			"processedUtc": string,
			"references": {
				string: string
			},
			"steps": [
				{
					"address": string,
					"duration": string,
					"eta": string,
					"id": number,
					"latlng": {
						"lat": number,
						"lng": number
					},
					"name": string,
					"notes": string,
					"place": number,
					"signatory": string,
					"signature": boolean,
					"states": {
						string: {
							"latlng": {
								"lat": number,
								"lng": number
							},
							"updated": string
						}
					}
				}
			],
			"tags": [
				string
			],
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"labels": [
		string
	],
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
400	3	The labels is not an array.
401	5	You do not have permission to view any DispatchJobs for this Company.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company was not found by its unique identifier.

GET/companies/{companyId}/assets/dispatch/tasks?{keys=values}?includeDeleted=boolean&includeArchive=boolean&limit=number&after=string&before=string&{keys=values}

Gets the list of DispatchTasks for the specified Company only if the specified reference fields match. If no references are specified, it will match any DispatchTask with no references. If a reference value is null, it will match any DispatchTask without that reference key.

URL Parameters

Parameter	Type	Required	Description
after	datetime	optional	When using , sets the earliest objects (by dts) to retrieve from the archive.
before	datetime	optional	When using , sets the most recent objects (by dts) to retrieve from the archive.
companyId	uint64	required	Unique identifier of the Company.
includeArchive	boolean	optional	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	False by default, but when true the command will also return deleted objects.
limit	uint16?	optional	When using , sets the maximum number of objects retrieved from the archive.

Response description

Property	Type	Description
company	RespId	An object to contain the "id" of the Company to which the array of DispatchTasks belong.
company.id	uint64?	Identifier given as input for the command.
dispatchTasks	Array.<DispatchTask>	The list of requested DispatchTasks.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
references	Object.<string, string>	The reference string given as input.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"company": {
		"id": number
	},
	"dispatchTasks": [
		{
			"address": string,
			"arrived": string,
			"asset": number,
			"attachments": [
				number
			],
			"company": number,
			"completed": string,
			"created": string,
			"duration": string,
			"eta": string,
			"id": number,
			"instructions": string,
			"latlng": {
				"lat": number,
				"lng": number
			},
			"name": string,
			"notes": string,
			"place": number,
			"processedUtc": string,
			"reference": string,
			"references": {
				string: string
			},
			"signatory": string,
			"signature": boolean,
			"status": string,
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"references": {
		string: string
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a company object, or it is invalid.
400	3	The request does not contain a references object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
401	5	You do not have permission to view DispatchTasks.
401	5	You do not have permission to view Assets.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company containing the DispatchTasks was not found.

GET/companies/{companyId}/assets/dispatch/tasks?includeDeleted=boolean&includeArchive=boolean&limit=number&after=string&before=string

Gets the list of DispatchTasks for the specified Company.

URL Parameters

Parameter	Type	Required	Description
after	datetime	optional	When using , sets the earliest objects (by dts) to retrieve from the archive.
before	datetime	optional	When using , sets the most recent objects (by dts) to retrieve from the archive.
companyId	uint64	required	Unique identifier of the Company.
includeArchive	boolean	optional	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	False by default, but when true the command will also return deleted objects.
limit	uint16?	optional	When using , sets the maximum number of objects retrieved from the archive.

Response description

Property	Type	Description
company	RespId	An object to contain the "id" of the Company to which the array of DispatchTasks belong.
company.id	uint64?	Identifier given as input for the command.
dispatchTasks	Array.<DispatchTask>	The list of requested DispatchTasks.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"company": {
		"id": number
	},
	"dispatchTasks": [
		{
			"address": string,
			"arrived": string,
			"asset": number,
			"attachments": [
				number
			],
			"company": number,
			"completed": string,
			"created": string,
			"duration": string,
			"eta": string,
			"id": number,
			"instructions": string,
			"latlng": {
				"lat": number,
				"lng": number
			},
			"name": string,
			"notes": string,
			"place": number,
			"processedUtc": string,
			"reference": string,
			"references": {
				string: string
			},
			"signatory": string,
			"signature": boolean,
			"status": string,
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
401	5	You do not have permission to view DispatchTasks.
401	5	You do not have permission to view Assets.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company containing the DispatchTasks was not found.

GET/dispatch/jobs?includeDeleted=boolean&includeArchive=boolean&limit=number&after=string&before=string

This request is an alias of /companies/{your-company-id}/assets/dispatch/jobs?{keys=values} (when No at least query-string key/value is given) or /companies/{your-company-id}/assets/dispatch/jobs (when No query-string parameters are given).

URL Parameters

Parameter	Type	Required	Default	Description
after	datetime	optional		When using , sets the earliest objects (by dts) to retrieve from the archive.
before	datetime	optional		When using , sets the most recent objects (by dts) to retrieve from the archive.
includeArchive	boolean	optional	`false`	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	`false`	False by default, but when true the command will also return deleted objects.
limit	uint16	optional		When using , sets the maximum number of objects retrieved from the archive.
your-company-id	uint64	aliased	`{your-company-id}`	Your own Company's identifier.

PATCH/dispatch/jobs

Creates a new or updates an existing DispatchJob.

HTTP Request body description

Property	Type	Required	Description
dispatchJob	Object.<string, ?>	always	The details of a DispatchJob either for creation or update.
dispatchJob.asset	uint64?	optional	The identifier of the Asset assigned to the DispatchJob.
dispatchJob.attachments	Array.<uint64> for values see: Document.id	optional	A list of Document identifiers to attach to the DispatchJob.
dispatchJob.company	uint64?	create	The identifier of the Company to which the DispatchJob belongs. After creation, this value is read-only.
dispatchJob.forms	Array.<uint64> for values see: FormResult.id	optional	A list of FormResult identifiers to attach to the DispatchJob.
dispatchJob.id	uint64?	update	The unique identifier of the DispatchJob you want to update.
dispatchJob.instructions	string	optional	Instructions for the driver to help them complete the DispatchJob. Such as which door to use, a buzz code to enter the facility, etc...
dispatchJob.labels	Array.<codified> for values see: LabelStyle.code	optional	A list of codified label names used to relate (unassigned) DispatchJobs to Assets.
dispatchJob.name	string maximum-length: 100	create	Name for the DispatchJob.
dispatchJob.priority	DispatchJobPriority?	optional	The importance of the DispatchJob when scheduling for an asset.
dispatchJob.references	Object.<string, string>	optional	A custom field used to refer the DispatchJob to an external system. Examples are a work order, pick-up, waybill, etc... If value is null, the field is removed from the DispatchJob. If a new value or null is not provided for a current attribute, no change is made.
dispatchJob.steps	Array.<ParamDispatchStep>	create	A list of coordinates to visit in order to carry out the work for the DispatchJob.
dispatchJob.v	Array.<int32>	optional
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"dispatchJob": {
		"asset": number,
		"attachments": [
			number
		],
		"company": number,
		"forms": [
			number
		],
		"id": number,
		"instructions": string,
		"labels": [
			string
		],
		"name": string,
		"priority": string,
		"references": {
			string: string
		},
		"steps": [
			{
				"address": string,
				"duration": string,
				"eta": string,
				"id": number,
				"latlng": {
					"lat": number,
					"lng": number
				},
				"name": string,
				"place": number,
				"signature": boolean
			}
		],
		"v": [
			number
		]
	},
	"reqId": number
}

Response description

Property	Type	Description
dispatchJob	RespIdCompany	The id, owning Company id and owning Asset id of the object requested/created.
dispatchJob.company	uint64	Identifier of the Company to which this object belongs.
dispatchJob.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"dispatchJob": {
		"company": number,
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a dispatchJob object, or it is invalid.
400	3	Not enough keys exist in the dispatchJob object.
400	3	The request contains an invalid dispatchJob.steps array.
400	3	The request contains an invalid dispatchJob.references object.
400	3	The request contains an invalid dispatchJob.attachments array.
400	3	The request contains an invalid dispatchJob.forms array.
400	3	During create: When creating a new DispatchJob, a name was not given, or was blank.
400	3	During create: When creating a new DispatchJob, company was not given.
400	3	During create: When creating a new DispatchJob, not enough steps were given.
400	3	During create: When creating a new DispatchJob, a place, a latlng, or an address must be given for each step.
400	3	During update: When updating a DispatchJob, the new name cannot be blank.
400	3	During update: When updating a DispatchJob, not enough v values were given.
400	3	During update: When updating a DispatchJob, latlng cannot be set to null.
400	3	The dispatchJob.priority value is not a known DispatchJobPriority. Returns an ErrorDetailEnum as the `errorDetails`.
400	3	When adding a step, the ParamDispatchStep.name was not given, or was blank, and a ParamDispatchStep.place was also not given. Returns an ErrorDetailInput as the `errorDetails`.
400	3	The ParamDispatchStep.eta value is invalid. Returns an ErrorDetailInput as the `errorDetails`.
400	3	The ParamDispatchStep.duration value is invalid. Returns an ErrorDetailInput as the `errorDetails`.
400	3	The ParamDispatchStep.place value is invalid. Returns an ErrorDetailInput as the `errorDetails`.
400	3	The ParamDispatchStep.latlng value is invalid. Returns an ErrorDetailInput as the `errorDetails`.
400	3	The ParamDispatchStep.signature value is invalid. Returns an ErrorDetailInput as the `errorDetails`.
400	3	Too many DispatchJob steps were given. Returns an ErrorDetailMinMax as the `errorDetails`.
400	3	Too many DispatchJob references were given. Returns an ErrorDetailMinMax as the `errorDetails`.
400	3	Too many DispatchJob attachements and forms were given. Returns an ErrorDetailMinMax as the `errorDetails`.
401	5	You do not have permission to view the Asset to which the DispatchJob belongs.
401	5	During create: You do not have permission to create new DispatchJobs.
401	5	During update: You do not have permission to update DispatchJobs.
400	6	During update: When updating a DispatchJob, the wrong version key(s) were given.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	20	The Asset to which this DispatchJob is assigned was not found.
404	40	The Place being given for the DispatchJob was not found.
401	71	During update: Changing the labels on this DispatchJob in the requested way would grant you elevated access to it. Returns an ErrorDetailEscalation as the `errorDetails`.
404	81	When giving only an address (not a Place or ParamDispatchStep.latlng), the address could not be geocoded.
404	81	When giving only an address (not a Place or ParamDispatchStep.latlng), the address was not street-level accurate enough. Returns an ErrorDetailExternals as the `errorDetails`.
403	96	The Asset to which this DispatchJob is assigned is suspended. Before sending or updating DispatchJobs for a Asset, it must be reactivated.
404	124	One or more of the given attachments could not be found. Returns an ErrorDetailBadIds as the `errorDetails`.
409	130	The dispatchJob.asset doesn't belong to the same Company as this DispatchJob
409	130	The dispatchJob.asset doesn't have any matching labels with this DispatchJob.
409	130	When adding a step, the order of DispatchStepStatus.completed DispatchJob.steps cannot be changed.
409	130	During update: When updating a DispatchJob, you cannot change the Company.
409	130	During update: When updating a DispatchJob, you cannot change the Asset to which it is assigned if any of the steps are underway.
409	130	During update: One or more of the DispatchJob.steps is DispatchStepStatus.completed and is being removed.
409	130	During update: There are too many combined dispatchJob.references after adding the newly given keys. Returns an ErrorDetailMinMax as the `errorDetails`.
404	136	One or more of the given FormResults could not be found. Returns an ErrorDetailBadIds as the `errorDetails`.
404	139	During update: The DispatchJob was not found.

DELETE/dispatch/jobs

Deletes an existing DispatchJob.

Response description

Property	Type	Description
dispatchJob	RespDeleted	The id, owning Asset id, owning Company id, and deleted state.
dispatchJob.company	uint64	Identifier of the Company to which this object belongs.
dispatchJob.deleted	boolean	Flag showing if the object is deleted.
dispatchJob.id	uint64?	Identifier given as input for the command.
dispatchJob.v	Array.<uint32>
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"dispatchJob": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a dispatchJob object, or it is invalid.
400	3	The dispatchJob object does not contain an id, or it is invalid.
401	5	You do not have permission to delete DispatchJobs.
401	5	You do not have permission to view the associated Asset.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	20	The DispatchJob was found, but the associated Asset was not found.
403	96	The DispatchJob was found, but the associated Asset is suspended. Before using any Asset resources, it must be reactivated.
404	139	The DispatchJob was not found by its unique identifier.

GET/dispatch/jobs/{jobId}?includeDeleted=boolean

Gets details of the specified DispatchJob.

URL Parameters

Parameter	Type	Required	Description
includeDeleted	boolean	optional	False by default, but when true the command will also return deleted objects.
jobId	uint64	required	Unique identifier of the DispatchJob.

Response description

Property	Type	Description
dispatchJob	DispatchJob	The requested DispatchJob.
dispatchJob.asset	uint64? see: Asset.id	The Asset to which this job belongs. This value is null when unassigned.
dispatchJob.attachments	Array.<uint64> maximum-count: 10 for values see: Document.id	A list of hosted Document identifiers attached to this job.
dispatchJob.company	uint64 see: Company.id	The company to which this job belongs.
dispatchJob.created	datetime	When this job was originally created.
dispatchJob.driver	string	Clocked-in driver name who made the update. Null if not clocked-in, or no changes have been made.
dispatchJob.forms	Array.<uint64> maximum-count: 10 for values see: FormResult.id	A list of hosted FormResult identifiers attached to this job.
dispatchJob.id	uint64	Unique identifier of this job.
dispatchJob.instructions	string	Instructions (filled out by dispatcher) for the field-employee to help them complete the job.
dispatchJob.labels	Array.<codified> for values see: LabelStyle.code	Codified label names used to relate (unassigned) jobs to Assets.
dispatchJob.name	string maximum-length: 100	A name for the work needed to be performed.
dispatchJob.priority	DispatchJobPriority	The importance of this job when scheduling for an asset.
dispatchJob.processedUtc	datetime	When the was change procesed.
dispatchJob.references	Object.<string, string> maximum-count: 10 maximum-length of keys: 20 maximum-length of values: 100	Name/value collections of custom fields used to refer to external systems.
dispatchJob.steps	Array.<DispatchStep>	A list of coordinates to visit in order to carry out the work for this job.
dispatchJob.tags	Array.<codified> for values see: LabelStyle.code	The codified status tag names reflecting the conditions of this job.
dispatchJob.updated		by: login, from: monster
dispatchJob.v	Array.<uint32>	Object version keys used to validate synchronization for all object properties.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"dispatchJob": {
		"asset": number,
		"attachments": [
			number
		],
		"company": number,
		"created": string,
		"driver": string,
		"forms": [
			number
		],
		"id": number,
		"instructions": string,
		"labels": [
			string
		],
		"name": string,
		"priority": string,
		"processedUtc": string,
		"references": {
			string: string
		},
		"steps": [
			{
				"address": string,
				"duration": string,
				"eta": string,
				"id": number,
				"latlng": {
					"lat": number,
					"lng": number
				},
				"name": string,
				"notes": string,
				"place": number,
				"signatory": string,
				"signature": boolean,
				"states": {
					string: {
						"latlng": {
							"lat": number,
							"lng": number
						},
						"updated": string
					}
				}
			}
		],
		"tags": [
			string
		],
		"updated": {
		},
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a dispatchJob object, or it is invalid.
400	3	The dispatchJob object does not contain an id, or it is invalid.
401	5	You do not have permission to view this DispatchJob.
401	5	You do not have permission to view the associated Asset.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	20	The DispatchJob was found, but the associated asset was not found.
403	96	The DispatchJob was found, but the associated asset is suspended. Before using any asset resources, it must be reactivated.
404	139	The DispatchJob was not found by its unique identifier.

PUT/dispatch/jobs/{jobId}

Completes or modifies an existing DispatchJob from a driver's perspective. This can be used by dispatchers to accomodate thrid-party delivery systems, or correcting errors from drivers.

URL Parameters

Parameter	Type	Required	Description
jobId	uint64?	optional

HTTP Request body description

Property	Type	Required	Description
dispatchJob	Object.<string, ?>	always	The details of a DispatchJob either for creation or update.
dispatchJob.driver	string	optional	Name of the driver who completed the DispatchJob.
dispatchJob.id	uint64	always	The unique identifier of the DispatchJob you want to update.
dispatchJob.steps	Array.<ParamDispatchStepChange>	optional	A list of notes and signatories from the completion of the DispatchJob.
dispatchJob.tags	Array.<codified> for values see: LabelStyle.code	optional	The codified status tag names reflecting the conditions of the DispatchJob.
dispatchJob.v	Array.<int32>	optional
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"dispatchJob": {
		"driver": string,
		"id": number,
		"steps": [
			{
				"id": number,
				"notes": string,
				"signatory": string,
				"status": string
			}
		],
		"tags": [
			string
		],
		"v": [
			number
		]
	},
	"reqId": number
}

Response description

Property	Type	Description
dispatchJob	RespIdCompany	The id, owning Company id and owning Asset id of the object requested/created.
dispatchJob.company	uint64	Identifier of the Company to which this object belongs.
dispatchJob.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"dispatchJob": {
		"company": number,
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a dispatchJob object, or it is invalid.
400	3	Not enough keys exist in the dispatchJob object.
400	3	The dispatchJob.id is invalid.
400	3	The dispatchJob does not have enough `v` values.
400	3	One or more of the dispatchJob.steps array values is not an object.
400	3	One or more of the dispatchJob.steps has an invalid `id`.
400	3	One or more of the dispatchJob.steps has an invalid `status`.
400	3	The dispatchJob.steps contains duplicate `id`s. Returns an ErrorDetailBadIds as the `errorDetails`.
401	5	You do not have permission to update the DispatchJob.
401	5	You do not have permission to view the Asset to which the DispatchJob belongs.
400	6	When updating a DispatchJob, the wrong version key(s) were given.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
409	130	One or more of the dispatchJob.steps are DispatchStepStatus.completed and cannot be changed.
409	130	One or more of the dispatchJob.steps has a more advanced lifetime status than a preceding step.
409	130	The order of DispatchStepStatus.completed DispatchJob.steps cannot be changed.
409	130	A step was marked DispatchStepStatus.completed, but a DispatchStep.signature is required and the ParamDispatchStepChange.signatory was not given.
409	130	All dispatchJob.steps are already completed. Returns an ErrorDetailBadIds as the `errorDetails`.
409	130	There are too many dispatchJob.steps. Returns an ErrorDetailMinMax as the `errorDetails`.
404	139	The DispatchJob was not found.

POST/dispatch/jobs/{jobId}

Creates a new or updates an existing DispatchJob.

URL Parameters

Parameter	Type	Required	Description
jobId	uint64?	optional	Unique identifier of the DispatchJob. This value is optional, and ignored by the command.

HTTP Request body description

Property	Type	Required	Description
dispatchJob	Object.<string, ?>	always	The details of a DispatchJob either for creation or update.
dispatchJob.asset	uint64?	optional	The identifier of the Asset assigned to the DispatchJob.
dispatchJob.attachments	Array.<uint64> for values see: Document.id	optional	A list of Document identifiers to attach to the DispatchJob.
dispatchJob.company	uint64?	create	The identifier of the Company to which the DispatchJob belongs. After creation, this value is read-only.
dispatchJob.forms	Array.<uint64> for values see: FormResult.id	optional	A list of FormResult identifiers to attach to the DispatchJob.
dispatchJob.id	uint64?	update	The unique identifier of the DispatchJob you want to update.
dispatchJob.instructions	string	optional	Instructions for the driver to help them complete the DispatchJob. Such as which door to use, a buzz code to enter the facility, etc...
dispatchJob.labels	Array.<codified> for values see: LabelStyle.code	optional	A list of codified label names used to relate (unassigned) DispatchJobs to Assets.
dispatchJob.name	string maximum-length: 100	create	Name for the DispatchJob.
dispatchJob.priority	DispatchJobPriority?	optional	The importance of the DispatchJob when scheduling for an asset.
dispatchJob.references	Object.<string, string>	optional	A custom field used to refer the DispatchJob to an external system. Examples are a work order, pick-up, waybill, etc... If value is null, the field is removed from the DispatchJob. If a new value or null is not provided for a current attribute, no change is made.
dispatchJob.steps	Array.<ParamDispatchStep>	create	A list of coordinates to visit in order to carry out the work for the DispatchJob.
dispatchJob.v	Array.<int32>	optional
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"dispatchJob": {
		"asset": number,
		"attachments": [
			number
		],
		"company": number,
		"forms": [
			number
		],
		"id": number,
		"instructions": string,
		"labels": [
			string
		],
		"name": string,
		"priority": string,
		"references": {
			string: string
		},
		"steps": [
			{
				"address": string,
				"duration": string,
				"eta": string,
				"id": number,
				"latlng": {
					"lat": number,
					"lng": number
				},
				"name": string,
				"place": number,
				"signature": boolean
			}
		],
		"v": [
			number
		]
	},
	"reqId": number
}

Response description

Property	Type	Description
dispatchJob	RespIdCompany	The id, owning Company id and owning Asset id of the object requested/created.
dispatchJob.company	uint64	Identifier of the Company to which this object belongs.
dispatchJob.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"dispatchJob": {
		"company": number,
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a dispatchJob object, or it is invalid.
400	3	Not enough keys exist in the dispatchJob object.
400	3	The request contains an invalid dispatchJob.steps array.
400	3	The request contains an invalid dispatchJob.references object.
400	3	The request contains an invalid dispatchJob.attachments array.
400	3	The request contains an invalid dispatchJob.forms array.
400	3	During create: When creating a new DispatchJob, a name was not given, or was blank.
400	3	During create: When creating a new DispatchJob, company was not given.
400	3	During create: When creating a new DispatchJob, not enough steps were given.
400	3	During create: When creating a new DispatchJob, a place, a latlng, or an address must be given for each step.
400	3	During update: When updating a DispatchJob, the new name cannot be blank.
400	3	During update: When updating a DispatchJob, not enough v values were given.
400	3	During update: When updating a DispatchJob, latlng cannot be set to null.
400	3	The dispatchJob.priority value is not a known DispatchJobPriority. Returns an ErrorDetailEnum as the `errorDetails`.
400	3	When adding a step, the ParamDispatchStep.name was not given, or was blank, and a ParamDispatchStep.place was also not given. Returns an ErrorDetailInput as the `errorDetails`.
400	3	The ParamDispatchStep.eta value is invalid. Returns an ErrorDetailInput as the `errorDetails`.
400	3	The ParamDispatchStep.duration value is invalid. Returns an ErrorDetailInput as the `errorDetails`.
400	3	The ParamDispatchStep.place value is invalid. Returns an ErrorDetailInput as the `errorDetails`.
400	3	The ParamDispatchStep.latlng value is invalid. Returns an ErrorDetailInput as the `errorDetails`.
400	3	The ParamDispatchStep.signature value is invalid. Returns an ErrorDetailInput as the `errorDetails`.
400	3	Too many DispatchJob steps were given. Returns an ErrorDetailMinMax as the `errorDetails`.
400	3	Too many DispatchJob references were given. Returns an ErrorDetailMinMax as the `errorDetails`.
400	3	Too many DispatchJob attachements and forms were given. Returns an ErrorDetailMinMax as the `errorDetails`.
401	5	You do not have permission to view the Asset to which the DispatchJob belongs.
401	5	During create: You do not have permission to create new DispatchJobs.
401	5	During update: You do not have permission to update DispatchJobs.
400	6	During update: When updating a DispatchJob, the wrong version key(s) were given.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	20	The Asset to which this DispatchJob is assigned was not found.
404	40	The Place being given for the DispatchJob was not found.
401	71	During update: Changing the labels on this DispatchJob in the requested way would grant you elevated access to it. Returns an ErrorDetailEscalation as the `errorDetails`.
404	81	When giving only an address (not a Place or ParamDispatchStep.latlng), the address could not be geocoded.
404	81	When giving only an address (not a Place or ParamDispatchStep.latlng), the address was not street-level accurate enough. Returns an ErrorDetailExternals as the `errorDetails`.
403	96	The Asset to which this DispatchJob is assigned is suspended. Before sending or updating DispatchJobs for a Asset, it must be reactivated.
404	124	One or more of the given attachments could not be found. Returns an ErrorDetailBadIds as the `errorDetails`.
409	130	The dispatchJob.asset doesn't belong to the same Company as this DispatchJob
409	130	The dispatchJob.asset doesn't have any matching labels with this DispatchJob.
409	130	When adding a step, the order of DispatchStepStatus.completed DispatchJob.steps cannot be changed.
409	130	During update: When updating a DispatchJob, you cannot change the Company.
409	130	During update: When updating a DispatchJob, you cannot change the Asset to which it is assigned if any of the steps are underway.
409	130	During update: One or more of the DispatchJob.steps is DispatchStepStatus.completed and is being removed.
409	130	During update: There are too many combined dispatchJob.references after adding the newly given keys. Returns an ErrorDetailMinMax as the `errorDetails`.
404	136	One or more of the given FormResults could not be found. Returns an ErrorDetailBadIds as the `errorDetails`.
404	139	During update: The DispatchJob was not found.

DELETE/dispatch/jobs/{jobId}

Deletes an existing DispatchJob.

URL Parameters

Parameter	Type	Required	Description
jobId	uint64	required	Unique identifier of the DispatchJob.

Response description

Property	Type	Description
dispatchJob	RespDeleted	The id, owning Asset id, owning Company id, and deleted state.
dispatchJob.company	uint64	Identifier of the Company to which this object belongs.
dispatchJob.deleted	boolean	Flag showing if the object is deleted.
dispatchJob.id	uint64?	Identifier given as input for the command.
dispatchJob.v	Array.<uint32>
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"dispatchJob": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a dispatchJob object, or it is invalid.
400	3	The dispatchJob object does not contain an id, or it is invalid.
401	5	You do not have permission to delete DispatchJobs.
401	5	You do not have permission to view the associated Asset.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	20	The DispatchJob was found, but the associated Asset was not found.
403	96	The DispatchJob was found, but the associated Asset is suspended. Before using any Asset resources, it must be reactivated.
404	139	The DispatchJob was not found by its unique identifier.

PATCH/dispatch/jobs/{jobId}/restore

Restores a deleted DispatchJob.

URL Parameters

Parameter	Type	Required	Description
jobId	uint64	required	Unique identifier of the DispatchJob.

HTTP Request body description

Property	Type	Required	Description
dispatchJob	ParamId	always	Identifier object to contain the DispatchJob's identifier.
dispatchJob.id	uint64	always	Identifier given as input for the command.
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"dispatchJob": {
		"id": number
	},
	"reqId": number
}

Response description

Property	Type	Description
dispatchJob	RespDeleted	The id, owning Asset id, owning Company id, and deleted state.
dispatchJob.company	uint64	Identifier of the Company to which this object belongs.
dispatchJob.deleted	boolean	Flag showing if the object is deleted.
dispatchJob.id	uint64?	Identifier given as input for the command.
dispatchJob.v	Array.<uint32>
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"dispatchJob": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a dispatchJob object, or it is invalid.
400	3	The dispatchJob object does not contain an id, or it is invalid.
401	5	You do not have permission to create DispatchJobs.
401	5	You do not have permission to view the associated Asset.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	139	The DispatchJob was not found by its unique identifier.
400	140	The DispatchJob was found, but is not marked as deleted.

GET/dispatch/jobs?labels={string}&includeDeleted=boolean&includeArchive=boolean&limit=number&after=string&before=string

This request is an alias of /companies/{your-company-id}/assets/dispatch/jobs?labels={labels}.

URL Parameters

Parameter	Type	Required	Default	Description
after	datetime	optional		When using , sets the earliest objects (by dts) to retrieve from the archive.
before	datetime	optional		When using , sets the most recent objects (by dts) to retrieve from the archive.
includeArchive	boolean	optional	`false`	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	`false`	False by default, but when true the command will also return deleted objects.
labels	string	optional		Labels to match the DispatchJob.
limit	uint16	optional		When using , sets the maximum number of objects retrieved from the archive.
your-company-id	uint64	aliased	`{your-company-id}`	Your own Company's identifier.

GET/dispatch/tasks?includeDeleted=boolean&includeArchive=boolean&limit=number&after=string&before=string

This request is an alias of /companies/{your-company-id}/assets/dispatch/tasks?{keys=values} (when No at least query-string key/value is given) or /companies/{your-company-id}/assets/dispatch/tasks (when No query-string parameters are given).

URL Parameters

Parameter	Type	Required	Default	Description
after	datetime	optional		When using , sets the earliest objects (by dts) to retrieve from the archive.
before	datetime	optional		When using , sets the most recent objects (by dts) to retrieve from the archive.
includeArchive	boolean	optional	`false`	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	`false`	False by default, but when true the command will also return deleted objects.
limit	uint16	optional		When using , sets the maximum number of objects retrieved from the archive.
your-company-id	uint64	aliased	`{your-company-id}`	Your own Company's identifier.

PATCH/dispatch/tasks

Creates a new or updates an existing DispatchTask.

HTTP Request body description

Property	Type	Required	Description
dispatchTask	Object.<string, ?>	always	The details of a DispatchTask either for creation or update.
dispatchTask.address	string	create (conditional)	The street address of this DispatchTask. Condition: You must provide a `place`, a `latlng`, or an `address`. Note: If you ommit the `address`, the geocoder attempts to populate the field, but will not return an error if it fails.
dispatchTask.asset	uint64?	create	The identifier of the Asset assigned to this DispatchTask.
dispatchTask.attachments	Array.<uint64> for values see: Document.id	optional	A list of Document identifiers to attach to this DispatchTask for both driver and dispatcher review.
dispatchTask.duration	timespan	optional	The duration on site, or how much time is expected to complete the DispatchTask. Used to help calculate other DispatchTask ETAs when routing is performed.
dispatchTask.eta	datetime	optional	Estimated time of arrival.
dispatchTask.id	uint64?	update	The unique identifier of the DispatchTask you want to update.
dispatchTask.instructions	string	optional	Instructions for the driver to help them complete the DispatchTask. Such as which door to use, a buzz code to enter the facility, etc...
dispatchTask.latlng	LatLng	create (conditional)	The lat/long coordinates of the street address. Condition: You must provide a `place`, a `latlng`, or an `address`. Note: If you invoke the geocoder, the `address` is also replaced with the geocoded value.
dispatchTask.latlng.lat	double	optional	Latitude
dispatchTask.latlng.lng	double	optional	Longitude
dispatchTask.name	string maximum-length: 100	create	Name for the DispatchTask.
dispatchTask.notes	string	optional	Notes completed by the driver about the DispatchTask. Such as service notes, damaged goods upon pick-up, etc...
dispatchTask.place	uint64?	create (conditional)	An optional identifier of a Place for this DispatchTask. Using a Place makes detecting the "arrived" status more reliable. Condition: You must provide a `place`, a `latlng`, or an `address`. Note: If you invoke the geocoder, the `address` is also replaced with the geocoded value.
dispatchTask.references	Object.<string, string>	optional	A custom field used to refer this DispatchTask an external system. Examples are a work order, pick-up, waybill, etc... If value is null, the field is removed from the DispatchTask. If a new value or null is not provided for a current attribute, no change is made.
dispatchTask.status	TaskStatus?	optional	DispatchTasks have a lifetime and each status represents a DispatchTask's progress through it's life.
dispatchTask.v	Array.<int32>	optional
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"dispatchTask": {
		"address": string,
		"asset": number,
		"attachments": [
			number
		],
		"duration": string,
		"eta": string,
		"id": number,
		"instructions": string,
		"latlng": {
			"lat": number,
			"lng": number
		},
		"name": string,
		"notes": string,
		"place": number,
		"references": {
			string: string
		},
		"status": string,
		"v": [
			number
		]
	},
	"reqId": number
}

Response description

Property	Type	Description
dispatchTask	RespIdAsset	The id, owning Asset id, and owning Company id of the object requested/created.
dispatchTask.asset	uint64	Identifier of the Asset to which this object belongs
dispatchTask.company	uint64	Identifier of the Company to which this object belongs.
dispatchTask.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"dispatchTask": {
		"asset": number,
		"company": number,
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a dispatchTask object, or it is invalid.
400	3	Not enough keys exist in the dispatchTask object.
400	3	Too many DispatchTask references were given.
400	3	Too many DispatchTask attachements were given.
400	3	The request contains an invalid dispatchTask.references object.
400	3	The request contains an invalid dispatchTask.place id.
400	3	The request contains an invalid dispatchTask.attachments array.
400	3	The request contains an invalid dispatchTask.latlng object.
400	3	The request contains an invalid dispatchTask.eta date time.
400	3	The request contains an invalid dispatchTask.duration timespan.
400	3	The request contains an invalid dispatchTask.status TaskStatus.
400	3	During create: When creating a new DispatchTask, a name was not given, or was blank.
400	3	During create: When creating a new DispatchTask, an asset was not given.
400	3	During create: When creating a new DispatchTask, a place, a latlng, or an address must be given.
400	3	During update: When updating a DispatchTask, the new name cannot be blank.
400	3	During update: When updating a DispatchTask, not enough v values were given.
400	3	During update: There are too many combined dispatchTask.references after adding the newly given keys. Returns an ErrorDetailMinMax as the `errorDetails`.
401	5	You do not have permission to view the Asset to which the DispatchTask belongs.
401	5	During create: You do not have permission to create new DispatchTasks.
401	5	During update: You do not have permission to update DispatchTasks.
400	6	During update: When updating a DispatchTask, the wrong version key(s) were given.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	20	The Asset to which this DispatchTask is assigned was not found.
404	40	The Place being given for the DispatchTask was not found.
404	64	The DispatchTask was not found.
404	64	The DispatchTask was cancelled.
404	81	When giving only an address (not a Place or dispatchTask.latlng), the address could not be geocoded.
404	81	When giving only an address (not a Place or dispatchTask.latlng), the address was not street-level accurate enough. Returns an ErrorDetailExternals as the `errorDetails`.
403	96	The Asset to which this DispatchTask is assigned is suspended. Before sending or updating DispatchTasks for an Asset, it must be reactivated.
404	124	One or more of the given attachments could not be found. Returns an ErrorDetailBadIds as the `errorDetails`.
409	130	During update: When updating a DispatchTask, you cannot change the Asset to which it is assigned.

DELETE/dispatch/tasks

Deletes an existing DispatchTask.

Response description

Property	Type	Description
dispatchTask	RespAssetDeleted	The id, owning Asset id, owning Company id, and deleted state.
dispatchTask.asset	uint64	Identifier of the Asset to which this object belongs.
dispatchTask.company	uint64	Identifier of the Company to which this object belongs.
dispatchTask.deleted	boolean	Flag showing if the object is deleted.
dispatchTask.id	uint64?	Identifier given as input for the command.
dispatchTask.v	Array.<uint32>
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"dispatchTask": {
		"asset": number,
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a dispatchTask object, or it is invalid.
400	3	The dispatchTask object does not contain an id, or it is invalid.
401	5	You do not have permission to delete DispatchTasks.
401	5	You do not have permission to view the associated Asset.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	20	The DispatchTask was found, but the associated Asset was not found.
404	64	The DispatchTask was not found by its unique identifier.
403	96	The DispatchTask was found, but the associated Asset is suspended. Before using any Asset resources, it must be reactivated.

GET/dispatch/tasks/{taskId}?includeDeleted=boolean

Gets details of the specified DispatchTask.

URL Parameters

Parameter	Type	Required	Description
includeDeleted	boolean	optional	False by default, but when true the command will also return deleted objects.
taskId	uint64	required	Unique identifier of the DispatchTask.

Response description

Property	Type	Description
dispatchTask Deprecated	DispatchTask	The requested DispatchTask. Use DispatchJob instead.
dispatchTask.address	string maximum-length: 500	The street address of where the task must be completed.
dispatchTask.arrived	datetime	The date/time stamp of when the asset arrived at this task.
dispatchTask.asset	uint64 see: Asset.id	The asset to which this task belongs.
dispatchTask.attachments	Array.<uint64> maximum-count: 10 for values see: Document.id	A list of hosted Document identifiers attached to this task.
dispatchTask.company	uint64 see: Company.id	The company to which this task belongs.
dispatchTask.completed	datetime	The date/time stamp of when this task was completed.
dispatchTask.created	datetime	When this task was created.
dispatchTask.duration	timespan	The optional expected duration of the work for this task.
dispatchTask.eta	datetime	The optional estimated time of arrival for the asset.
dispatchTask.id	uint64	Unique identifier of this task.
dispatchTask.instructions	string	Instructions (filled out by dispatcher) for the field-employee to help them completed the task.
dispatchTask.latlng	LatLng	The lat/long coordinates of where the task must be completed.
dispatchTask.latlng.lat	double	Latitude
dispatchTask.latlng.lng	double	Longitude
dispatchTask.name	string maximum-length: 100	The name of this task or the work needed to be performed.
dispatchTask.notes	string	Notes about the status of the work filled in by field-employee.
dispatchTask.place	uint64? see: Place.id	An optional place which can be used as a template instead of providing lat/long coordinates and a street address.
dispatchTask.processedUtc	datetime	When the was change procesed.
dispatchTask.reference Deprecated	string maximum-length: 100	A custom field used to refer to an external system. Examples are a work order, pick-up, waybill, etc... Use dispatchTask.references[DispatchTask.REFERENCE] instead.
dispatchTask.references	Object.<string, string> maximum-count: 10 maximum-length of keys: 20 maximum-length of values: 100	Name/value collections of custom fields used to refer to external systems.
dispatchTask.signatory	string maximum-length: 100	The name of the person who signed the task's completion.
dispatchTask.signature	boolean	Indicates whether the task has a signature.
dispatchTask.status Deprecated	TaskStatus	The progress of this task. Use DispatchStepStatus instead.
dispatchTask.updated		by: login, from: monster
dispatchTask.v	Array.<uint32>	Object version keys used to validate synchronization for all object properties.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"dispatchTask": {
		"address": string,
		"arrived": string,
		"asset": number,
		"attachments": [
			number
		],
		"company": number,
		"completed": string,
		"created": string,
		"duration": string,
		"eta": string,
		"id": number,
		"instructions": string,
		"latlng": {
			"lat": number,
			"lng": number
		},
		"name": string,
		"notes": string,
		"place": number,
		"processedUtc": string,
		"reference": string,
		"references": {
			string: string
		},
		"signatory": string,
		"signature": boolean,
		"status": string,
		"updated": {
		},
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a dispatchTask object, or it is invalid.
400	3	The dispatchTask object does not contain an id, or it is invalid.
401	5	You do not have permission to view DispatchTasks.
401	5	You do not have permission to view the associated Asset.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	20	The DispatchTask was found, but the associated asset was not found.
404	64	The DispatchTask was not found by its unique identifier.
403	96	The DispatchTask was found, but the associated asset is suspended. Before using any asset resources, it must be reactivated.

POST/dispatch/tasks/{taskId}

Creates a new or updates an existing DispatchTask.

URL Parameters

Parameter	Type	Required	Description
taskId	uint64?	optional	Unique identifier of the DispatchTask. This value is optional, and ignored by the command.

HTTP Request body description

Property	Type	Required	Description
dispatchTask	Object.<string, ?>	always	The details of a DispatchTask either for creation or update.
dispatchTask.address	string	create (conditional)	The street address of this DispatchTask. Condition: You must provide a `place`, a `latlng`, or an `address`. Note: If you ommit the `address`, the geocoder attempts to populate the field, but will not return an error if it fails.
dispatchTask.asset	uint64?	create	The identifier of the Asset assigned to this DispatchTask.
dispatchTask.attachments	Array.<uint64> for values see: Document.id	optional	A list of Document identifiers to attach to this DispatchTask for both driver and dispatcher review.
dispatchTask.duration	timespan	optional	The duration on site, or how much time is expected to complete the DispatchTask. Used to help calculate other DispatchTask ETAs when routing is performed.
dispatchTask.eta	datetime	optional	Estimated time of arrival.
dispatchTask.id	uint64?	update	The unique identifier of the DispatchTask you want to update.
dispatchTask.instructions	string	optional	Instructions for the driver to help them complete the DispatchTask. Such as which door to use, a buzz code to enter the facility, etc...
dispatchTask.latlng	LatLng	create (conditional)	The lat/long coordinates of the street address. Condition: You must provide a `place`, a `latlng`, or an `address`. Note: If you invoke the geocoder, the `address` is also replaced with the geocoded value.
dispatchTask.latlng.lat	double	optional	Latitude
dispatchTask.latlng.lng	double	optional	Longitude
dispatchTask.name	string maximum-length: 100	create	Name for the DispatchTask.
dispatchTask.notes	string	optional	Notes completed by the driver about the DispatchTask. Such as service notes, damaged goods upon pick-up, etc...
dispatchTask.place	uint64?	create (conditional)	An optional identifier of a Place for this DispatchTask. Using a Place makes detecting the "arrived" status more reliable. Condition: You must provide a `place`, a `latlng`, or an `address`. Note: If you invoke the geocoder, the `address` is also replaced with the geocoded value.
dispatchTask.references	Object.<string, string>	optional	A custom field used to refer this DispatchTask an external system. Examples are a work order, pick-up, waybill, etc... If value is null, the field is removed from the DispatchTask. If a new value or null is not provided for a current attribute, no change is made.
dispatchTask.status	TaskStatus?	optional	DispatchTasks have a lifetime and each status represents a DispatchTask's progress through it's life.
dispatchTask.v	Array.<int32>	optional
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"dispatchTask": {
		"address": string,
		"asset": number,
		"attachments": [
			number
		],
		"duration": string,
		"eta": string,
		"id": number,
		"instructions": string,
		"latlng": {
			"lat": number,
			"lng": number
		},
		"name": string,
		"notes": string,
		"place": number,
		"references": {
			string: string
		},
		"status": string,
		"v": [
			number
		]
	},
	"reqId": number
}

Response description

Property	Type	Description
dispatchTask	RespIdAsset	The id, owning Asset id, and owning Company id of the object requested/created.
dispatchTask.asset	uint64	Identifier of the Asset to which this object belongs
dispatchTask.company	uint64	Identifier of the Company to which this object belongs.
dispatchTask.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"dispatchTask": {
		"asset": number,
		"company": number,
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a dispatchTask object, or it is invalid.
400	3	Not enough keys exist in the dispatchTask object.
400	3	Too many DispatchTask references were given.
400	3	Too many DispatchTask attachements were given.
400	3	The request contains an invalid dispatchTask.references object.
400	3	The request contains an invalid dispatchTask.place id.
400	3	The request contains an invalid dispatchTask.attachments array.
400	3	The request contains an invalid dispatchTask.latlng object.
400	3	The request contains an invalid dispatchTask.eta date time.
400	3	The request contains an invalid dispatchTask.duration timespan.
400	3	The request contains an invalid dispatchTask.status TaskStatus.
400	3	During create: When creating a new DispatchTask, a name was not given, or was blank.
400	3	During create: When creating a new DispatchTask, an asset was not given.
400	3	During create: When creating a new DispatchTask, a place, a latlng, or an address must be given.
400	3	During update: When updating a DispatchTask, the new name cannot be blank.
400	3	During update: When updating a DispatchTask, not enough v values were given.
400	3	During update: There are too many combined dispatchTask.references after adding the newly given keys. Returns an ErrorDetailMinMax as the `errorDetails`.
401	5	You do not have permission to view the Asset to which the DispatchTask belongs.
401	5	During create: You do not have permission to create new DispatchTasks.
401	5	During update: You do not have permission to update DispatchTasks.
400	6	During update: When updating a DispatchTask, the wrong version key(s) were given.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	20	The Asset to which this DispatchTask is assigned was not found.
404	40	The Place being given for the DispatchTask was not found.
404	64	The DispatchTask was not found.
404	64	The DispatchTask was cancelled.
404	81	When giving only an address (not a Place or dispatchTask.latlng), the address could not be geocoded.
404	81	When giving only an address (not a Place or dispatchTask.latlng), the address was not street-level accurate enough. Returns an ErrorDetailExternals as the `errorDetails`.
403	96	The Asset to which this DispatchTask is assigned is suspended. Before sending or updating DispatchTasks for an Asset, it must be reactivated.
404	124	One or more of the given attachments could not be found. Returns an ErrorDetailBadIds as the `errorDetails`.
409	130	During update: When updating a DispatchTask, you cannot change the Asset to which it is assigned.

DELETE/dispatch/tasks/{taskId}

Deletes an existing DispatchTask.

URL Parameters

Parameter	Type	Required	Description
taskId	uint64	required	Unique identifier of the DispatchTask.

Response description

Property	Type	Description
dispatchTask	RespAssetDeleted	The id, owning Asset id, owning Company id, and deleted state.
dispatchTask.asset	uint64	Identifier of the Asset to which this object belongs.
dispatchTask.company	uint64	Identifier of the Company to which this object belongs.
dispatchTask.deleted	boolean	Flag showing if the object is deleted.
dispatchTask.id	uint64?	Identifier given as input for the command.
dispatchTask.v	Array.<uint32>
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"dispatchTask": {
		"asset": number,
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a dispatchTask object, or it is invalid.
400	3	The dispatchTask object does not contain an id, or it is invalid.
401	5	You do not have permission to delete DispatchTasks.
401	5	You do not have permission to view the associated Asset.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	20	The DispatchTask was found, but the associated Asset was not found.
404	64	The DispatchTask was not found by its unique identifier.
403	96	The DispatchTask was found, but the associated Asset is suspended. Before using any Asset resources, it must be reactivated.

PATCH/dispatch/tasks/{taskId}/restore

Restores a deleted DispatchTask.

URL Parameters

Parameter	Type	Required	Description
taskId	uint64	required	Unique identifier of the DispatchTask.

HTTP Request body description

Property	Type	Required	Description
dispatchTask	ParamId	always	Identifier object to contain the DispatchTask's identifier.
dispatchTask.id	uint64	always	Identifier given as input for the command.
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"dispatchTask": {
		"id": number
	},
	"reqId": number
}

Response description

Property	Type	Description
dispatchTask	RespAssetDeleted	The id, owning Asset id, owning Company id, and deleted state.
dispatchTask.asset	uint64	Identifier of the Asset to which this object belongs.
dispatchTask.company	uint64	Identifier of the Company to which this object belongs.
dispatchTask.deleted	boolean	Flag showing if the object is deleted.
dispatchTask.id	uint64?	Identifier given as input for the command.
dispatchTask.v	Array.<uint32>
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"dispatchTask": {
		"asset": number,
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a dispatchTask object, or it is invalid.
400	3	The dispatchTask object does not contain an id, or it is invalid.
401	5	You do not have permission to create DispatchTasks.
401	5	You do not have permission to view the associated Asset.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	20	The DispatchTask was found, but the associated Asset was not found.
404	64	The DispatchTask was not found by its unique identifier.
403	96	The DispatchTask was found, but the associated Asset is suspended. Before using any Asset resources, it must be reactivated.
400	100	The DispatchTask was found, but is not marked as deleted.

File Hosting

GET/assets/{assetId}/dashcams?after=string&before=string&limit=number&kind=DashcamDataType

Gets the list of dashcam metadata for the specified Asset.

URL Parameters

Parameter	Type	Required	Default	Description
after	datetime	optional	`"{28-days-ago}"`	A timestamp for the earliest DashcamData metadata to retrieve.
assetId	uint64	required		Unique identifier of the Asset.
before	datetime	optional	`"{now}"`	A timestamp for the most recent DashcamData metadata to retrieve.
kind	DashcamDataType?	optional		An optional filter available so that only a certain kind of DashcamData is returned.
limit	uint16?	optional	`1000`	A maximum number of DashcamData metadata to retrieve.

Response description

Property	Type	Description
asset	RespId	An object to contain the "id" of the Asset to which the array of dashcam image or video metadata belong.
asset.id	uint64?	Identifier given as input for the command.
dashcams	Array.<DashcamData>	The list of requested dashcam image or video metadata.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.
totals	Object.<DashcamDataType, HostedTotal>	Totals of hosted dashcam media as calculated at midnight.

Response structure

{
	"asset": {
		"id": number
	},
	"dashcams": [
		{
			"altitude": number,
			"asset": number,
			"bytes": number,
			"camera": number,
			"company": number,
			"end": string,
			"eventName": string,
			"fps": number,
			"guid": string,
			"heading": number,
			"kind": string,
			"latitude": number,
			"longitude": number,
			"provider": string,
			"size": {
				"height": number,
				"width": number
			},
			"speed": number,
			"start": string
		}
	],
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number,
	"totals": {
		string: {
			"bytes": number,
			"count": number,
			"newest": string,
			"oldest": string
		}
	}
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a valid after timestamp.
400	3	The request does not contain a valid before timestamp.
400	3	The request does not contain a asset object, or it is invalid.
400	3	The asset object does not contain an id, or it is invalid.
401	5	You do not have permission to view Providers.
401	5	You do not have permission to view the specified Asset.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	20	The Asset was not found by its unique identifier.
403	96	The Asset is suspended.

GET/assets/{assetId}/dashcams/live?camera=number

Gets the list of dashcam live metadata for the specified Asset.

URL Parameters

Parameter	Type	Required	Description
assetId	uint64	required	Unique identifier of the Asset.
camera	byte?	optional	Optional camera number when multiple cameras are installed.

Response description

Property	Type	Description
asset	RespId	An object to contain the "id" of the Asset to which the array of dashcam live image metadata belongs.
asset.id	uint64?	Identifier given as input for the command.
dashcams	Array.<DashcamDataLive>	The list of requested dashcam live image metadata.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"asset": {
		"id": number
	},
	"dashcams": [
		{
			"altitude": number,
			"asset": number,
			"bytes": number,
			"camera": number,
			"company": number,
			"dts": string,
			"heading": number,
			"kind": string,
			"latitude": number,
			"longitude": number,
			"provider": string,
			"size": {
				"height": number,
				"width": number
			},
			"speed": number
		}
	],
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a asset object, or it is invalid.
400	3	The asset object does not contain an id, or it is invalid.
401	5	You do not have permission to view Providers.
401	5	You do not have permission to view the specified Asset.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	20	The Asset was not found by its unique identifier.
403	96	The Asset is suspended.

GET/assets/{assetId}/forms?includeDeleted=boolean&includeArchive=boolean&limit=number&after=string&before=string

Gets the list of FormResults for the specified Asset.

URL Parameters

Parameter	Type	Required	Description
after	datetime	optional	When using , sets the earliest objects (by dts) to retrieve from the archive.
assetId	uint64	required	Unique identifier of the Asset.
before	datetime	optional	When using , sets the most recent objects (by dts) to retrieve from the archive.
includeArchive	boolean	optional	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	False by default, but when true, the command will also return deleted objects.
limit	uint16?	optional	When using , sets the maximum number of objects retrieved from the archive.

Response description

Property	Type	Description
asset	RespIdCompany	An object to contain the "id" of the Asset to which the array of FormResults belong.
asset.company	uint64	Identifier of the Company to which this object belongs.
asset.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
formResults	Array.<FormResult>	The list of requested FormResults.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"asset": {
		"company": number,
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"formResults": [
		{
			"asset": number,
			"company": number,
			"completed": string,
			"driver": string,
			"fields": {
				string: string
			},
			"id": number,
			"labels": [
				string
			],
			"latlng": {
				"lat": number,
				"lng": number
			},
			"name": string,
			"notes": string,
			"processedUtc": string,
			"template": number,
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a asset object, or it is invalid.
400	3	The asset object does not contain an id, or it is invalid.
401	5	You do not have permission to view FormResults.
401	5	You do not have permission to view the specified Asset.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	20	The Asset that owns these FormResults was not found.
403	96	The Asset that owns these FormResults is suspended. Before reading FormResults from an Asset, it must be reactivated.

GET/assets/{assetId}/forms?labels={string}&includeDeleted=boolean&includeArchive=boolean&limit=number&after=string&before=string

Gets the list of FormResults for the specified Asset.

URL Parameters

Parameter	Type	Required	Description
after	datetime	optional	When using , sets the earliest objects (by dts) to retrieve from the archive.
assetId	uint64	required	Unique identifier of the Asset.
before	datetime	optional	When using , sets the most recent objects (by dts) to retrieve from the archive.
includeArchive	boolean	optional	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	False by default, but when true, the command will also return deleted objects.
labels	string	required	Labels to match the FormResult.
limit	uint16?	optional	When using , sets the maximum number of objects retrieved from the archive.

Response description

Property	Type	Description
asset	RespIdCompany	An object to contain the "id" of the Asset to which the array of FormResults belong.
asset.company	uint64	Identifier of the Company to which this object belongs.
asset.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
formResults	Array.<FormResult>	The list of requested FormResults.
labels	Array.<string>	The labels given as input.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"asset": {
		"company": number,
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"formResults": [
		{
			"asset": number,
			"company": number,
			"completed": string,
			"driver": string,
			"fields": {
				string: string
			},
			"id": number,
			"labels": [
				string
			],
			"latlng": {
				"lat": number,
				"lng": number
			},
			"name": string,
			"notes": string,
			"processedUtc": string,
			"template": number,
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"labels": [
		string
	],
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a asset object, or it is invalid.
400	3	The asset object does not contain an id, or it is invalid.
400	3	The labels is not an array.
401	5	You do not have permission to view FormResults.
401	5	You do not have permission to view the specified Asset.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	20	The Asset that owns these FormResults was not found.
403	96	The Asset that owns these FormResults is suspended. Before reading FormResults from an Asset, it must be reactivated.

GET/companies/{companyId}/dashcams?after=string&before=string&limit=number&kind=DashcamDataType

Gets the list of dashcam image or video metadata for the specified Company.

URL Parameters

Parameter	Type	Required	Default	Description
after	datetime	optional	`"{28-days-ago}"`	A timestamp for the earliest DashcamData metadata to retrieve.
before	datetime	optional	`"{now}"`	A timestamp for the most recent DashcamData metadata to retrieve.
companyId	uint64	required		Unique identifier of the Company.
kind	DashcamDataType?	optional		An optional filter available so that only a certain kind of DashcamData is returned.
limit	uint16?	optional	`1000`	A maximum number of DashcamData metadata to retrieve.

Response description

Property	Type	Description
company	RespId	An object to contain the "id" of the Company to which the array of dashcam image or video metadata belong.
company.id	uint64?	Identifier given as input for the command.
dashcams	Array.<DashcamData>	The list of requested dashcam image or video metadata.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.
totals	Object.<DashcamDataType, HostedTotal>	Totals of hosted dashcam media as calculated at midnight.

Response structure

{
	"company": {
		"id": number
	},
	"dashcams": [
		{
			"altitude": number,
			"asset": number,
			"bytes": number,
			"camera": number,
			"company": number,
			"end": string,
			"eventName": string,
			"fps": number,
			"guid": string,
			"heading": number,
			"kind": string,
			"latitude": number,
			"longitude": number,
			"provider": string,
			"size": {
				"height": number,
				"width": number
			},
			"speed": number,
			"start": string
		}
	],
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number,
	"totals": {
		string: {
			"bytes": number,
			"count": number,
			"newest": string,
			"oldest": string
		}
	}
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a valid after timestamp.
400	3	The request does not contain a valid before timestamp.
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
401	5	You do not have permission to view any Assets or Providers in the given Company.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company was not found by its unique identifier.

GET/companies/{companyId}/dashcams/live?camera=number

Gets the list of dashcam live image metadata for the specified Company.

URL Parameters

Parameter	Type	Required	Description
camera	byte?	optional	Optional camera number when multiple cameras are installed.
companyId	uint64	required	Unique identifier of the Company.

Response description

Property	Type	Description
company	RespId	An object to contain the "id" of the Company to which the array of dashcam live image metadata belongs.
company.id	uint64?	Identifier given as input for the command.
dashcams	Array.<DashcamDataLive>	The list of requested dashcam live image metadata.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"company": {
		"id": number
	},
	"dashcams": [
		{
			"altitude": number,
			"asset": number,
			"bytes": number,
			"camera": number,
			"company": number,
			"dts": string,
			"heading": number,
			"kind": string,
			"latitude": number,
			"longitude": number,
			"provider": string,
			"size": {
				"height": number,
				"width": number
			},
			"speed": number
		}
	],
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
401	5	You do not have permission to view any Assets or Providers in the given Company.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company was not found by its unique identifier.

GET/companies/{companyId}/documents?includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

Gets the list of Documents for the specified Company.

URL Parameters

Parameter	Type	Required	Description
companyId	uint64	required	Unique identifier of the Company.
highest	uint64?	optional	When using , sets the largest valued id objects to retrieve.
includeArchive	boolean	optional	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	False by default, but when true, the command will also return deleted objects.
limit	uint16?	optional	When using , sets the maximum number of objects retrieved from the archive.
lowest	uint64?	optional	When using , sets the smallest valued id objects to retrieve.

Response description

Property	Type	Description
company	RespId	An object to contain the "id" of the Company to which the array of Documents belong.
company.id	uint64?	Identifier given as input for the command.
documents	Array.<Document>	The list of requested Documents.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"company": {
		"id": number
	},
	"documents": [
		{
			"bytes": number,
			"company": number,
			"expiry": string,
			"id": number,
			"mime": string,
			"name": string,
			"notes": string,
			"processedUtc": string,
			"references": {
				string: string
			},
			"src": string,
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
401	5	You do not have permission to view Documents for this Company.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company was not found by its unique identifier.

GET/companies/{companyId}/documents?{keys=values}?includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number&{keys=values}

Gets the list of Documents for the specified Company only if one of the specified Document.references fields match. If no references are specified, it will match any Document with no references. If a reference value is null, it will match any Document without that reference key.

URL Parameters

Parameter	Type	Required	Description
companyId	uint64	required	Unique identifier of the Company.
highest	uint64?	optional	When using , sets the largest valued id objects to retrieve.
includeArchive	boolean	optional	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	False by default, but when true, the command will also return deleted objects.
limit	uint16?	optional	When using , sets the maximum number of objects retrieved from the archive.
lowest	uint64?	optional	When using , sets the smallest valued id objects to retrieve.

Response description

Property	Type	Description
company	RespId	An object to contain the "id" of the Company to which the array of Documents belong.
company.id	uint64?	Identifier given as input for the command.
documents	Array.<Document>	The list of requested Documents.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
references	Object.<string, string>	The reference string given as input.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"company": {
		"id": number
	},
	"documents": [
		{
			"bytes": number,
			"company": number,
			"expiry": string,
			"id": number,
			"mime": string,
			"name": string,
			"notes": string,
			"processedUtc": string,
			"references": {
				string: string
			},
			"src": string,
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"references": {
		string: string
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
400	3	The references is not an object, or it is invalid.
401	5	You do not have permission to view any Documents for this Company.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company was not found by its unique identifier.

GET/companies/{companyId}/forms?includeDeleted=boolean&includeArchive=boolean&limit=number&after=string&before=string

Gets the list of FormResults for the specified Company.

URL Parameters

Parameter	Type	Required	Description
after	datetime	optional	When using , sets the earliest objects (by dts) to retrieve from the archive.
before	datetime	optional	When using , sets the most recent objects (by dts) to retrieve from the archive.
companyId	uint64	required	Unique identifier of the Company.
includeArchive	boolean	optional	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	False by default, but when true, the command will also return deleted objects.
limit	uint16?	optional	When using , sets the maximum number of objects retrieved from the archive.

Response description

Property	Type	Description
company	RespId	An object to contain the "id" of the Company to which the array of FormResults belong.
company.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
formResults	Array.<FormResult>	The list of requested FormResults.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"formResults": [
		{
			"asset": number,
			"company": number,
			"completed": string,
			"driver": string,
			"fields": {
				string: string
			},
			"id": number,
			"labels": [
				string
			],
			"latlng": {
				"lat": number,
				"lng": number
			},
			"name": string,
			"notes": string,
			"processedUtc": string,
			"template": number,
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
401	5	You do not have permission to view FormResults for this Company.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company was not found by its unique identifier.

GET/companies/{companyId}/forms/templates?includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

Gets the list of FormTemplates for the specified Company.

URL Parameters

Parameter	Type	Required	Description
companyId	uint64	required	Unique identifier of the Company.
highest	uint64?	optional	When using , sets the largest valued id objects to retrieve.
includeArchive	boolean	optional	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	False by default, but when true, the command will also return deleted objects.
limit	uint16?	optional	When using , sets the maximum number of objects retrieved from the archive.
lowest	uint64?	optional	When using , sets the smallest valued id objects to retrieve.

Response description

Property	Type	Description
company	RespId	An object to contain the "id" of the Company to which the array of FormTemplates belong.
company.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
formTemplates	Array.<FormTemplate>	The list of requested FormTemplates.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"formTemplates": [
		{
			"company": number,
			"fields": [
				{
					"editable": boolean,
					"id": number,
					"kind": string,
					"name": string,
					"notes": string,
					"required": boolean,
					"value": string
				}
			],
			"fill": string,
			"graphic": string,
			"id": number,
			"labels": [
				string
			],
			"name": string,
			"notes": string,
			"processedUtc": string,
			"stroke": string,
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
401	5	You do not have permission to view FormTemplates for this Company.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company was not found by its unique identifier.

GET/companies/{companyId}/forms/templates?labels={string}&includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

Gets the list of FormTemplates for the specified Company only if the FormTemplate.labels matches all of the given labels.

URL Parameters

Parameter	Type	Required	Description
companyId	uint64	required	Unique identifier of the Company.
highest	uint64?	optional	When using , sets the largest valued id objects to retrieve.
includeArchive	boolean	optional	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	False by default, but when true, the command will also return deleted objects.
labels	string	required	Labels to match the FormTemplate.
limit	uint16?	optional	When using , sets the maximum number of objects retrieved from the archive.
lowest	uint64?	optional	When using , sets the smallest valued id objects to retrieve.

Response description

Property	Type	Description
company	RespId	An object to contain the "id" of the Company to which the array of FormTemplates belong.
company.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
formTemplates	Array.<FormTemplate>	The list of requested FormTemplates.
labels	Array.<string>	The labels given as input.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"formTemplates": [
		{
			"company": number,
			"fields": [
				{
					"editable": boolean,
					"id": number,
					"kind": string,
					"name": string,
					"notes": string,
					"required": boolean,
					"value": string
				}
			],
			"fill": string,
			"graphic": string,
			"id": number,
			"labels": [
				string
			],
			"name": string,
			"notes": string,
			"processedUtc": string,
			"stroke": string,
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"labels": [
		string
	],
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
400	3	The labels is not an array.
401	5	You do not have permission to view FormTemplates for this Company.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company was not found by its unique identifier.

GET/companies/{companyId}/forms?labels={string}&includeDeleted=boolean&includeArchive=boolean&limit=number&after=string&before=string

Gets the list of FormResults for the specified Company only if the FormResult.labels matches all of the given labels.

URL Parameters

Parameter	Type	Required	Description
after	datetime	optional	When using , sets the earliest objects (by dts) to retrieve from the archive.
before	datetime	optional	When using , sets the most recent objects (by dts) to retrieve from the archive.
companyId	uint64	required	Unique identifier of the Company.
includeArchive	boolean	optional	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	False by default, but when true, the command will also return deleted objects.
labels	string	required	Labels to match the FormResult.
limit	uint16?	optional	When using , sets the maximum number of objects retrieved from the archive.

Response description

Property	Type	Description
company	RespId	An object to contain the "id" of the Company to which the array of FormResults belong.
company.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
formResults	Array.<FormResult>	The list of requested FormResults.
labels	Array.<string>	The labels given as input.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"formResults": [
		{
			"asset": number,
			"company": number,
			"completed": string,
			"driver": string,
			"fields": {
				string: string
			},
			"id": number,
			"labels": [
				string
			],
			"latlng": {
				"lat": number,
				"lng": number
			},
			"name": string,
			"notes": string,
			"processedUtc": string,
			"template": number,
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"labels": [
		string
	],
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
400	3	The labels is not an array.
401	5	You do not have permission to view FormResults for this Company.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company was not found by its unique identifier.

GET/companies/{companyId}/pictures?branch=boolean&includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

Gets the list of Pictures for the specified Company.

URL Parameters

Parameter	Type	Required	Default	Description
branch	boolean	optional	`false`
companyId	uint64	required		Unique identifier of the Company.
highest	uint64?	optional		When using , sets the largest valued id objects to retrieve.
includeArchive	boolean	optional		Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional		False by default, but when true, the command will also return deleted objects.
limit	uint16?	optional		When using , sets the maximum number of objects retrieved from the archive.
lowest	uint64?	optional		When using , sets the smallest valued id objects to retrieve.

Response description

Property	Type	Description
company	RespId	An object to contain the "id" of the Company to which the array of Pictures belong.
company.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
pictures	Array.<Picture>	The list of requested Pictures.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"pictures": [
		{
			"bytes": number,
			"company": number,
			"focals": [
				{
					"bottom": number,
					"left": number,
					"right": number,
					"top": number
				}
			],
			"id": number,
			"name": string,
			"notes": string,
			"processedUtc": string,
			"size": {
				"height": number,
				"width": number
			},
			"src": string,
			"updated": {
			},
			"uses": number,
			"v": [
				number
			]
		}
	],
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
401	5	You do not have permission to view Pictures for this Company.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company was not found by its unique identifier.

GET/dashcams?kind=string&limit=number&after=string&before=string

This request is an alias of /companies/{your-company-id}/dashcams?after={28-days-ago}&before={current-time}.

URL Parameters

Parameter	Type	Required	Default	Description
after	datetime	optional	`"{28-days-ago}"`	28 days ago.
before	datetime	optional	`"{now}"`	The current date/time.
kind	DashcamDataType	optional		Null by default, but can be overridden.
your-company-id	uint64	aliased	`{your-company-id}`	Your own Company's identifier.

GET/dashcams/{guid}

Gets details of the specified dashcam image or video metadata.

URL Parameters

Parameter	Type	Required	Description
guid	guid	optional	Unique identifier of the DashcamData image or video metadata.

Response description

Property	Type	Description
dashcam	DashcamData	The requested dashcam image or video metadata.
dashcam.altitude	double	Altitude of the start of the resource.
dashcam.asset	uint64? see: Asset.id	Unique identifier of the asset tied to the provider at the time.
dashcam.bytes	uint64	Number bytes in the dashcam media file.
dashcam.camera	byte	Number assigned to the camera that took the image/video.
dashcam.company	uint64 see: Company.id	Unique identifier of the company of the provider.
dashcam.end	datetime	Timestamp of when this resource ended. For DashcamDataType.image media files, the start and end are the same.
dashcam.eventName	string	The reason why we're saving this image/video. Or the event name that triggered it.
dashcam.fps	single?	For DashcamDataType.video media files, this indicates the frames-per-second.
dashcam.guid	guid	Unique identifier of this resource.
dashcam.heading	double	Heading of the start of the resource.
dashcam.kind	DashcamDataType	The type of data being stored.
dashcam.latitude	double	Latitude of the start of the resource.
dashcam.longitude	double	Longitude of the start of the resource.
dashcam.provider	string see: Provider.id	Unique identifier of the provider that sent the data.
dashcam.size	Size	Resolution defined in pixels.
dashcam.size.height	double	Height
dashcam.size.width	double	Width
dashcam.speed	double	Speed of the start of the resource.
dashcam.start	datetime	Timestamp of when this resource started. For DashcamDataType.image media files, the start and end are the same.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"dashcam": {
		"altitude": number,
		"asset": number,
		"bytes": number,
		"camera": number,
		"company": number,
		"end": string,
		"eventName": string,
		"fps": number,
		"guid": string,
		"heading": number,
		"kind": string,
		"latitude": number,
		"longitude": number,
		"provider": string,
		"size": {
			"height": number,
			"width": number
		},
		"speed": number,
		"start": string
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a dashcam object, or it is invalid.
400	3	The dashcam object does not contain a guid, or it is invalid.
401	5	You do not have permission to view this dashcam metadata because you do not have access to the Asset.
401	5	You do not have permission to view this dashcam metadata because you do not have access to the Provider.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	20	The dashcam image or video metadata is associated with a deleted Asset.
404	43	The dashcam image or video metadata is associated with a deleted Provider.
404	68	The dashcam image or video metadata was not found by its unique identifier.

GET/dashcams/live?camera=number

This request is an alias of /companies/{your-company-id}/dashcams/live.

URL Parameters

Parameter	Type	Required	Default	Description
camera	byte	optional		Optional camera number when multiple cameras are installed.
your-company-id	uint64	aliased	`{your-company-id}`	Your own Company's identifier.

GET/documents?includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

This request is an alias of /companies/{your-company-id}/documents (when no additional query-string parameters are given) or /companies/{your-company-id}/documents?{keys=values} (when at least one additional query-string key/value is given).

URL Parameters

Parameter	Type	Required	Default	Description
highest	uint64	optional		When using , sets the maximum id when listing from the database.
includeArchive	boolean	optional	`false`	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	`false`	False by default, but when true the command will also return deleted objects.
limit	uint16	optional		When using , sets the maximum number of objects in this response.
lowest	uint64	optional		When using , sets the minimum id when listing from the database.
your-company-id	uint64	aliased	`{your-company-id}`	Your own Company's identifier.

PATCH/documents

Creates or updates an existing Document. To upload Documents, you need to use the Files API.

HTTP Request body description

Property	Type	Required	Description
document	Object.<string, ?>	always	A simple object to contain the Document parameters.
document.company	uint64?	create	The Company to which this Document belongs. After creation, this value is read-only.
document.expiry	datetime	optional	The time at which the Document will automatically be purged from the system.
document.id	uint64?	update	The unique identifier of the Document you want to update.
document.name	string maximum-length: 100	create	The file name of this Document.
document.notes	string	optional	Notes about this Document.
document.references	Object.<string, string> maximum-count: 10 maximum-length of keys: 20 maximum-length of values: 100	optional	Name/value collections of custom fields used to refer to external systems. If the value is null, the references are removed from the Document.
document.v	Array.<int32>	optional
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"document": {
		"company": number,
		"expiry": string,
		"id": number,
		"name": string,
		"notes": string,
		"references": {
			string: string
		},
		"v": [
			number
		]
	},
	"reqId": number
}

Response description

Property	Type	Description
document	RespIdCompany	An object which contains the "id" and "company" keys.
document.company	uint64	Identifier of the Company to which this object belongs.
document.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"document": {
		"company": number,
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a document object, or it is invalid.
400	3	Not enough keys exist in the document object.
400	3	The given document.expiry is too far into the future.
400	3	During create: When creating a new Document, a company was not given.
400	3	During create: When creating a new Document, a name was not given, or it is invalid.
400	3	During create: When creating a new Document, the local path was not specified.
400	3	During create: When creating a new Document, the bytes was invalid.
400	3	During create: When creating a new Document, the mime was invalid.
400	3	During update: When updating a Document, the id was invalid.
400	3	During update: When updating a Document, the v was not an array, or contained too few numbers.
400	3	During update: When updating a Document, the name was given as blank.
401	5	You do not have permission to create a new Document.
401	5	You do not have permission to update this Document.
400	6	During update: When updating a Document, an incorrect v value was given as input.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	122	During update: The Document was not found by its unique identifier.
409	130	During update: When updating a Document, the company can not be changed.

DELETE/documents

Deletes an existing Document.

Response description

Property	Type	Description
document	RespDeleted	An object which contains the Document's id, owning Company id, and deleted status.
document.company	uint64	Identifier of the Company to which this object belongs.
document.deleted	boolean	Flag showing if the object is deleted.
document.id	uint64?	Identifier given as input for the command.
document.v	Array.<uint32>
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"document": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a document object, or it is invalid.
400	3	The document object does not contain an id, or it is invalid.
401	5	You do not have permission to delete this Document.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	122	The Document was not found by its unique identifier.

GET/documents/{documentId}?includeDeleted=boolean

Gets details of the specified Document.

URL Parameters

Parameter	Type	Required	Description
documentId	uint64	required	Unique identifier of the Document.
includeDeleted	boolean	optional	False by default, but when true the command will also return deleted objects.

Response description

Property	Type	Description
document	Document	The requested Document.
document.bytes	uint64	The file-size on the disk.
document.company	uint64 see: Company.id	The company to which this file belongs.
document.expiry	datetime	The date and time this fill will be automatically purged from our system.
document.id	uint64	Unique identifier of this file.
document.mime	string maximum-length: 50	The MIME type of the file.
document.name	string maximum-length: 100	The file name of this file.
document.notes	string	Notes about this file.
document.processedUtc	datetime	When the was change procesed.
document.references	Object.<string, string> maximum-count: 10 maximum-length of keys: 20 maximum-length of values: 100	Name/value collections of custom fields used to refer to external systems.
document.src	string maximum-length: 200	The URL/path to find this file.
document.updated		by: login, from: monster
document.v	Array.<uint32>	Object version keys used to validate synchronization for all object properties.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"document": {
		"bytes": number,
		"company": number,
		"expiry": string,
		"id": number,
		"mime": string,
		"name": string,
		"notes": string,
		"processedUtc": string,
		"references": {
			string: string
		},
		"src": string,
		"updated": {
		},
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a document object, or it is invalid.
400	3	The document object does not contain an id, or it is invalid.
401	5	You do not have permission to view this Document.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	122	The Document was not found by its unique identifier.

POST/documents/{documentId}

Creates or updates an existing Document. To upload Documents, you need to use the Files API.

URL Parameters

Parameter	Type	Required	Description
documentId	uint64?	optional	Unique identifier of the Document. This value is optional, and ignored by the command.

HTTP Request body description

Property	Type	Required	Description
document	Object.<string, ?>	always	A simple object to contain the Document parameters.
document.company	uint64?	create	The Company to which this Document belongs. After creation, this value is read-only.
document.expiry	datetime	optional	The time at which the Document will automatically be purged from the system.
document.id	uint64?	update	The unique identifier of the Document you want to update.
document.name	string maximum-length: 100	create	The file name of this Document.
document.notes	string	optional	Notes about this Document.
document.references	Object.<string, string> maximum-count: 10 maximum-length of keys: 20 maximum-length of values: 100	optional	Name/value collections of custom fields used to refer to external systems. If the value is null, the references are removed from the Document.
document.v	Array.<int32>	optional
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"document": {
		"company": number,
		"expiry": string,
		"id": number,
		"name": string,
		"notes": string,
		"references": {
			string: string
		},
		"v": [
			number
		]
	},
	"reqId": number
}

Response description

Property	Type	Description
document	RespIdCompany	An object which contains the "id" and "company" keys.
document.company	uint64	Identifier of the Company to which this object belongs.
document.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"document": {
		"company": number,
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a document object, or it is invalid.
400	3	Not enough keys exist in the document object.
400	3	The given document.expiry is too far into the future.
400	3	During create: When creating a new Document, a company was not given.
400	3	During create: When creating a new Document, a name was not given, or it is invalid.
400	3	During create: When creating a new Document, the local path was not specified.
400	3	During create: When creating a new Document, the bytes was invalid.
400	3	During create: When creating a new Document, the mime was invalid.
400	3	During update: When updating a Document, the id was invalid.
400	3	During update: When updating a Document, the v was not an array, or contained too few numbers.
400	3	During update: When updating a Document, the name was given as blank.
401	5	You do not have permission to create a new Document.
401	5	You do not have permission to update this Document.
400	6	During update: When updating a Document, an incorrect v value was given as input.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	122	During update: The Document was not found by its unique identifier.
409	130	During update: When updating a Document, the company can not be changed.

DELETE/documents/{documentId}

Deletes an existing Document.

URL Parameters

Parameter	Type	Required	Description
documentId	uint64	required	Unique identifier of the Document.

Response description

Property	Type	Description
document	RespDeleted	An object which contains the Document's id, owning Company id, and deleted status.
document.company	uint64	Identifier of the Company to which this object belongs.
document.deleted	boolean	Flag showing if the object is deleted.
document.id	uint64?	Identifier given as input for the command.
document.v	Array.<uint32>
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"document": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a document object, or it is invalid.
400	3	The document object does not contain an id, or it is invalid.
401	5	You do not have permission to delete this Document.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	122	The Document was not found by its unique identifier.

PATCH/documents/{documentId}/restore

Restores a deleted Document.

URL Parameters

Parameter	Type	Required	Description
documentId	uint64	required	Unique identifier of the Document.

HTTP Request body description

Property	Type	Required	Description
document	ParamId	always	An object to contain the identifier of the Document.
document.id	uint64	always	Identifier given as input for the command.
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"document": {
		"id": number
	},
	"reqId": number
}

Response description

Property	Type	Description
document	RespDeleted	An object which contains the Document's id, owning Company id, and deleted status.
document.company	uint64	Identifier of the Company to which this object belongs.
document.deleted	boolean	Flag showing if the object is deleted.
document.id	uint64?	Identifier given as input for the command.
document.v	Array.<uint32>
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"document": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a document object, or it is invalid.
400	3	The document object does not contain an id, or it is invalid.
401	5	You do not have permission to restore this Document.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	122	The Document was not found by its unique identifier.
400	123	The Document was found, but is not marked as deleted.

GET/forms?includeDeleted=boolean&includeArchive=boolean&limit=number&after=string&before=string

This request is an alias of /companies/{your-company-id}/forms.

URL Parameters

Parameter	Type	Required	Default	Description
after	datetime	optional		When using , sets the earliest objects (by dts) to retrieve from the archive.
before	datetime	optional		When using , sets the most recent objects (by dts) to retrieve from the archive.
includeArchive	boolean	optional	`false`	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	`false`	False by default, but when true the command will also return deleted objects.
limit	uint16	optional		When using , sets the maximum number of objects in this response.
your-company-id	uint64	aliased	`{your-company-id}`	Your own Company's identifier.

PATCH/forms

Creates a new or updates an existing FormResult.

HTTP Request body description

Property	Type	Required	Description
formResult	Object.<string, ?>	always	A simple object to contain the FormResult parameters.
formResult.asset	uint64?	create	The unique identifier of the Asset filling out this form.
formResult.completed	datetime	optional	A timestamp from when the FormResult was completed.
formResult.fields	Object.<uint64, string> maximum-length of values: 254	optional	A collection of values for the FormResult.fields. You can update parts of the collection, the FormResult must have a value for all fields in order to complete it.
formResult.id	uint64?	update	The unique identifier of the FormResult you want to update.
formResult.labels	Array.<codified> for values see: LabelStyle.code	optional	Codified label names used to relate forms to Assets.
formResult.latlng	LatLng	optional	Coordinates from when the FormResult was completed.
formResult.latlng.lat	double	optional	Latitude
formResult.latlng.lng	double	optional	Longitude
formResult.name	string maximum-length: 100	optional	Name for the FormResult.
formResult.notes	string	optional	Notes for the FormResult.
formResult.template	uint64?	create	The unique identifier of the FormTemplate for this form.
formResult.v	Array.<int32>	optional
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"formResult": {
		"asset": number,
		"completed": string,
		"fields": {
			string: string
		},
		"id": number,
		"labels": [
			string
		],
		"latlng": {
			"lat": number,
			"lng": number
		},
		"name": string,
		"notes": string,
		"template": number,
		"v": [
			number
		]
	},
	"reqId": number
}

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
formResult	RespIdCompany	An object which contains the "id" and "company" keys when there is no error.
formResult.company	uint64	Identifier of the Company to which this object belongs.
formResult.id	uint64?	Identifier given as input for the command.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"formResult": {
		"company": number,
		"id": number
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a formResult object, or it is invalid.
400	3	Not enough keys exist in the formResult object.
400	3	During create: When creating a new FormResult, a template was not given.
400	3	During create: When creating a new FormResult, an asset was not a UInt64 or null.
400	3	During create: When creating a new FormResult, a name was not given, or it is invalid.
400	3	During update: When updating a FormResult, the id was invalid.
400	3	During update: When updating a FormResult, the name was given as blank.
400	3	During update: When updating a FormResult, the v was not an array, or contained too few numbers.
400	3	One of the formResult.fields keys or values is invalid. Returns an ErrorDetailInput as the `errorDetails`.
401	5	You do not have permission to read FormTemplates.
401	5	You do not have permission to the Asset to which this FormResult is assigned.
401	5	During create: You do not have permission to create a new FormResult.
401	5	During update: You do not have permission to update this FormResult.
400	6	During update: When updating a FormResult, an incorrect v value was given as input.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	20	During create: The Asset was not found by its unique identifier.
401	71	During update: Changing the labels on this FormResult in the requested way would grant you elevated access to it. Returns an ErrorDetailEscalation as the `errorDetails`.
403	96	The FormResult's assigned Asset is suspended. Before sending or updating FormResults for an Asset, it must be reactivated.
409	130	One of the formResult.fields values is invalid for the FormTemplate's field's FormFieldType.
409	130	The formResult.asset doesn't belong to the same Company as this FormResult.
409	130	After the FormResult.completed is set, the FormResult becomes read-only except for the FormResult.name and FormResult.notes. All other edits are rejected.
409	130	During update: When updating a FormResult, the formResult.template was provided as a different value.
404	132	During create: The FormTemplate was not found by its unique identifier.
404	134	During update: The FormResult was not found by its unique identifier.

DELETE/forms

Deletes an existing FormResult.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
formResult	RespDeleted	An object which contains the FormResult's id, owning Company id, and deleted status.
formResult.company	uint64	Identifier of the Company to which this object belongs.
formResult.deleted	boolean	Flag showing if the object is deleted.
formResult.id	uint64?	Identifier given as input for the command.
formResult.v	Array.<uint32>
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"formResult": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a formResult object, or it is invalid.
400	3	The formResult object does not contain an id, or it is invalid.
401	5	You do not have permission to delete this FormResult.
401	5	You do not have permission to view this FormResult's FormTemplate.
401	5	You do not have permission to the Asset that owns this FormResult.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	20	The Asset that owns this FormResult was not found. If you receive this error, please contact technical support.
403	96	The Asset that owns this FormResult is suspended. Before reading FormResults from an Asset, it must be reactivated.
404	132	The FormResult's FormTemplate was not found by its unique identifier. If you receive this error, please contact technical support.
404	134	The FormResult was not found by its unique identifier.

GET/forms/{resultId}?includeDeleted=boolean

Gets details of the specified FormResult.

URL Parameters

Parameter	Type	Required	Description
includeDeleted	boolean	optional	False by default, but when true the command will also return deleted objects.
resultId	uint64	required	Unique identifier of the FormResult.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
formResult	FormResult	The requested FormResult.
formResult.asset	uint64? see: Asset.id	The Asset to which this form belongs.
formResult.company	uint64 see: Company.id	The Company to which this form belongs.
formResult.completed	datetime	A timestamp from when this form was completed by a User or Asset.
formResult.driver	string	Clocked-in driver name who made the update. Null if not clocked-in, or no changes have been made.
formResult.fields	Object.<uint64, string>	All the values for fillable fields by index.
formResult.id	uint64	Unique identifier of this form.
formResult.labels	Array.<codified> for values see: LabelStyle.code	Codified label names used to relate forms to Assets.
formResult.latlng	LatLng	The coordinates of the User or Asset from when the form was completed.
formResult.latlng.lat	double	Latitude
formResult.latlng.lng	double	Longitude
formResult.name	string maximum-length: 100	Name of this form.
formResult.notes	string	Notes about this form.
formResult.processedUtc	datetime	When the was change procesed.
formResult.template	uint64	The FormTemplate to which this form belongs.
formResult.updated		by: login, from: monster
formResult.v	Array.<uint32>	Object version keys used to validate synchronization for all object properties.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"formResult": {
		"asset": number,
		"company": number,
		"completed": string,
		"driver": string,
		"fields": {
			string: string
		},
		"id": number,
		"labels": [
			string
		],
		"latlng": {
			"lat": number,
			"lng": number
		},
		"name": string,
		"notes": string,
		"processedUtc": string,
		"template": number,
		"updated": {
		},
		"v": [
			number
		]
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a formResult object, or it is invalid.
400	3	The formResult object does not contain an id, or it is invalid.
401	5	You do not have permission to view this FormResult.
401	5	You do not have permission to view this FormResult's FormTemplate.
401	5	You do not have permission to the Asset that owns this FormResult.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	20	The Asset that owns this FormResult was not found. If you receive this error, please contact technical support.
403	96	The Asset that owns this FormResult is suspended. Before reading FormResults from an Asset, it must be reactivated.
404	132	The FormResult's FormTemplate was not found by its unique identifier. If you receive this error, please contact technical support.
404	134	The FormResult was not found by its unique identifier.

POST/forms/{resultId}

Creates a new or updates an existing FormResult.

URL Parameters

Parameter	Type	Required	Description
resultId	uint64?	optional	Unique identifier of the FormResult. This value is optional, and ignored by the command.

HTTP Request body description

Property	Type	Required	Description
formResult	Object.<string, ?>	always	A simple object to contain the FormResult parameters.
formResult.asset	uint64?	create	The unique identifier of the Asset filling out this form.
formResult.completed	datetime	optional	A timestamp from when the FormResult was completed.
formResult.fields	Object.<uint64, string> maximum-length of values: 254	optional	A collection of values for the FormResult.fields. You can update parts of the collection, the FormResult must have a value for all fields in order to complete it.
formResult.id	uint64?	update	The unique identifier of the FormResult you want to update.
formResult.labels	Array.<codified> for values see: LabelStyle.code	optional	Codified label names used to relate forms to Assets.
formResult.latlng	LatLng	optional	Coordinates from when the FormResult was completed.
formResult.latlng.lat	double	optional	Latitude
formResult.latlng.lng	double	optional	Longitude
formResult.name	string maximum-length: 100	optional	Name for the FormResult.
formResult.notes	string	optional	Notes for the FormResult.
formResult.template	uint64?	create	The unique identifier of the FormTemplate for this form.
formResult.v	Array.<int32>	optional
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"formResult": {
		"asset": number,
		"completed": string,
		"fields": {
			string: string
		},
		"id": number,
		"labels": [
			string
		],
		"latlng": {
			"lat": number,
			"lng": number
		},
		"name": string,
		"notes": string,
		"template": number,
		"v": [
			number
		]
	},
	"reqId": number
}

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
formResult	RespIdCompany	An object which contains the "id" and "company" keys when there is no error.
formResult.company	uint64	Identifier of the Company to which this object belongs.
formResult.id	uint64?	Identifier given as input for the command.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"formResult": {
		"company": number,
		"id": number
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a formResult object, or it is invalid.
400	3	Not enough keys exist in the formResult object.
400	3	During create: When creating a new FormResult, a template was not given.
400	3	During create: When creating a new FormResult, an asset was not a UInt64 or null.
400	3	During create: When creating a new FormResult, a name was not given, or it is invalid.
400	3	During update: When updating a FormResult, the id was invalid.
400	3	During update: When updating a FormResult, the name was given as blank.
400	3	During update: When updating a FormResult, the v was not an array, or contained too few numbers.
400	3	One of the formResult.fields keys or values is invalid. Returns an ErrorDetailInput as the `errorDetails`.
401	5	You do not have permission to read FormTemplates.
401	5	You do not have permission to the Asset to which this FormResult is assigned.
401	5	During create: You do not have permission to create a new FormResult.
401	5	During update: You do not have permission to update this FormResult.
400	6	During update: When updating a FormResult, an incorrect v value was given as input.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	20	During create: The Asset was not found by its unique identifier.
401	71	During update: Changing the labels on this FormResult in the requested way would grant you elevated access to it. Returns an ErrorDetailEscalation as the `errorDetails`.
403	96	The FormResult's assigned Asset is suspended. Before sending or updating FormResults for an Asset, it must be reactivated.
409	130	One of the formResult.fields values is invalid for the FormTemplate's field's FormFieldType.
409	130	The formResult.asset doesn't belong to the same Company as this FormResult.
409	130	After the FormResult.completed is set, the FormResult becomes read-only except for the FormResult.name and FormResult.notes. All other edits are rejected.
409	130	During update: When updating a FormResult, the formResult.template was provided as a different value.
404	132	During create: The FormTemplate was not found by its unique identifier.
404	134	During update: The FormResult was not found by its unique identifier.

DELETE/forms/{resultId}

Deletes an existing FormResult.

URL Parameters

Parameter	Type	Required	Description
resultId	uint64	required	Unique identifier of the FormResult.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
formResult	RespDeleted	An object which contains the FormResult's id, owning Company id, and deleted status.
formResult.company	uint64	Identifier of the Company to which this object belongs.
formResult.deleted	boolean	Flag showing if the object is deleted.
formResult.id	uint64?	Identifier given as input for the command.
formResult.v	Array.<uint32>
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"formResult": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a formResult object, or it is invalid.
400	3	The formResult object does not contain an id, or it is invalid.
401	5	You do not have permission to delete this FormResult.
401	5	You do not have permission to view this FormResult's FormTemplate.
401	5	You do not have permission to the Asset that owns this FormResult.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	20	The Asset that owns this FormResult was not found. If you receive this error, please contact technical support.
403	96	The Asset that owns this FormResult is suspended. Before reading FormResults from an Asset, it must be reactivated.
404	132	The FormResult's FormTemplate was not found by its unique identifier. If you receive this error, please contact technical support.
404	134	The FormResult was not found by its unique identifier.

PATCH/forms/{resultId}/restore

Restores the specified FormResult.

URL Parameters

Parameter	Type	Required	Description
resultId	uint64	required	Unique identifier of the FormResult.

HTTP Request body description

Property	Type	Required	Description
formResult	ParamId	always	An object to contain the "id" of the FormResult.
formResult.id	uint64	always	Identifier given as input for the command.
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"formResult": {
		"id": number
	},
	"reqId": number
}

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
formResult	RespDeleted	An object which contains the FormResult's id, owning Company id, and deleted status.
formResult.company	uint64	Identifier of the Company to which this object belongs.
formResult.deleted	boolean	Flag showing if the object is deleted.
formResult.id	uint64?	Identifier given as input for the command.
formResult.v	Array.<uint32>
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"formResult": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a formResult object, or it is invalid.
400	3	The formResult object does not contain an id, or it is invalid.
401	5	You do not have permission to restore this FormResult.
401	5	You do not have permission to view this FormResult's FormTemplate.
401	5	You do not have permission to the Asset that owns this FormResult.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	20	The Asset that owns this FormResult was not found. If you receive this error, please contact technical support.
403	96	The Asset that owns this FormResult is suspended. Before reading FormResults from an Asset, it must be reactivated.
404	134	The FormResult was not found by its unique identifier.
400	135	The FormResult was found, but is not marked as deleted.

GET/forms/templates?includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

This request is an alias of /companies/{your-company-id}/forms/templates.

URL Parameters

Parameter	Type	Required	Default	Description
highest	uint64	optional		When using , sets the maximum id when listing from the database.
includeArchive	boolean	optional	`false`	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	`false`	False by default, but when true the command will also return deleted objects.
limit	uint16	optional		When using , sets the maximum number of objects in this response.
lowest	uint64	optional		When using , sets the minimum id when listing from the database.
your-company-id	uint64	aliased	`{your-company-id}`	Your own Company's identifier.

PATCH/forms/templates

Creates a new or updates an existing FormTemplate.

HTTP Request body description

Property	Type	Required	Description
formTemplate	Object.<string, ?>	always	A simple object to contain the FormTemplate parameters.
formTemplate.company	uint64?	create	The Company to which this FormTemplate belongs. After creation, this value is read-only.
formTemplate.fields	Array.<ParamFormField>	optional	A collection of all the FormTemplate.fields. Any field not given in the collection will be removed.
formTemplate.fill	colour maximum-length: 22	optional	Background and fill colour in the UI.
formTemplate.graphic	colour maximum-length: 22	optional	The name of the symbol shown in the UI.
formTemplate.id	uint64?	update	The unique identifier of the FormTemplate you want to update.
formTemplate.labels	Array.<codified> for values see: LabelStyle.code	optional	Codified label names used to relate forms to Assets.
formTemplate.name	string maximum-length: 100	optional	Name for the FormTemplate.
formTemplate.notes	string	optional	Notes for the FormTemplate.
formTemplate.stroke	colour maximum-length: 22	optional	Text and outline colour in the UI.
formTemplate.v	Array.<int32>	optional
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"formTemplate": {
		"company": number,
		"fields": [
			{
				"choices": Object,
				"editable": boolean,
				"id": number,
				"kind": string,
				"maximum": Object,
				"minimum": Object,
				"name": string,
				"notes": string,
				"precision": number,
				"required": boolean,
				"rows": number,
				"size": string,
				"step": number,
				"units": string,
				"value": string
			}
		],
		"fill": string,
		"graphic": string,
		"id": number,
		"labels": [
			string
		],
		"name": string,
		"notes": string,
		"stroke": string,
		"v": [
			number
		]
	},
	"reqId": number
}

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
formTemplate	RespIdCompany	An object which contains the "id" and "company" keys when there is no error.
formTemplate.company	uint64	Identifier of the Company to which this object belongs.
formTemplate.id	uint64?	Identifier given as input for the command.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"formTemplate": {
		"company": number,
		"id": number
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a formTemplate object, or it is invalid.
400	3	Not enough keys exist in the formTemplate object.
400	3	During create: When creating a new FormTemplate, a company was not given.
400	3	During create: When creating a new FormTemplate, a name was not given, or it is invalid.
400	3	During create: When creating a new FormTemplate, no formTemplate.fields were given.
400	3	During create: When creating a new FormTemplate, a formTemplate.fields had the ParamFormField.id value, which must be null or ommited.
400	3	During create: When creating a new FormTemplate, a formTemplate.fields was missing the ParamFormField.name value.
400	3	During create: When creating a new FormTemplate, a formTemplate.fields was missing the ParamFormField.kind value.
400	3	During update: When updating a FormTemplate, the id was invalid.
400	3	During update: When updating a FormTemplate, the name was given as blank.
400	3	During update: When updating a FormTemplate, the v was not an array, or contained too few numbers.
400	3	The formTemplate.fields list contains two (or more) fields with the same non-null ParamFormField.id. Returns an ErrorDetailBadIds as the `errorDetails`.
400	3	During update: When updating a FormTemplate, a formTemplate.fields was not found by the given ParamFormField.id. Returns an ErrorDetailBadIds as the `errorDetails`.
400	3	One of the formTemplate.fields is null, or an empty object. Returns an ErrorDetailInput as the `errorDetails`.
400	3	One of the formTemplate.fields object's values is invalid. Returns an ErrorDetailInput as the `errorDetails`.
400	3	During create: One of the ParameterContent's ParamFormField.name is blank or null. Returns an ErrorDetailInput as the `errorDetails`.
401	5	You do not have permission to create a new FormTemplate.
401	5	You do not have permission to update this FormTemplate.
400	6	During update: When updating a FormTemplate, an incorrect v value was given as input.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
401	71	During update: Changing the labels on this FormTemplate in the requested way would grant you elevated access to it. Returns an ErrorDetailEscalation as the `errorDetails`.
409	130	During update: When updating a FormTemplate, the company was provided as a different value.
409	130	One of the default values specified for the FormTemplate was invalid. Returns an ErrorDetailInput as the `errorDetails`.
404	132	During update: The FormTemplate was not found by its unique identifier.

DELETE/forms/templates

Deletes an existing FormTemplate.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
formTemplate	RespDeleted	An object which contains the FormTemplate's id, owning Company id, and deleted status.
formTemplate.company	uint64	Identifier of the Company to which this object belongs.
formTemplate.deleted	boolean	Flag showing if the object is deleted.
formTemplate.id	uint64?	Identifier given as input for the command.
formTemplate.v	Array.<uint32>
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"formTemplate": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a formTemplate object, or it is invalid.
400	3	The formTemplate object does not contain an id, or it is invalid.
401	5	You do not have permission to delete this FormTemplate.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	132	The FormTemplate was not found by its unique identifier.
409	142	This FormTemplate is still in use by a FormResult. Returns an ErrorDetailFormTemplateInUse as the `errorDetails`.

GET/forms/templates/{templateId}?includeDeleted=boolean

Gets details of the specified FormTemplate.

URL Parameters

Parameter	Type	Required	Description
includeDeleted	boolean	optional	False by default, but when true the command will also return deleted objects.
templateId	uint64	required	Unique identifier of the FormTemplate.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
formTemplate	FormTemplate	The requested FormTemplate.
formTemplate.company	uint64 see: Company.id	The Company to which this form belongs.
formTemplate.fields	Array.<FormFieldBase>	All the user fillable fields by name.
formTemplate.fill	colour maximum-length: 22	The fill/background colour of the icon.
formTemplate.graphic	codified maximum-length: 22	The name of the symbol for this template.
formTemplate.id	uint64	Unique identifier of this form.
formTemplate.labels	Array.<codified> for values see: LabelStyle.code	Codified label names used to relate forms to Assets.
formTemplate.name	string maximum-length: 100	Name of this form.
formTemplate.notes	string	Notes about this form.
formTemplate.processedUtc	datetime	When the was change procesed.
formTemplate.stroke	colour maximum-length: 22	Outline and graphic colour.
formTemplate.updated		by: login, from: monster
formTemplate.v	Array.<uint32>	Object version keys used to validate synchronization for all object properties.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"formTemplate": {
		"company": number,
		"fields": [
			{
				"editable": boolean,
				"id": number,
				"kind": string,
				"name": string,
				"notes": string,
				"required": boolean,
				"value": string
			}
		],
		"fill": string,
		"graphic": string,
		"id": number,
		"labels": [
			string
		],
		"name": string,
		"notes": string,
		"processedUtc": string,
		"stroke": string,
		"updated": {
		},
		"v": [
			number
		]
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a formTemplate object, or it is invalid.
400	3	The formTemplate object does not contain an id, or it is invalid.
401	5	You do not have permission to view this FormTemplate.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	132	The FormTemplate was not found by its unique identifier.

POST/forms/templates/{templateId}

Creates a new or updates an existing FormTemplate.

URL Parameters

Parameter	Type	Required	Description
templateId	uint64?	optional	Unique identifier of the FormTemplate. This value is optional, and ignored by the command.

HTTP Request body description

Property	Type	Required	Description
formTemplate	Object.<string, ?>	always	A simple object to contain the FormTemplate parameters.
formTemplate.company	uint64?	create	The Company to which this FormTemplate belongs. After creation, this value is read-only.
formTemplate.fields	Array.<ParamFormField>	optional	A collection of all the FormTemplate.fields. Any field not given in the collection will be removed.
formTemplate.fill	colour maximum-length: 22	optional	Background and fill colour in the UI.
formTemplate.graphic	colour maximum-length: 22	optional	The name of the symbol shown in the UI.
formTemplate.id	uint64?	update	The unique identifier of the FormTemplate you want to update.
formTemplate.labels	Array.<codified> for values see: LabelStyle.code	optional	Codified label names used to relate forms to Assets.
formTemplate.name	string maximum-length: 100	optional	Name for the FormTemplate.
formTemplate.notes	string	optional	Notes for the FormTemplate.
formTemplate.stroke	colour maximum-length: 22	optional	Text and outline colour in the UI.
formTemplate.v	Array.<int32>	optional
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"formTemplate": {
		"company": number,
		"fields": [
			{
				"choices": Object,
				"editable": boolean,
				"id": number,
				"kind": string,
				"maximum": Object,
				"minimum": Object,
				"name": string,
				"notes": string,
				"precision": number,
				"required": boolean,
				"rows": number,
				"size": string,
				"step": number,
				"units": string,
				"value": string
			}
		],
		"fill": string,
		"graphic": string,
		"id": number,
		"labels": [
			string
		],
		"name": string,
		"notes": string,
		"stroke": string,
		"v": [
			number
		]
	},
	"reqId": number
}

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
formTemplate	RespIdCompany	An object which contains the "id" and "company" keys when there is no error.
formTemplate.company	uint64	Identifier of the Company to which this object belongs.
formTemplate.id	uint64?	Identifier given as input for the command.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"formTemplate": {
		"company": number,
		"id": number
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a formTemplate object, or it is invalid.
400	3	Not enough keys exist in the formTemplate object.
400	3	During create: When creating a new FormTemplate, a company was not given.
400	3	During create: When creating a new FormTemplate, a name was not given, or it is invalid.
400	3	During create: When creating a new FormTemplate, no formTemplate.fields were given.
400	3	During create: When creating a new FormTemplate, a formTemplate.fields had the ParamFormField.id value, which must be null or ommited.
400	3	During create: When creating a new FormTemplate, a formTemplate.fields was missing the ParamFormField.name value.
400	3	During create: When creating a new FormTemplate, a formTemplate.fields was missing the ParamFormField.kind value.
400	3	During update: When updating a FormTemplate, the id was invalid.
400	3	During update: When updating a FormTemplate, the name was given as blank.
400	3	During update: When updating a FormTemplate, the v was not an array, or contained too few numbers.
400	3	The formTemplate.fields list contains two (or more) fields with the same non-null ParamFormField.id. Returns an ErrorDetailBadIds as the `errorDetails`.
400	3	During update: When updating a FormTemplate, a formTemplate.fields was not found by the given ParamFormField.id. Returns an ErrorDetailBadIds as the `errorDetails`.
400	3	One of the formTemplate.fields is null, or an empty object. Returns an ErrorDetailInput as the `errorDetails`.
400	3	One of the formTemplate.fields object's values is invalid. Returns an ErrorDetailInput as the `errorDetails`.
400	3	During create: One of the ParameterContent's ParamFormField.name is blank or null. Returns an ErrorDetailInput as the `errorDetails`.
401	5	You do not have permission to create a new FormTemplate.
401	5	You do not have permission to update this FormTemplate.
400	6	During update: When updating a FormTemplate, an incorrect v value was given as input.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
401	71	During update: Changing the labels on this FormTemplate in the requested way would grant you elevated access to it. Returns an ErrorDetailEscalation as the `errorDetails`.
409	130	During update: When updating a FormTemplate, the company was provided as a different value.
409	130	One of the default values specified for the FormTemplate was invalid. Returns an ErrorDetailInput as the `errorDetails`.
404	132	During update: The FormTemplate was not found by its unique identifier.

DELETE/forms/templates/{templateId}

Deletes an existing FormTemplate.

URL Parameters

Parameter	Type	Required	Description
templateId	uint64	required	Unique identifier of the FormTemplate.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
formTemplate	RespDeleted	An object which contains the FormTemplate's id, owning Company id, and deleted status.
formTemplate.company	uint64	Identifier of the Company to which this object belongs.
formTemplate.deleted	boolean	Flag showing if the object is deleted.
formTemplate.id	uint64?	Identifier given as input for the command.
formTemplate.v	Array.<uint32>
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"formTemplate": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a formTemplate object, or it is invalid.
400	3	The formTemplate object does not contain an id, or it is invalid.
401	5	You do not have permission to delete this FormTemplate.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	132	The FormTemplate was not found by its unique identifier.
409	142	This FormTemplate is still in use by a FormResult. Returns an ErrorDetailFormTemplateInUse as the `errorDetails`.

PATCH/forms/templates/{templateId}/restore

Restores the specified FormTemplate.

URL Parameters

Parameter	Type	Required	Description
templateId	uint64	required	Unique identifier of the FormTemplate.

HTTP Request body description

Property	Type	Required	Description
formTemplate	ParamId	always	An object to contain the "id" of the FormTemplate.
formTemplate.id	uint64	always	Identifier given as input for the command.
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"formTemplate": {
		"id": number
	},
	"reqId": number
}

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
formTemplate	RespDeleted	An object which contains the FormTemplate's id, owning Company id, and deleted status.
formTemplate.company	uint64	Identifier of the Company to which this object belongs.
formTemplate.deleted	boolean	Flag showing if the object is deleted.
formTemplate.id	uint64?	Identifier given as input for the command.
formTemplate.v	Array.<uint32>
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"formTemplate": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a formTemplate object, or it is invalid.
400	3	The formTemplate object does not contain an id, or it is invalid.
401	5	You do not have permission to restore this FormTemplate.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	132	The FormTemplate was not found by its unique identifier.
400	133	The FormTemplate was found, but is not marked as deleted.

GET/forms?template={uint64}&labels={string}&includeDeleted=boolean&includeArchive=boolean&limit=number&after=string&before=string

Gets the list of FormResults for the specified FormTemplate.

URL Parameters

Parameter	Type	Required	Description
after	datetime	optional	When using , sets the earliest objects (by dts) to retrieve from the archive.
before	datetime	optional	When using , sets the most recent objects (by dts) to retrieve from the archive.
includeArchive	boolean	optional	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	False by default, but when true, the command will also return deleted objects.
labels	string	required	Labels to match the FormResult.
limit	uint16?	optional	When using , sets the maximum number of objects retrieved from the archive.
template	uint64	required	Unique identifier of the FormTemplate.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
formResults	Array.<FormResult>	The list of requested FormResults.
formTemplate	RespIdCompany	An object to contain the "id" of the FormTemplate to which the array of FormResults belong.
formTemplate.company	uint64	Identifier of the Company to which this object belongs.
formTemplate.id	uint64?	Identifier given as input for the command.
labels	Array.<string>	The labels given as input.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"formResults": [
		{
			"asset": number,
			"company": number,
			"completed": string,
			"driver": string,
			"fields": {
				string: string
			},
			"id": number,
			"labels": [
				string
			],
			"latlng": {
				"lat": number,
				"lng": number
			},
			"name": string,
			"notes": string,
			"processedUtc": string,
			"template": number,
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"formTemplate": {
		"company": number,
		"id": number
	},
	"labels": [
		string
	],
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a formTemplate object, or it is invalid.
400	3	The formTemplate object does not contain an id, or it is invalid.
400	3	The labels is not an array.
401	5	You do not have permission to view FormResults.
401	5	You do not have permission to view the specified FormTemplate.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	132	The FormTemplate that owns these FormResults was not found.

GET/forms?template={uint64}&includeDeleted=boolean&includeArchive=boolean&limit=number&after=string&before=string

Gets the list of FormResults for the specified FormTemplate.

URL Parameters

Parameter	Type	Required	Description
after	datetime	optional	When using , sets the earliest objects (by dts) to retrieve from the archive.
before	datetime	optional	When using , sets the most recent objects (by dts) to retrieve from the archive.
includeArchive	boolean	optional	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	False by default, but when true, the command will also return deleted objects.
limit	uint16?	optional	When using , sets the maximum number of objects retrieved from the archive.
template	uint64	required	Unique identifier of the FormTemplate.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
formResults	Array.<FormResult>	The list of requested FormResults.
formTemplate	RespIdCompany	An object to contain the "id" of the FormTemplate to which the array of FormResults belong.
formTemplate.company	uint64	Identifier of the Company to which this object belongs.
formTemplate.id	uint64?	Identifier given as input for the command.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"formResults": [
		{
			"asset": number,
			"company": number,
			"completed": string,
			"driver": string,
			"fields": {
				string: string
			},
			"id": number,
			"labels": [
				string
			],
			"latlng": {
				"lat": number,
				"lng": number
			},
			"name": string,
			"notes": string,
			"processedUtc": string,
			"template": number,
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"formTemplate": {
		"company": number,
		"id": number
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a formTemplate object, or it is invalid.
400	3	The formTemplate object does not contain an id, or it is invalid.
401	5	You do not have permission to view FormResults.
401	5	You do not have permission to view the specified FormTemplate.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	132	The FormTemplate that owns these FormResults was not found.

GET/pictures?branch=boolean&includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

This request is an alias of /companies/{your-company-id}/pictures?branch=true.

URL Parameters

Parameter	Type	Required	Default	Description
branch	boolean	optional	`true`	Defaults to true for this alias.
highest	uint64	optional		When using , sets the maximum id when listing from the database.
includeArchive	boolean	optional	`false`	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	`false`	False by default, but when true the command will also return deleted objects.
limit	uint16	optional		When using , sets the maximum number of objects in this response.
lowest	uint64	optional		When using , sets the minimum id when listing from the database.
your-company-id	uint64	aliased	`{your-company-id}`	Your own Company's identifier.

PATCH/pictures

Creates a new or updates an existing Picture.

HTTP Request body description

Property	Type	Required	Description
picture	Object.<string, ?>	always	A simple object to contain the Picture parameters.
picture.company	uint64?	create	The Company to which this Picture belongs. After creation, this value is read-only.
picture.focals	Array.<Square>	optional	A list of focal points in the Picture like faces.
picture.id	uint64?	update	The unique identifier of the Picture you want to update.
picture.name	string maximum-length: 100	create	The file name of this Picture.
picture.notes	string	optional	Notes about this Picture.
picture.v	Array.<int32>	optional
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"picture": {
		"company": number,
		"focals": [
			{
				"bottom": number,
				"left": number,
				"right": number,
				"top": number
			}
		],
		"id": number,
		"name": string,
		"notes": string,
		"v": [
			number
		]
	},
	"reqId": number
}

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
picture	RespIdCompany	An object which contains the "id" and "company" keys when there is no error.
picture.company	uint64	Identifier of the Company to which this object belongs.
picture.id	uint64?	Identifier given as input for the command.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"picture": {
		"company": number,
		"id": number
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
500	2	During create: When creating a new Picture, the file size could not be determined. If you receive this error, please contact technical support.
500	2	During create: When creating a new Picture, the upload was not successful. If you receive this error, please contact technical support.
400	3	The request does not contain a picture object, or it is invalid.
400	3	Not enough keys exist in the picture object.
400	3	During create: When creating a new Picture, a company was not given.
400	3	During create: When creating a new Picture, a name was not given, or it is invalid.
400	3	During update: When updating a Picture, the id was invalid.
400	3	During update: When updating a Picture, the name was given as blank.
400	3	During update: When updating a Picture, the v was not an array, or contained too few numbers.
400	3	One of the picture.focals values is invalid. Returns an ErrorDetailInput as the `errorDetails`.
401	5	You do not have permission to create a new Picture.
401	5	You do not have permission to update this Picture.
400	6	During update: When updating a Picture, an incorrect v value was given as input.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	68	During update: The Picture was not found by its unique identifier.
400	90	During create: When creating a new Picture, the given mime type is not supported.
400	91	During create: When creating a new Picture, the file size was too large. Returns an ErrorDetailMinMax as the `errorDetails`.
409	130	During update: When updating a Picture, the company can not be changed.

DELETE/pictures

Deletes an existing Picture.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
picture	RespDeleted	An object which contains the Picture's id, owning Company id, and deleted status.
picture.company	uint64	Identifier of the Company to which this object belongs.
picture.deleted	boolean	Flag showing if the object is deleted.
picture.id	uint64?	Identifier given as input for the command.
picture.v	Array.<uint32>
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"picture": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a picture object, or it is invalid.
400	3	The picture object does not contain an id, or it is invalid.
401	5	You do not have permission to delete this Picture.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	68	The Picture was not found by its unique identifier.

GET/pictures/{pictureId}?includeDeleted=boolean

Gets details of the specified Picture.

URL Parameters

Parameter	Type	Required	Description
includeDeleted	boolean	optional	False by default, but when true the command will also return deleted objects.
pictureId	uint64	required	Unique identifier of the Picture.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
picture	Picture	The requested Picture.
picture.bytes	uint64	The file-size on the disk.
picture.company	uint64 see: Company.id	The company to which this image belongs.
picture.focals	Array.<Square>	A list of focal points in the images like faces.
picture.id	uint64	Unique identifier of this image.
picture.name	string maximum-length: 100	The file name of this image.
picture.notes	string	Notes about this image.
picture.processedUtc	datetime	When the was change procesed.
picture.size	Size	Resolution defined in pixels.
picture.size.height	double	Height
picture.size.width	double	Width
picture.src	string maximum-length: 200	The URL/path to find this image.
picture.updated		by: login, from: monster
picture.uses	uint32	A count of the times this image was used for something (asset, contact, task, etc).
picture.v	Array.<uint32>	Object version keys used to validate synchronization for all object properties.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"picture": {
		"bytes": number,
		"company": number,
		"focals": [
			{
				"bottom": number,
				"left": number,
				"right": number,
				"top": number
			}
		],
		"id": number,
		"name": string,
		"notes": string,
		"processedUtc": string,
		"size": {
			"height": number,
			"width": number
		},
		"src": string,
		"updated": {
		},
		"uses": number,
		"v": [
			number
		]
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a picture object, or it is invalid.
400	3	The picture object does not contain an id, or it is invalid.
401	5	You do not have permission to view this Picture.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	68	The Picture was not found by its unique identifier.

POST/pictures/{pictureId}

Creates a new or updates an existing Picture.

URL Parameters

Parameter	Type	Required	Description
pictureId	uint64?	optional	Unique identifier of the Picture. This value is optional, and ignored by the command.

HTTP Request body description

Property	Type	Required	Description
picture	Object.<string, ?>	always	A simple object to contain the Picture parameters.
picture.company	uint64?	create	The Company to which this Picture belongs. After creation, this value is read-only.
picture.focals	Array.<Square>	optional	A list of focal points in the Picture like faces.
picture.id	uint64?	update	The unique identifier of the Picture you want to update.
picture.name	string maximum-length: 100	create	The file name of this Picture.
picture.notes	string	optional	Notes about this Picture.
picture.v	Array.<int32>	optional
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"picture": {
		"company": number,
		"focals": [
			{
				"bottom": number,
				"left": number,
				"right": number,
				"top": number
			}
		],
		"id": number,
		"name": string,
		"notes": string,
		"v": [
			number
		]
	},
	"reqId": number
}

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
picture	RespIdCompany	An object which contains the "id" and "company" keys when there is no error.
picture.company	uint64	Identifier of the Company to which this object belongs.
picture.id	uint64?	Identifier given as input for the command.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"picture": {
		"company": number,
		"id": number
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
500	2	During create: When creating a new Picture, the file size could not be determined. If you receive this error, please contact technical support.
500	2	During create: When creating a new Picture, the upload was not successful. If you receive this error, please contact technical support.
400	3	The request does not contain a picture object, or it is invalid.
400	3	Not enough keys exist in the picture object.
400	3	During create: When creating a new Picture, a company was not given.
400	3	During create: When creating a new Picture, a name was not given, or it is invalid.
400	3	During update: When updating a Picture, the id was invalid.
400	3	During update: When updating a Picture, the name was given as blank.
400	3	During update: When updating a Picture, the v was not an array, or contained too few numbers.
400	3	One of the picture.focals values is invalid. Returns an ErrorDetailInput as the `errorDetails`.
401	5	You do not have permission to create a new Picture.
401	5	You do not have permission to update this Picture.
400	6	During update: When updating a Picture, an incorrect v value was given as input.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	68	During update: The Picture was not found by its unique identifier.
400	90	During create: When creating a new Picture, the given mime type is not supported.
400	91	During create: When creating a new Picture, the file size was too large. Returns an ErrorDetailMinMax as the `errorDetails`.
409	130	During update: When updating a Picture, the company can not be changed.

DELETE/pictures/{pictureId}

Deletes an existing Picture.

URL Parameters

Parameter	Type	Required	Description
pictureId	uint64	required	Unique identifier of the Picture.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
picture	RespDeleted	An object which contains the Picture's id, owning Company id, and deleted status.
picture.company	uint64	Identifier of the Company to which this object belongs.
picture.deleted	boolean	Flag showing if the object is deleted.
picture.id	uint64?	Identifier given as input for the command.
picture.v	Array.<uint32>
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"picture": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a picture object, or it is invalid.
400	3	The picture object does not contain an id, or it is invalid.
401	5	You do not have permission to delete this Picture.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	68	The Picture was not found by its unique identifier.

PATCH/pictures/{pictureId}/restore

Restores the specified Picture.

URL Parameters

Parameter	Type	Required	Description
pictureId	uint64	required	Unique identifier of the Picture.

HTTP Request body description

Property	Type	Required	Description
picture	ParamId	always	An object to contain the "id" of the Picture.
picture.id	uint64	always	Identifier given as input for the command.
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"picture": {
		"id": number
	},
	"reqId": number
}

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
picture	RespDeleted	An object which contains the Picture's id, owning Company id, and deleted status.
picture.company	uint64	Identifier of the Company to which this object belongs.
picture.deleted	boolean	Flag showing if the object is deleted.
picture.id	uint64?	Identifier given as input for the command.
picture.v	Array.<uint32>
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"picture": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a picture object, or it is invalid.
400	3	The picture object does not contain an id, or it is invalid.
401	5	You do not have permission to restore this Picture.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	68	The Picture was not found by its unique identifier.
400	70	The Picture was found, but is not marked as deleted.

GET/providers/{providerId}/dashcams?after=string&before=string&limit=number&kind=DashcamDataType

Gets the list of dashcam metadata for the specified Provider.

URL Parameters

Parameter	Type	Required	Default	Description
after	datetime	optional	`"{28-days-ago}"`	A timestamp for the earliest DashcamData metadata to retrieve.
before	datetime	optional	`"{now}"`	A timestamp for the most recent DashcamData metadata to retrieve.
kind	DashcamDataType?	optional		An optional filter available so that only a certain kind of DashcamData is returned.
limit	uint16?	optional	`1000`	A maximum number of DashcamData metadata to retrieve.
providerId	string	required		Unique identifier of the Provider.

Response description

Property	Type	Description
dashcams	Array.<DashcamData>	The list of requested dashcam image or video metadata.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
provider	RespIdendifier	An object to contain the "id" of the Provider to which the array of dashcam image or video metadata belong.
provider.id	string	Identifier given as input for the command.
reqId	int32?	Identifier used by external system to correlate requests to responses.
totals	Object.<DashcamDataType, HostedTotal>	Totals of hosted dashcam media as calculated at midnight.

Response structure

{
	"dashcams": [
		{
			"altitude": number,
			"asset": number,
			"bytes": number,
			"camera": number,
			"company": number,
			"end": string,
			"eventName": string,
			"fps": number,
			"guid": string,
			"heading": number,
			"kind": string,
			"latitude": number,
			"longitude": number,
			"provider": string,
			"size": {
				"height": number,
				"width": number
			},
			"speed": number,
			"start": string
		}
	],
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"provider": {
		"id": string
	},
	"reqId": number,
	"totals": {
		string: {
			"bytes": number,
			"count": number,
			"newest": string,
			"oldest": string
		}
	}
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a valid after timestamp.
400	3	The request does not contain a valid before timestamp.
400	3	The request does not contain a provider object, or it is invalid.
400	3	The provider object does not contain an id, or it is invalid.
401	5	You do not have permission to view Providers.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	43	The Provider was not found by its unique identifier.
403	98	The Provider is suspended.

GET/providers/{providerId}/dashcams/live?camera=number

Gets the list of dashcam live metadata for the specified Provider.

URL Parameters

Parameter	Type	Required	Description
camera	byte?	optional	Optional camera number when multiple cameras are installed.
providerId	string	required	Unique identifier of the Provider.

Response description

Property	Type	Description
dashcams	Array.<DashcamDataLive>	The list of requested dashcam live image metadata.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
provider	RespIdendifier	An object to contain the "id" of the Provider to which the array of dashcam live image metadata belong.
provider.id	string	Identifier given as input for the command.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"dashcams": [
		{
			"altitude": number,
			"asset": number,
			"bytes": number,
			"camera": number,
			"company": number,
			"dts": string,
			"heading": number,
			"kind": string,
			"latitude": number,
			"longitude": number,
			"provider": string,
			"size": {
				"height": number,
				"width": number
			},
			"speed": number
		}
	],
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"provider": {
		"id": string
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a provider object, or it is invalid.
400	3	The provider object does not contain an id, or it is invalid.
401	5	You do not have permission to view Providers.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	43	The Provider was not found by its unique identifier.
403	98	The Provider is suspended.

Icons

GET/companies/{companyId}/icons?branch=boolean&trunk=boolean&includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

Gets the list of Icons for the specified Company.

URL Parameters

Parameter	Type	Required	Default	Description
branch	boolean	optional	`false`	When true the list of Icons will include any publicly available Icons from the given Company's parent(s).
companyId	uint64	required		Unique identifier of the Company.
highest	uint64?	optional		When using , sets the largest valued id objects to retrieve.
includeArchive	boolean	optional		Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional		False by default, but when true, the command will also return deleted objects.
limit	uint16?	optional		When using , sets the maximum number of objects retrieved from the archive.
lowest	uint64?	optional		When using , sets the smallest valued id objects to retrieve.
trunk	boolean	optional	`true`	When true the list of Icons from the given Company and all child-companies are returned. Otherwise, only Icons from the given Company are included.

Response description

Property	Type	Description
company	RespId	An object to contain the "id" of the Company to which the array of Icons belong.
company.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
icons	Array.<Icon>	The list of requested Icons.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"icons": [
		{
			"badge": {
				"align": string,
				"anchor": {
					"x": number,
					"y": number
				},
				"colour": string
			},
			"category": string,
			"company": number,
			"global": boolean,
			"glyphs": [
				{
					"anchor": {
						"x": number,
						"y": number
					},
					"layer": string,
					"rotates": boolean,
					"size": {
						"height": number,
						"width": number
					},
					"src": string,
					"tags": [
						string
					],
					"zIndex": number
				}
			],
			"id": number,
			"label": {
				"align": string,
				"anchor": {
					"x": number,
					"y": number
				},
				"colour": string
			},
			"name": string,
			"notes": string,
			"processedUtc": string,
			"updated": {
			},
			"usage": [
				string
			],
			"v": [
				number
			]
		}
	],
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
401	5	You do not have permission to view Icons for this Company.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company was not found by its unique identifier.

GET/icons?branch=boolean&trunk=boolean&includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

This request is an alias of /companies/{your-company-id}/icons?branch=true.

URL Parameters

Parameter	Type	Required	Default	Description
branch	boolean	optional	`false`	Defaults to false for this alias.
highest	uint64	optional		When using , sets the maximum id when listing from the database.
includeArchive	boolean	optional	`false`	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	`false`	False by default, but when true the command will also return deleted objects.
limit	uint16	optional		When using , sets the maximum number of objects in this response.
lowest	uint64	optional		When using , sets the minimum id when listing from the database.
trunk	boolean	optional	`true`	Defaults to true for this alias.
your-company-id	uint64	aliased	`{your-company-id}`	Your own Company's identifier.

PATCH/icons

Creates a new or updates an existing Icon.

HTTP Request body description

Property	Type	Required	Description
icon	Object.<string, ?>	always	A simple object to contain the Icon parameters.
icon.badge	IconLabel	optional	Definition for the name badge beside the Icon on a map.
icon.badge.align	string	optional	Determines which corner of the label is attached to the anchor.
icon.badge.anchor	Point	optional	The offset from the lat/long in pixels.
icon.badge.anchor.x	double	optional	Horizontal coordinate
icon.badge.anchor.y	double	optional	Vertical coordinate
icon.badge.colour	string	optional	Background colour of the label.
icon.category	string maximum-length: 100	optional	A noun to describe the type of thing represented. Like Truck, Car, Trailer, Hot-Air Balloon, etc...
icon.company	uint64?	create	The Company to which these Icons belongs.
icon.global	boolean	optional	Indicates whether this Icon is available to child companies.
icon.glyphs	Array.<IconGlyph>	optional	The images used to show the detail of this Icon.
icon.id	uint64?	update	The unique identifier of the Icon you want to update.
icon.label	IconLabel	optional	Definition for the name bubble above the Icon on a map.
icon.label.align	string	optional	Determines which corner of the label is attached to the anchor.
icon.label.anchor	Point	optional	The offset from the lat/long in pixels.
icon.label.anchor.x	double	optional	Horizontal coordinate
icon.label.anchor.y	double	optional	Vertical coordinate
icon.label.colour	string	optional	Background colour of the label.
icon.name	string maximum-length: 100	create	A specific adjective to describe the thing. Like Blue, Red, Empty, Full, etc...
icon.notes	string	optional	Notes.
icon.usage	Array.<string>	optional	A list of things that this Icon can be used to represent. Like `asset`, `place`, `user`, etc...
icon.v	Array.<int32>	optional
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"icon": {
		"badge": {
			"align": string,
			"anchor": {
				"x": number,
				"y": number
			},
			"colour": string
		},
		"category": string,
		"company": number,
		"global": boolean,
		"glyphs": [
			{
				"anchor": {
					"x": number,
					"y": number
				},
				"layer": string,
				"rotates": boolean,
				"size": {
					"height": number,
					"width": number
				},
				"src": string,
				"tags": [
					string
				],
				"zIndex": number
			}
		],
		"id": number,
		"label": {
			"align": string,
			"anchor": {
				"x": number,
				"y": number
			},
			"colour": string
		},
		"name": string,
		"notes": string,
		"usage": [
			string
		],
		"v": [
			number
		]
	},
	"reqId": number
}

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
icon	RespIdCompany	An object which contains the "id" and "company" keys when there is no error.
icon.company	uint64	Identifier of the Company to which this object belongs.
icon.id	uint64?	Identifier given as input for the command.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"icon": {
		"company": number,
		"id": number
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a icon object, or it is invalid.
400	3	Not enough keys exist in the icon object.
400	3	The icon.usage was invalid.
400	3	During create: When creating a new Icon, a company was not given.
400	3	During create: When creating a new Icon, a name was not given, or it is invalid.
400	3	During update: When updating a Icon, the id was invalid.
400	3	During update: When updating a Icon, the name was given as blank.
400	3	During update: When updating a Icon, the v was not an array, or contained too few numbers.
400	3	One of the icon.glyphs values is invalid. Returns an ErrorDetailInput as the `errorDetails`.
401	5	You do not have permission to create a new Icon.
401	5	You do not have permission to update this Icon.
400	6	During update: When updating a Icon, an incorrect v value was given as input.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	33	During update: The Icon was not found by its unique identifier.
409	130	During update: When updating a Icon, the company can not be changed.

DELETE/icons

Deletes an existing Icon.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
icon	RespDeleted	An object which contains the Icon's id, owning Company id, and deleted status.
icon.company	uint64	Identifier of the Company to which this object belongs.
icon.deleted	boolean	Flag showing if the object is deleted.
icon.id	uint64?	Identifier given as input for the command.
icon.v	Array.<uint32>
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"icon": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a icon object, or it is invalid.
400	3	The icon object does not contain an id, or it is invalid.
401	5	You do not have permission to delete this Icon.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	33	The Icon was not found by its unique identifier.

GET/icons/{iconId}?includeDeleted=boolean

Gets details of the specified Icon.

URL Parameters

Parameter	Type	Required	Description
iconId	uint64	required	Unique identifier of the Icon.
includeDeleted	boolean	optional	False by default, but when true the command will also return deleted objects.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
icon	Icon	The requested Icon.
icon.badge	IconLabel	Where the notification will appear for a mapped icon. Such as the number of dispatches an asset is working on, or the number of dispatches at a place.
icon.badge.align	string	Determines which corner of the label is attached to the anchor.
icon.badge.anchor	Point	The offset from the lat/long in pixels.
icon.badge.anchor.x	double	Horizontal coordinate
icon.badge.anchor.y	double	Vertical coordinate
icon.badge.colour	string	Background colour of the label.
icon.category	string maximum-length: 100	A noun to describe the type of thing represented. Like Truck, Car, Trailer, Hot-Air Balloon, etc...
icon.company	uint64 see: Company.id	The company to which this icon belongs.
icon.global	boolean	Indicates whether this icon is available to child companies.
icon.glyphs	Array.<IconGlyph>	The images used to show the detail of this icon.
icon.id	uint64	Unique identifier of this icon.
icon.label	IconLabel	Definition for the name bubble above the icon on a map.
icon.label.align	string	Determines which corner of the label is attached to the anchor.
icon.label.anchor	Point	The offset from the lat/long in pixels.
icon.label.anchor.x	double	Horizontal coordinate
icon.label.anchor.y	double	Vertical coordinate
icon.label.colour	string	Background colour of the label.
icon.name	string maximum-length: 100	A specific adjective to describe the thing. Like Blue, Red, Empty, Full, etc...
icon.notes	string	Notes.
icon.processedUtc	datetime	When the was change procesed.
icon.updated		by: login, from: monster
icon.usage	Array.<string>	A list of things that this icon can be used to represent. Like asset, place, user, etc...
icon.v	Array.<uint32>	Object version keys used to validate synchronization for all object properties.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"icon": {
		"badge": {
			"align": string,
			"anchor": {
				"x": number,
				"y": number
			},
			"colour": string
		},
		"category": string,
		"company": number,
		"global": boolean,
		"glyphs": [
			{
				"anchor": {
					"x": number,
					"y": number
				},
				"layer": string,
				"rotates": boolean,
				"size": {
					"height": number,
					"width": number
				},
				"src": string,
				"tags": [
					string
				],
				"zIndex": number
			}
		],
		"id": number,
		"label": {
			"align": string,
			"anchor": {
				"x": number,
				"y": number
			},
			"colour": string
		},
		"name": string,
		"notes": string,
		"processedUtc": string,
		"updated": {
		},
		"usage": [
			string
		],
		"v": [
			number
		]
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a icon object, or it is invalid.
400	3	The icon object does not contain an id, or it is invalid.
401	5	You do not have permission to view this Icon.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	33	The Icon was not found by its unique identifier.

POST/icons/{iconId}

Creates a new or updates an existing Icon.

URL Parameters

Parameter	Type	Required	Description
iconId	uint64?	optional	Unique identifier of the Icon. This value is optional, and ignored by the command.

HTTP Request body description

Property	Type	Required	Description
icon	Object.<string, ?>	always	A simple object to contain the Icon parameters.
icon.badge	IconLabel	optional	Definition for the name badge beside the Icon on a map.
icon.badge.align	string	optional	Determines which corner of the label is attached to the anchor.
icon.badge.anchor	Point	optional	The offset from the lat/long in pixels.
icon.badge.anchor.x	double	optional	Horizontal coordinate
icon.badge.anchor.y	double	optional	Vertical coordinate
icon.badge.colour	string	optional	Background colour of the label.
icon.category	string maximum-length: 100	optional	A noun to describe the type of thing represented. Like Truck, Car, Trailer, Hot-Air Balloon, etc...
icon.company	uint64?	create	The Company to which these Icons belongs.
icon.global	boolean	optional	Indicates whether this Icon is available to child companies.
icon.glyphs	Array.<IconGlyph>	optional	The images used to show the detail of this Icon.
icon.id	uint64?	update	The unique identifier of the Icon you want to update.
icon.label	IconLabel	optional	Definition for the name bubble above the Icon on a map.
icon.label.align	string	optional	Determines which corner of the label is attached to the anchor.
icon.label.anchor	Point	optional	The offset from the lat/long in pixels.
icon.label.anchor.x	double	optional	Horizontal coordinate
icon.label.anchor.y	double	optional	Vertical coordinate
icon.label.colour	string	optional	Background colour of the label.
icon.name	string maximum-length: 100	create	A specific adjective to describe the thing. Like Blue, Red, Empty, Full, etc...
icon.notes	string	optional	Notes.
icon.usage	Array.<string>	optional	A list of things that this Icon can be used to represent. Like `asset`, `place`, `user`, etc...
icon.v	Array.<int32>	optional
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"icon": {
		"badge": {
			"align": string,
			"anchor": {
				"x": number,
				"y": number
			},
			"colour": string
		},
		"category": string,
		"company": number,
		"global": boolean,
		"glyphs": [
			{
				"anchor": {
					"x": number,
					"y": number
				},
				"layer": string,
				"rotates": boolean,
				"size": {
					"height": number,
					"width": number
				},
				"src": string,
				"tags": [
					string
				],
				"zIndex": number
			}
		],
		"id": number,
		"label": {
			"align": string,
			"anchor": {
				"x": number,
				"y": number
			},
			"colour": string
		},
		"name": string,
		"notes": string,
		"usage": [
			string
		],
		"v": [
			number
		]
	},
	"reqId": number
}

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
icon	RespIdCompany	An object which contains the "id" and "company" keys when there is no error.
icon.company	uint64	Identifier of the Company to which this object belongs.
icon.id	uint64?	Identifier given as input for the command.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"icon": {
		"company": number,
		"id": number
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a icon object, or it is invalid.
400	3	Not enough keys exist in the icon object.
400	3	The icon.usage was invalid.
400	3	During create: When creating a new Icon, a company was not given.
400	3	During create: When creating a new Icon, a name was not given, or it is invalid.
400	3	During update: When updating a Icon, the id was invalid.
400	3	During update: When updating a Icon, the name was given as blank.
400	3	During update: When updating a Icon, the v was not an array, or contained too few numbers.
400	3	One of the icon.glyphs values is invalid. Returns an ErrorDetailInput as the `errorDetails`.
401	5	You do not have permission to create a new Icon.
401	5	You do not have permission to update this Icon.
400	6	During update: When updating a Icon, an incorrect v value was given as input.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	33	During update: The Icon was not found by its unique identifier.
409	130	During update: When updating a Icon, the company can not be changed.

DELETE/icons/{iconId}

Deletes an existing Icon.

URL Parameters

Parameter	Type	Required	Description
iconId	uint64	required	Unique identifier of the Icon.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
icon	RespDeleted	An object which contains the Icon's id, owning Company id, and deleted status.
icon.company	uint64	Identifier of the Company to which this object belongs.
icon.deleted	boolean	Flag showing if the object is deleted.
icon.id	uint64?	Identifier given as input for the command.
icon.v	Array.<uint32>
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"icon": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a icon object, or it is invalid.
400	3	The icon object does not contain an id, or it is invalid.
401	5	You do not have permission to delete this Icon.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	33	The Icon was not found by its unique identifier.

PATCH/icons/{iconId}/restore

Restores the specified Icon.

URL Parameters

Parameter	Type	Required	Description
iconId	uint64	required	Unique identifier of the Icon.

HTTP Request body description

Property	Type	Required	Description
icon	ParamId	always	An object to contain the "id" of the Icon.
icon.id	uint64	always	Identifier given as input for the command.
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"icon": {
		"id": number
	},
	"reqId": number
}

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
icon	RespDeleted	An object which contains the Icon's id, owning Company id, and deleted status.
icon.company	uint64	Identifier of the Company to which this object belongs.
icon.deleted	boolean	Flag showing if the object is deleted.
icon.id	uint64?	Identifier given as input for the command.
icon.v	Array.<uint32>
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"icon": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a icon object, or it is invalid.
400	3	The icon object does not contain an id, or it is invalid.
401	5	You do not have permission to restore this Icon.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	33	The Icon was not found by its unique identifier.
400	34	The Icon was found, but is not marked as deleted.

Maintenance

GET/assets/{assetId}/maintenance/jobs?pending=boolean&includeDeleted=boolean&includeArchive=boolean&limit=number&after=string&before=string

Gets a list of MaintenanceJobs by the asset.

URL Parameters

Parameter	Type	Required	Description
after	datetime	optional	When using , sets the earliest objects (by dts) to retrieve from the archive.
assetId	uint64	required	Unique identifier of the Asset.
before	datetime	optional	When using , sets the most recent objects (by dts) to retrieve from the archive.
includeArchive	boolean	optional	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	False by default, but when true the command will also return deleted objects.
limit	uint16?	optional	When using , sets the maximum number of objects retrieved from the archive.
pending	boolean	optional	When true, will include all MaintenanceJobStatus.pending and MaintenanceJobStatus.pastdue jobs.

Response description

Property	Type	Description
asset	RespIdCompany	An object to contain the "id" of the Asset to which the array of MaintenanceJobs belong.
asset.company	uint64	Identifier of the Company to which this object belongs.
asset.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
maintenanceJobs	Array.<MaintenanceJob>	The list of requested MaintenanceJobs.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"asset": {
		"company": number,
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"maintenanceJobs": [
		{
			"asset": number,
			"company": number,
			"completed": string,
			"cost": number,
			"created": string,
			"duration": string,
			"engineHours": number,
			"garage": string,
			"id": number,
			"name": string,
			"notes": string,
			"odometer": number,
			"pictures": [
				number
			],
			"processedUtc": string,
			"reference": string,
			"schedule": number,
			"status": string,
			"technician": string,
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a asset object, or it is invalid.
400	3	The asset object does not contain an id, or it is invalid.
400	3	The (optional) before date is invalid.
400	3	The (optional) after date is invalid.
401	5	You do not have permission to view this MaintenanceJob.
401	5	You do not have permission to view this Asset's MaintenanceJobs.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	20	The Asset was not found by its unique identifier.

GET/companies/{companyId}/maintenance/jobs?pending=boolean&includeDeleted=boolean&includeArchive=boolean&limit=number&after=string&before=string

Gets a list of MaintenanceJobs by the Company.

URL Parameters

Parameter	Type	Required	Description
after	datetime	optional	When using , sets the earliest objects (by dts) to retrieve from the archive.
before	datetime	optional	When using , sets the most recent objects (by dts) to retrieve from the archive.
companyId	uint64	required	Unique identifier of the Company.
includeArchive	boolean	optional	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	False by default, but when true the command will also return deleted objects.
limit	uint16?	optional	When using , sets the maximum number of objects retrieved from the archive.
pending	boolean	optional	When true, will include all MaintenanceJobStatus.pending and MaintenanceJobStatus.pastdue jobs.

Response description

Property	Type	Description
company	RespId	An object to contain the "id" of the Company to which the array of MaintenanceJobs belong.
company.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
maintenanceJobs	Array.<MaintenanceJob>	The list of requested MaintenanceJobs.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"maintenanceJobs": [
		{
			"asset": number,
			"company": number,
			"completed": string,
			"cost": number,
			"created": string,
			"duration": string,
			"engineHours": number,
			"garage": string,
			"id": number,
			"name": string,
			"notes": string,
			"odometer": number,
			"pictures": [
				number
			],
			"processedUtc": string,
			"reference": string,
			"schedule": number,
			"status": string,
			"technician": string,
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
400	3	The (optional) before date is invalid.
400	3	The (optional) after date is invalid.
401	5	You do not have permission to view this MaintenanceJob.
401	5	You do not have permission to view any Assets in the given Company.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company was not found by its unique identifier.

GET/companies/{companyId}/maintenance/schedules?includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

Gets the list of MaintenanceSchedules for the specified Company.

URL Parameters

Parameter	Type	Required	Description
companyId	uint64	required	Unique identifier of the Company.
highest	uint64?	optional	When using , sets the largest valued id objects to retrieve.
includeArchive	boolean	optional	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	False by default, but when true, the command will also return deleted objects.
limit	uint16?	optional	When using , sets the maximum number of objects retrieved from the archive.
lowest	uint64?	optional	When using , sets the smallest valued id objects to retrieve.

Response description

Property	Type	Description
company	RespId	An object to contain the "id" of the Company to which the array of MaintenanceSchedules belong.
company.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
maintenanceSchedules	Array.<MaintenanceSchedule>	The list of requested MaintenanceSchedules.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"maintenanceSchedules": [
		{
			"company": number,
			"cost": number,
			"duration": string,
			"fill": string,
			"garage": string,
			"graphic": string,
			"id": number,
			"intervals": {
				string: {
					"asset": number,
					"date": string,
					"engineHours": number,
					"lastJob": number,
					"odometer": number
				}
			},
			"name": string,
			"notes": string,
			"notify": [
				string
			],
			"predictionDays": number,
			"processedUtc": string,
			"recurDays": number,
			"recurDistance": number,
			"recurEngineHours": number,
			"reference": string,
			"stroke": string,
			"targets": string,
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
401	5	You do not have permission to view this MaintenanceSchedule.
401	5	You do not have permission to view any assets in the given Company.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.

GET/maintenance/jobs?pending=boolean&includeDeleted=boolean&includeArchive=boolean&limit=number&after=string&before=string

This request is an alias of /companies/{your-company-id}/maintenance/jobs.

URL Parameters

Parameter	Type	Required	Default	Description
after	datetime	optional		When using , sets the earliest objects (by dts) to retrieve from the archive.
before	datetime	optional		When using , sets the most recent objects (by dts) to retrieve from the archive.
includeArchive	boolean	optional	`false`	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	`false`	False by default, but when true the command will also return deleted objects.
limit	uint16	optional		When using , sets the maximum number of objects retrieved from the archive.
pending	boolean	optional		When true, will include all MaintenanceJobStatus.pending and MaintenanceJobStatus.pastdue jobs.
your-company-id	uint64	aliased	`{your-company-id}`	Your own Company's identifier.

PATCH/maintenance/jobs

Creates a new or updates an existing MaintenanceJob.

HTTP Request body description

Property	Type	Required	Description
maintenanceJob	Object.<string, ?>	always	A simple object to contain the MaintenanceJob parameters.
maintenanceJob.asset	uint64?	create	The identifier of the Asset to which this MaintenanceJob is assigned.
maintenanceJob.completed	datetime	optional	When was this MaintenanceJob created.
maintenanceJob.cost	double?	optional	How much the MaintenanceJob cost in dollars.
maintenanceJob.created	datetime	optional	When was this MaintenanceJob created.
maintenanceJob.duration	timespan	optional	Time it took to complete the MaintenanceJob.
maintenanceJob.engineHours	double?	optional	The operating time at the time of the service.
maintenanceJob.garage	string maximum-length: 100	optional	The name of the garage or service facility where the work is done.
maintenanceJob.id	uint64?	update	The unique identifier of the MaintenanceJob you want to update.
maintenanceJob.name	string maximum-length: 100	create	The work being done. Like "oil change".
maintenanceJob.notes	string	optional	Notes about the MaintenanceJob. Like "changed the oil and filter".
maintenanceJob.odometer	double?	optional	The odometer at the time of the service.
maintenanceJob.pictures	Array.<uint64> for values see: Picture.id	optional	Pictures taken while performing the work for reference.
maintenanceJob.reference	string maximum-length: 100	optional	A reference code used to track this MaintenanceJob.
maintenanceJob.schedule	uint64? see: MaintenanceSchedule.id	optional	The MaintenanceSchedule from which this job was created
maintenanceJob.status	MaintenanceJobStatus?	optional	The status of this MaintenanceJob.
maintenanceJob.technician	string maximum-length: 100	optional	The mechanic who performed the work.
maintenanceJob.v	Array.<int32>	optional
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"maintenanceJob": {
		"asset": number,
		"completed": string,
		"cost": number,
		"created": string,
		"duration": string,
		"engineHours": number,
		"garage": string,
		"id": number,
		"name": string,
		"notes": string,
		"odometer": number,
		"pictures": [
			number
		],
		"reference": string,
		"schedule": number,
		"status": string,
		"technician": string,
		"v": [
			number
		]
	},
	"reqId": number
}

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
maintenanceJob	RespIdAsset	An object which contains the "id", "asset", and "company" keys.
maintenanceJob.asset	uint64	Identifier of the Asset to which this object belongs
maintenanceJob.company	uint64	Identifier of the Company to which this object belongs.
maintenanceJob.id	uint64?	Identifier given as input for the command.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"maintenanceJob": {
		"asset": number,
		"company": number,
		"id": number
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a maintenanceJob object, or it is invalid.
400	3	Not enough keys exist in the maintenanceJob object.
400	3	The given maintenanceJob.completed is too far into the future.
400	3	maintenanceJob.asset can not be changed
400	3	The given maintenanceJob.asset was invalid.
400	3	The given maintenanceJob.schedule was invalid.
400	3	The given maintenanceJob.status was invalid.
400	3	The given maintenanceJob.created date was invalid.
400	3	The given maintenanceJob.completed date was invalid.
400	3	The given maintenanceJob.odometer was invalid.
400	3	The given maintenanceJob.engineHours was invalid.
400	3	The given maintenanceJob.duration was invalid, or it was not positive.
400	3	The given maintenanceJob.cost was invalid.
400	3	The given maintenanceJob.pictures was invalid.
400	3	During create: When creating a new MaintenanceJob, a maintenanceJob.name was not given, or it is invalid.
400	3	During update: When updating a MaintenanceJob, the maintenanceJob.id was invalid.
400	3	During update: When updating a MaintenanceJob, the maintenanceJob.name was given as blank.
400	3	During update: When updating a MaintenanceJob, the v was not an array, or contained too few numbers.
400	3	One of the maintenanceJob.pictures values is invalid. Returns an ErrorDetailInput as the `errorDetails`.
401	5	You do not have permission to create a new MaintenanceJob.
401	5	You do not have permission to update this MaintenanceJob.
401	5	You do not have permission to view the target Asset.
400	6	During update: When updating a MaintenanceJob, an incorrect v value was given as input.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	20	The Asset was not found by its unique identifier.
404	35	The MaintenanceJob was not found by its unique identifier.
404	37	The MaintenanceSchedule was not found by its unique identifier.
404	69	One or more Pictures were not found by their unique identifiers.
409	130	The maintenanceJob.schedule and maintenanceJob.asset belong to different companies.
409	130	During update: When updating a MaintenanceJob, the maintenanceJob.asset can not be changed.

DELETE/maintenance/jobs

Deletes an existing MaintenanceJob.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
maintenanceJob	RespAssetDeleted	An object which contains the MaintenanceJob's id, owning Company id, related Asset id, and deleted status.
maintenanceJob.asset	uint64	Identifier of the Asset to which this object belongs.
maintenanceJob.company	uint64	Identifier of the Company to which this object belongs.
maintenanceJob.deleted	boolean	Flag showing if the object is deleted.
maintenanceJob.id	uint64?	Identifier given as input for the command.
maintenanceJob.v	Array.<uint32>
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"maintenanceJob": {
		"asset": number,
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a maintenanceJob object, or it is invalid.
400	3	The maintenanceJob object does not contain an id, or it is invalid.
401	5	You do not have permission to delete this MaintenanceJob.
401	5	You do not have permission to view this MaintenanceJob's Asset.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	20	The Asset was not found by its unique identifier. If you receive this error, please contact technical support.
404	35	The MaintenanceJob was not found by its unique identifier.

GET/maintenance/jobs/{jobId}?includeDeleted=boolean

Gets details of the specified MaintenanceJob.

URL Parameters

Parameter	Type	Required	Description
includeDeleted	boolean	optional	False by default, but when true the command will also return deleted objects.
jobId	uint64	required	Unique identifier of the MaintenanceJob.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
maintenanceJob	MaintenanceJob	The requested MaintenanceJob.
maintenanceJob.asset	uint64 see: Asset.id	The Vehicle or Trailer to which this job belongs
maintenanceJob.company	uint64 see: Company.id	The company to which this Vehicle or Trailer belongs
maintenanceJob.completed	datetime	When was this job created.
maintenanceJob.cost	double	How much the job cost in dollars.
maintenanceJob.created	datetime	When was this job created.
maintenanceJob.duration	timespan	Time it took to complete the job.
maintenanceJob.engineHours	double?	The operating time at the time of the service.
maintenanceJob.garage	string maximum-length: 100	The name of the garage or service facility where the work is done.
maintenanceJob.id	uint64	Unique identifier
maintenanceJob.name	string maximum-length: 100	The work being done. Like "oil change".
maintenanceJob.notes	string	Notes about the job. Like "changed the oil and filter".
maintenanceJob.odometer	double?	The odometer at the time of the service.
maintenanceJob.pictures	Array.<uint64> see: Picture.id for values see: Picture.id	Images taken while performing the work for reference.
maintenanceJob.processedUtc	datetime	When the was change procesed.
maintenanceJob.reference	string maximum-length: 100	A reference code used to track this job
maintenanceJob.schedule	uint64? see: MaintenanceSchedule.id	The Maintenance Schedule from which this job was created
maintenanceJob.status	MaintenanceJobStatus	The status of this job.
maintenanceJob.technician	string maximum-length: 100	The mechanic who performed the work.
maintenanceJob.updated		by: login, from: monster
maintenanceJob.v	Array.<uint32>	Object version keys used to validate synchronization for all object properties.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"maintenanceJob": {
		"asset": number,
		"company": number,
		"completed": string,
		"cost": number,
		"created": string,
		"duration": string,
		"engineHours": number,
		"garage": string,
		"id": number,
		"name": string,
		"notes": string,
		"odometer": number,
		"pictures": [
			number
		],
		"processedUtc": string,
		"reference": string,
		"schedule": number,
		"status": string,
		"technician": string,
		"updated": {
		},
		"v": [
			number
		]
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a maintenanceJob object, or it is invalid.
400	3	The maintenanceJob object does not contain an id, or it is invalid.
401	5	You do not have permission to view this MaintenanceJob.
401	5	You do not have permission to view this MaintenanceJob's Asset.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	20	The Asset was not found by its unique identifier. If you receive this error, please contact technical support.
404	35	The MaintenanceJob was not found by its unique identifier.

POST/maintenance/jobs/{jobId}

Creates a new or updates an existing MaintenanceJob.

URL Parameters

Parameter	Type	Required	Description
jobId	uint64?	optional	Unique identifier of the MaintenanceJob. This value is optional, and ignored by the command.

HTTP Request body description

Property	Type	Required	Description
maintenanceJob	Object.<string, ?>	always	A simple object to contain the MaintenanceJob parameters.
maintenanceJob.asset	uint64?	create	The identifier of the Asset to which this MaintenanceJob is assigned.
maintenanceJob.completed	datetime	optional	When was this MaintenanceJob created.
maintenanceJob.cost	double?	optional	How much the MaintenanceJob cost in dollars.
maintenanceJob.created	datetime	optional	When was this MaintenanceJob created.
maintenanceJob.duration	timespan	optional	Time it took to complete the MaintenanceJob.
maintenanceJob.engineHours	double?	optional	The operating time at the time of the service.
maintenanceJob.garage	string maximum-length: 100	optional	The name of the garage or service facility where the work is done.
maintenanceJob.id	uint64?	update	The unique identifier of the MaintenanceJob you want to update.
maintenanceJob.name	string maximum-length: 100	create	The work being done. Like "oil change".
maintenanceJob.notes	string	optional	Notes about the MaintenanceJob. Like "changed the oil and filter".
maintenanceJob.odometer	double?	optional	The odometer at the time of the service.
maintenanceJob.pictures	Array.<uint64> for values see: Picture.id	optional	Pictures taken while performing the work for reference.
maintenanceJob.reference	string maximum-length: 100	optional	A reference code used to track this MaintenanceJob.
maintenanceJob.schedule	uint64? see: MaintenanceSchedule.id	optional	The MaintenanceSchedule from which this job was created
maintenanceJob.status	MaintenanceJobStatus?	optional	The status of this MaintenanceJob.
maintenanceJob.technician	string maximum-length: 100	optional	The mechanic who performed the work.
maintenanceJob.v	Array.<int32>	optional
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"maintenanceJob": {
		"asset": number,
		"completed": string,
		"cost": number,
		"created": string,
		"duration": string,
		"engineHours": number,
		"garage": string,
		"id": number,
		"name": string,
		"notes": string,
		"odometer": number,
		"pictures": [
			number
		],
		"reference": string,
		"schedule": number,
		"status": string,
		"technician": string,
		"v": [
			number
		]
	},
	"reqId": number
}

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
maintenanceJob	RespIdAsset	An object which contains the "id", "asset", and "company" keys.
maintenanceJob.asset	uint64	Identifier of the Asset to which this object belongs
maintenanceJob.company	uint64	Identifier of the Company to which this object belongs.
maintenanceJob.id	uint64?	Identifier given as input for the command.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"maintenanceJob": {
		"asset": number,
		"company": number,
		"id": number
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a maintenanceJob object, or it is invalid.
400	3	Not enough keys exist in the maintenanceJob object.
400	3	The given maintenanceJob.completed is too far into the future.
400	3	maintenanceJob.asset can not be changed
400	3	The given maintenanceJob.asset was invalid.
400	3	The given maintenanceJob.schedule was invalid.
400	3	The given maintenanceJob.status was invalid.
400	3	The given maintenanceJob.created date was invalid.
400	3	The given maintenanceJob.completed date was invalid.
400	3	The given maintenanceJob.odometer was invalid.
400	3	The given maintenanceJob.engineHours was invalid.
400	3	The given maintenanceJob.duration was invalid, or it was not positive.
400	3	The given maintenanceJob.cost was invalid.
400	3	The given maintenanceJob.pictures was invalid.
400	3	During create: When creating a new MaintenanceJob, a maintenanceJob.name was not given, or it is invalid.
400	3	During update: When updating a MaintenanceJob, the maintenanceJob.id was invalid.
400	3	During update: When updating a MaintenanceJob, the maintenanceJob.name was given as blank.
400	3	During update: When updating a MaintenanceJob, the v was not an array, or contained too few numbers.
400	3	One of the maintenanceJob.pictures values is invalid. Returns an ErrorDetailInput as the `errorDetails`.
401	5	You do not have permission to create a new MaintenanceJob.
401	5	You do not have permission to update this MaintenanceJob.
401	5	You do not have permission to view the target Asset.
400	6	During update: When updating a MaintenanceJob, an incorrect v value was given as input.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	20	The Asset was not found by its unique identifier.
404	35	The MaintenanceJob was not found by its unique identifier.
404	37	The MaintenanceSchedule was not found by its unique identifier.
404	69	One or more Pictures were not found by their unique identifiers.
409	130	The maintenanceJob.schedule and maintenanceJob.asset belong to different companies.
409	130	During update: When updating a MaintenanceJob, the maintenanceJob.asset can not be changed.

DELETE/maintenance/jobs/{jobId}

Deletes an existing MaintenanceJob.

URL Parameters

Parameter	Type	Required	Description
jobId	uint64	required	Unique identifier of the MaintenanceJob.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
maintenanceJob	RespAssetDeleted	An object which contains the MaintenanceJob's id, owning Company id, related Asset id, and deleted status.
maintenanceJob.asset	uint64	Identifier of the Asset to which this object belongs.
maintenanceJob.company	uint64	Identifier of the Company to which this object belongs.
maintenanceJob.deleted	boolean	Flag showing if the object is deleted.
maintenanceJob.id	uint64?	Identifier given as input for the command.
maintenanceJob.v	Array.<uint32>
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"maintenanceJob": {
		"asset": number,
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a maintenanceJob object, or it is invalid.
400	3	The maintenanceJob object does not contain an id, or it is invalid.
401	5	You do not have permission to delete this MaintenanceJob.
401	5	You do not have permission to view this MaintenanceJob's Asset.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	20	The Asset was not found by its unique identifier. If you receive this error, please contact technical support.
404	35	The MaintenanceJob was not found by its unique identifier.

PATCH/maintenance/jobs/{jobId}/restore

Restores the specified MaintenanceJob.

URL Parameters

Parameter	Type	Required	Description
jobId	uint64	required	Unique identifier of the MaintenanceJob.

HTTP Request body description

Property	Type	Required	Description
maintenanceJob	ParamId	always	An object to contain the "id" of the MaintenanceJob.
maintenanceJob.id	uint64	always	Identifier given as input for the command.
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"maintenanceJob": {
		"id": number
	},
	"reqId": number
}

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
maintenanceJob	RespAssetDeleted	An object which contains the MaintenanceJob's id, owning Company id, related Asset id, and deleted status.
maintenanceJob.asset	uint64	Identifier of the Asset to which this object belongs.
maintenanceJob.company	uint64	Identifier of the Company to which this object belongs.
maintenanceJob.deleted	boolean	Flag showing if the object is deleted.
maintenanceJob.id	uint64?	Identifier given as input for the command.
maintenanceJob.v	Array.<uint32>
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"maintenanceJob": {
		"asset": number,
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a maintenanceJob object, or it is invalid.
400	3	The maintenanceJob object does not contain an id, or it is invalid.
401	5	You do not have permission to restore this MaintenanceJob.
401	5	You do not have permission to view this MaintenanceJob's Asset.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	20	The Asset was not found by its unique identifier. If you receive this error, please contact technical support.
404	35	The MaintenanceJob was not found by its unique identifier.
400	36	The MaintenanceJob was found, but is not marked as deleted.

GET/maintenance/schedules?includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

This request is an alias of /companies/{your-company-id}/maintenance/schedules.

URL Parameters

Parameter	Type	Required	Default	Description
highest	uint64	optional		When using , sets the maximum id when listing from the database.
includeArchive	boolean	optional	`false`	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	`false`	False by default, but when true the command will also return deleted objects.
limit	uint16	optional		When using , sets the maximum number of objects in this response.
lowest	uint64	optional		When using , sets the minimum id when listing from the database.
your-company-id	uint64	aliased	`{your-company-id}`	Your own Company's identifier.

PATCH/maintenance/schedules

Creates a new or updates an existing MaintenanceSchedule.

HTTP Request body description

Property	Type	Required	Description
maintenanceSchedule	Object.<string, ?>	always	A simple object to contain the MaintenanceSchedule parameters.
maintenanceSchedule.company	uint64?	optional	The company to which this MaintenanceSchedule. After creation, this value is read-only.
maintenanceSchedule.cost	double?	optional	The estimated cost for the created MaintenanceJob cost in dollars.
maintenanceSchedule.duration	timespan	optional	The estimated time for the created MaintenanceJob.
maintenanceSchedule.fill	string maximum-length: 22	optional	The fill/background colour of the icon. Should be a hex colour in the format #RRGGBB.
maintenanceSchedule.garage	string maximum-length: 100	optional	The name of the garage or service facility where the work is done.
maintenanceSchedule.graphic	codified maximum-length: 22	optional	The name of the symbol for this report.
maintenanceSchedule.id	uint64?	update	The unique identifier of the MaintenanceSchedule you want to update.
maintenanceSchedule.intervals	Object.<uint64, MaintenanceInterval>	optional	The per-Asset details calculated by the system to help predict the creation of MaintenanceJobs.
maintenanceSchedule.name	string maximum-length: 100	create	The name of the MaintenanceSchedule.
maintenanceSchedule.notes	string	optional	Notes about the MaintenanceSchedule.
maintenanceSchedule.notify	Array.<email>	optional	List of Users to send notifications.
maintenanceSchedule.predictionDays	uint32?	optional	The number of days in advance to predict a MaintenanceJob will become pending.
maintenanceSchedule.recurDays	uint32?	optional	The number of days between service visits.
maintenanceSchedule.recurDistance	double?	optional	The amount of mileage between service visits.
maintenanceSchedule.recurEngineHours	double?	optional	The number of operating hours between service visits.
maintenanceSchedule.reference	string maximum-length: 100	optional	A reference code used to track this created MaintenanceJob.
maintenanceSchedule.stroke	string maximum-length: 22	optional	Outline and graphic colour. Should be a hex colour in the format #RRGGBB.
maintenanceSchedule.targets	expression	optional	Which Assets are targetted by this MaintenanceSchedule.
maintenanceSchedule.v	Array.<int32>	optional
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"maintenanceSchedule": {
		"company": number,
		"cost": number,
		"duration": string,
		"fill": string,
		"garage": string,
		"graphic": string,
		"id": number,
		"intervals": {
			string: {
				"asset": number,
				"date": string,
				"engineHours": number,
				"lastJob": number,
				"odometer": number
			}
		},
		"name": string,
		"notes": string,
		"notify": [
			string
		],
		"predictionDays": number,
		"recurDays": number,
		"recurDistance": number,
		"recurEngineHours": number,
		"reference": string,
		"stroke": string,
		"targets": string,
		"v": [
			number
		]
	},
	"reqId": number
}

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
maintenanceSchedule	RespIdCompany	An object which contains the "id" and "company" keys.
maintenanceSchedule.company	uint64	Identifier of the Company to which this object belongs.
maintenanceSchedule.id	uint64?	Identifier given as input for the command.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"maintenanceSchedule": {
		"company": number,
		"id": number
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a maintenanceSchedule object, or it is invalid.
400	3	Not enough keys exist in the maintenanceSchedule object.
400	3	The maintenanceSchedule.name was not given, or it is invalid.
400	3	The maintenanceSchedule.notify was invalid.
400	3	The maintenanceSchedule.predictionDays was invalid, or the value was not between 5 and 180.
400	3	The maintenanceSchedule.recurDays was invalid.
400	3	The maintenanceSchedule.recurDistance was invalid.
400	3	The maintenanceSchedule.recurEngineHours was invalid.
400	3	The maintenanceSchedule.intervals was invalid.
400	3	The maintenanceSchedule.duration was invalid, or it was not positive.
400	3	The maintenanceSchedule.cost was invalid.
400	3	The maintenanceSchedule.notify was invalid.
400	3	One of the maintenanceSchedule.notify values was invalid.
400	3	The maintenanceSchedule.intervals was invalid.
400	3	One of the maintenanceSchedule.intervals values was invalid.
400	3	During create: The maintenanceSchedule.company was invalid.
400	3	During create: When creating a MaintenanceSchedule, the maintenanceSchedule.targets was invalid.
400	3	During update: When updating a MaintenanceSchedule, the maintenanceSchedule.id was invalid.
400	3	During update: When updating a MaintenanceSchedule, the maintenanceSchedule.name was given as blank.
400	3	During update: When updating a MaintenanceSchedule, the v was not an array, or contained too few numbers.
401	5	You do not have permission to create a new MaintenanceSchedule.
401	5	You do not have permission to update this MaintenanceSchedule.
401	5	You do not have permission to view one of the Assets in a given maintenanceSchedule.intervals.
400	6	During update: When updating a MaintenanceSchedule, an incorrect v value was given as input.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	20	The Asset was not found by its unique identifier.
404	37	The MaintenanceSchedule was not found by its unique identifier.
409	130	During update: When updating a MaintenanceSchedule, the maintenanceSchedule.companycompany was provided as a different value.

DELETE/maintenance/schedules

Deletes an existing MaintenanceSchedule.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
maintenanceSchedule	RespDeleted	An object which contains the MaintenanceSchedule's unique identifier and deleted status.
maintenanceSchedule.company	uint64	Identifier of the Company to which this object belongs.
maintenanceSchedule.deleted	boolean	Flag showing if the object is deleted.
maintenanceSchedule.id	uint64?	Identifier given as input for the command.
maintenanceSchedule.v	Array.<uint32>
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"maintenanceSchedule": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a maintenanceSchedule object, or it is invalid.
400	3	The maintenanceSchedule object does not contain an id, or it is invalid.
401	5	You do not have permission to delete this MaintenanceSchedule.
401	5	You do not have permission to view any Assets targeted by this MaintenanceSchedule.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	37	The MaintenanceSchedule was not found by its unique identifier.

GET/maintenance/schedules/{scheduleId}?includeDeleted=boolean

Gets details of the specified MaintenanceSchedule.

URL Parameters

Parameter	Type	Required	Description
includeDeleted	boolean	optional	False by default, but when true the command will also return deleted objects.
scheduleId	uint64	required	Unique identifier of the MaintenanceSchedule.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
maintenanceSchedule	MaintenanceSchedule	The requested MaintenanceSchedule.
maintenanceSchedule.company	uint64 see: Company.id	The company to which this schedule belongs
maintenanceSchedule.cost	double	The estimated cost for the job cost in dollars.
maintenanceSchedule.duration	timespan	The estimated time for the job.
maintenanceSchedule.fill	colour maximum-length: 22	The fill/background colour of the icon.
maintenanceSchedule.garage	string maximum-length: 100	The name of the garage or service facility where the work is done.
maintenanceSchedule.graphic	codified maximum-length: 22	The name of the symbol for this schedule.
maintenanceSchedule.id	uint64	Unique identifier
maintenanceSchedule.intervals	Object.<uint64, MaintenanceInterval> for keys see: Asset.id	The per-asset details calculated by the system to help predict the creation of Maintenance Jobs.
maintenanceSchedule.name	string maximum-length: 100	The name of the work to be done. Like "oil change".
maintenanceSchedule.notes	string	Notes about the work to be done. Like "change the oil and oil filter".
maintenanceSchedule.notify	Array.<email> for values see: User.login	List of Users to send notifications.
maintenanceSchedule.predictionDays	uint32	The number of days in advance to predict a job will become pending.
maintenanceSchedule.processedUtc	datetime	When the was change procesed.
maintenanceSchedule.recurDays	uint32?	The number of days between service visits.
maintenanceSchedule.recurDistance	double?	The amount of mileage between service visits.
maintenanceSchedule.recurEngineHours	double?	The number of operating hours between service visits.
maintenanceSchedule.reference	string maximum-length: 100	A reference code used to track this job
maintenanceSchedule.stroke	colour maximum-length: 22	Outline and graphic colour.
maintenanceSchedule.targets	expression	The targeting expression to select which Vehicles and Trailers require this maintenance work.
maintenanceSchedule.updated		by: login, from: monster
maintenanceSchedule.v	Array.<uint32>	Object version keys used to validate synchronization for all object properties.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"maintenanceSchedule": {
		"company": number,
		"cost": number,
		"duration": string,
		"fill": string,
		"garage": string,
		"graphic": string,
		"id": number,
		"intervals": {
			string: {
				"asset": number,
				"date": string,
				"engineHours": number,
				"lastJob": number,
				"odometer": number
			}
		},
		"name": string,
		"notes": string,
		"notify": [
			string
		],
		"predictionDays": number,
		"processedUtc": string,
		"recurDays": number,
		"recurDistance": number,
		"recurEngineHours": number,
		"reference": string,
		"stroke": string,
		"targets": string,
		"updated": {
		},
		"v": [
			number
		]
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a maintenanceSchedule object, or it is invalid.
400	3	The maintenanceSchedule object does not contain an id, or it is invalid.
401	5	You do not have permission to view this MaintenanceSchedule.
401	5	You do not have permission to view any assets in the given Company.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	37	The MaintenanceSchedule was not found by its unique identifier.

POST/maintenance/schedules/{scheduleId}

Creates a new or updates an existing MaintenanceSchedule.

URL Parameters

Parameter	Type	Required	Description
scheduleId	uint64?	optional	Unique identifier of the MaintenanceSchedule. This value is optional, and ignored by the command.

HTTP Request body description

Property	Type	Required	Description
maintenanceSchedule	Object.<string, ?>	always	A simple object to contain the MaintenanceSchedule parameters.
maintenanceSchedule.company	uint64?	optional	The company to which this MaintenanceSchedule. After creation, this value is read-only.
maintenanceSchedule.cost	double?	optional	The estimated cost for the created MaintenanceJob cost in dollars.
maintenanceSchedule.duration	timespan	optional	The estimated time for the created MaintenanceJob.
maintenanceSchedule.fill	string maximum-length: 22	optional	The fill/background colour of the icon. Should be a hex colour in the format #RRGGBB.
maintenanceSchedule.garage	string maximum-length: 100	optional	The name of the garage or service facility where the work is done.
maintenanceSchedule.graphic	codified maximum-length: 22	optional	The name of the symbol for this report.
maintenanceSchedule.id	uint64?	update	The unique identifier of the MaintenanceSchedule you want to update.
maintenanceSchedule.intervals	Object.<uint64, MaintenanceInterval>	optional	The per-Asset details calculated by the system to help predict the creation of MaintenanceJobs.
maintenanceSchedule.name	string maximum-length: 100	create	The name of the MaintenanceSchedule.
maintenanceSchedule.notes	string	optional	Notes about the MaintenanceSchedule.
maintenanceSchedule.notify	Array.<email>	optional	List of Users to send notifications.
maintenanceSchedule.predictionDays	uint32?	optional	The number of days in advance to predict a MaintenanceJob will become pending.
maintenanceSchedule.recurDays	uint32?	optional	The number of days between service visits.
maintenanceSchedule.recurDistance	double?	optional	The amount of mileage between service visits.
maintenanceSchedule.recurEngineHours	double?	optional	The number of operating hours between service visits.
maintenanceSchedule.reference	string maximum-length: 100	optional	A reference code used to track this created MaintenanceJob.
maintenanceSchedule.stroke	string maximum-length: 22	optional	Outline and graphic colour. Should be a hex colour in the format #RRGGBB.
maintenanceSchedule.targets	expression	optional	Which Assets are targetted by this MaintenanceSchedule.
maintenanceSchedule.v	Array.<int32>	optional
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"maintenanceSchedule": {
		"company": number,
		"cost": number,
		"duration": string,
		"fill": string,
		"garage": string,
		"graphic": string,
		"id": number,
		"intervals": {
			string: {
				"asset": number,
				"date": string,
				"engineHours": number,
				"lastJob": number,
				"odometer": number
			}
		},
		"name": string,
		"notes": string,
		"notify": [
			string
		],
		"predictionDays": number,
		"recurDays": number,
		"recurDistance": number,
		"recurEngineHours": number,
		"reference": string,
		"stroke": string,
		"targets": string,
		"v": [
			number
		]
	},
	"reqId": number
}

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
maintenanceSchedule	RespIdCompany	An object which contains the "id" and "company" keys.
maintenanceSchedule.company	uint64	Identifier of the Company to which this object belongs.
maintenanceSchedule.id	uint64?	Identifier given as input for the command.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"maintenanceSchedule": {
		"company": number,
		"id": number
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a maintenanceSchedule object, or it is invalid.
400	3	Not enough keys exist in the maintenanceSchedule object.
400	3	The maintenanceSchedule.name was not given, or it is invalid.
400	3	The maintenanceSchedule.notify was invalid.
400	3	The maintenanceSchedule.predictionDays was invalid, or the value was not between 5 and 180.
400	3	The maintenanceSchedule.recurDays was invalid.
400	3	The maintenanceSchedule.recurDistance was invalid.
400	3	The maintenanceSchedule.recurEngineHours was invalid.
400	3	The maintenanceSchedule.intervals was invalid.
400	3	The maintenanceSchedule.duration was invalid, or it was not positive.
400	3	The maintenanceSchedule.cost was invalid.
400	3	The maintenanceSchedule.notify was invalid.
400	3	One of the maintenanceSchedule.notify values was invalid.
400	3	The maintenanceSchedule.intervals was invalid.
400	3	One of the maintenanceSchedule.intervals values was invalid.
400	3	During create: The maintenanceSchedule.company was invalid.
400	3	During create: When creating a MaintenanceSchedule, the maintenanceSchedule.targets was invalid.
400	3	During update: When updating a MaintenanceSchedule, the maintenanceSchedule.id was invalid.
400	3	During update: When updating a MaintenanceSchedule, the maintenanceSchedule.name was given as blank.
400	3	During update: When updating a MaintenanceSchedule, the v was not an array, or contained too few numbers.
401	5	You do not have permission to create a new MaintenanceSchedule.
401	5	You do not have permission to update this MaintenanceSchedule.
401	5	You do not have permission to view one of the Assets in a given maintenanceSchedule.intervals.
400	6	During update: When updating a MaintenanceSchedule, an incorrect v value was given as input.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	20	The Asset was not found by its unique identifier.
404	37	The MaintenanceSchedule was not found by its unique identifier.
409	130	During update: When updating a MaintenanceSchedule, the maintenanceSchedule.companycompany was provided as a different value.

DELETE/maintenance/schedules/{scheduleId}

Deletes an existing MaintenanceSchedule.

URL Parameters

Parameter	Type	Required	Description
scheduleId	uint64	required	Unique identifier of the MaintenanceSchedule.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
maintenanceSchedule	RespDeleted	An object which contains the MaintenanceSchedule's unique identifier and deleted status.
maintenanceSchedule.company	uint64	Identifier of the Company to which this object belongs.
maintenanceSchedule.deleted	boolean	Flag showing if the object is deleted.
maintenanceSchedule.id	uint64?	Identifier given as input for the command.
maintenanceSchedule.v	Array.<uint32>
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"maintenanceSchedule": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a maintenanceSchedule object, or it is invalid.
400	3	The maintenanceSchedule object does not contain an id, or it is invalid.
401	5	You do not have permission to delete this MaintenanceSchedule.
401	5	You do not have permission to view any Assets targeted by this MaintenanceSchedule.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	37	The MaintenanceSchedule was not found by its unique identifier.

GET/maintenance/schedules/{scheduleId}/jobs?pending=boolean&includeDeleted=boolean&includeArchive=boolean&limit=number&after=string&before=string

Gets a list of MaintenanceJobs by the schedule under which they were created/completed.

URL Parameters

Parameter	Type	Required	Description
after	datetime	optional	When using , sets the earliest objects (by dts) to retrieve from the archive.
before	datetime	optional	When using , sets the most recent objects (by dts) to retrieve from the archive.
includeArchive	boolean	optional	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	False by default, but when true the command will also return deleted objects.
limit	uint16?	optional	When using , sets the maximum number of objects retrieved from the archive.
pending	boolean	optional	When true, will include all MaintenanceJobStatus.pending and MaintenanceJobStatus.pastdue jobs.
scheduleId	uint64	required	Unique identifier of the MaintenanceSchedule.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
maintenanceJobs	Array.<MaintenanceJob>	The list of requested MaintenanceJobs.
maintenanceSchedule	RespIdCompany	An object to contain the "id" of the MaintenanceSchedule to which the array of MaintenanceJobs belong.
maintenanceSchedule.company	uint64	Identifier of the Company to which this object belongs.
maintenanceSchedule.id	uint64?	Identifier given as input for the command.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"maintenanceJobs": [
		{
			"asset": number,
			"company": number,
			"completed": string,
			"cost": number,
			"created": string,
			"duration": string,
			"engineHours": number,
			"garage": string,
			"id": number,
			"name": string,
			"notes": string,
			"odometer": number,
			"pictures": [
				number
			],
			"processedUtc": string,
			"reference": string,
			"schedule": number,
			"status": string,
			"technician": string,
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"maintenanceSchedule": {
		"company": number,
		"id": number
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a maintenanceSchedule object, or it is invalid.
400	3	The maintenanceSchedule object does not contain an id, or it is invalid.
400	3	The (optional) before date is invalid.
400	3	The (optional) after date is invalid.
401	5	You do not have permission to view this MaintenanceJob.
401	5	You do not have permission to view any Assets in the given Company.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	37	The MaintenanceSchedule was not found by its unique identifier.

PATCH/maintenance/schedules/{scheduleId}/restore

Restores the specified MaintenanceSchedule.

URL Parameters

Parameter	Type	Required	Description
scheduleId	uint64	required	Unique identifier of the MaintenanceSchedule.

HTTP Request body description

Property	Type	Required	Description
maintenanceSchedule	ParamId	always	An object to contain the "id" of the MaintenanceSchedule.
maintenanceSchedule.id	uint64	always	Identifier given as input for the command.
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"maintenanceSchedule": {
		"id": number
	},
	"reqId": number
}

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
maintenanceSchedule	RespDeleted	An object which contains the MaintenanceSchedule's unique identifier and deleted status.
maintenanceSchedule.company	uint64	Identifier of the Company to which this object belongs.
maintenanceSchedule.deleted	boolean	Flag showing if the object is deleted.
maintenanceSchedule.id	uint64?	Identifier given as input for the command.
maintenanceSchedule.v	Array.<uint32>
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"maintenanceSchedule": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a maintenanceSchedule object, or it is invalid.
400	3	The maintenanceSchedule object does not contain an id, or it is invalid.
401	5	You do not have permission to restore this MaintenanceSchedule.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	37	The MaintenanceSchedule was not found by its unique identifier.
400	38	The MaintenanceSchedule was found, but is not marked as deleted.

Messaging

GET/assets/{assetId}/messages?includeDeleted=boolean&includeArchive=boolean&limit=number&after=string&before=string

Gets the list of AssetMessages for the specified Asset.

URL Parameters

Parameter	Type	Required	Description
after	datetime	optional	When using , sets the earliest objects (by dts) to retrieve from the archive.
assetId	uint64	required	Unique identifier of the Asset.
before	datetime	optional	When using , sets the most recent objects (by dts) to retrieve from the archive.
includeArchive	boolean	optional	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	False by default, but when true the command will also return deleted objects.
limit	uint16?	optional	When using , sets the maximum number of objects retrieved from the archive.

Response description

Property	Type	Description
asset	RespIdCompany	An object to contain the "id" of the Asset to which the array of AssetMessages belong.
asset.company	uint64	Identifier of the Company to which this object belongs.
asset.id	uint64?	Identifier given as input for the command.
assetMessages	Array.<AssetMessage>	The list of requested AssetMessages.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"asset": {
		"company": number,
		"id": number
	},
	"assetMessages": [
		{
			"asset": number,
			"body": string,
			"company": number,
			"delivered": string,
			"folder": string,
			"from": string,
			"id": number,
			"incoming": boolean,
			"kind": string,
			"processed": string,
			"processedUtc": string,
			"readBy": string,
			"status": string,
			"subject": string,
			"to": string,
			"updated": {
			},
			"user": string,
			"v": [
				number
			]
		}
	],
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request contains a folder value, but it is not valid.
400	3	The request does not contain a asset object, or it is invalid.
400	3	The asset object does not contain an id, or it is invalid.
401	5	You do not have permission to view AssetMessages.
401	5	You do not have permission to view the specified Asset.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	20	The Asset that owns this message was not found.
403	96	The Asset that owns this message is suspended. Before reading messages from a Asset, it must be reactivated.

GET/assets/messages?includeDeleted=boolean&includeArchive=boolean&limit=number&after=string&before=string

This request is an alias of /companies/{your-company-id}/assets/messages.

URL Parameters

Parameter	Type	Required	Default	Description
after	datetime	optional		When using , sets the earliest objects (by dts) to retrieve from the archive.
before	datetime	optional		When using , sets the most recent objects (by dts) to retrieve from the archive.
includeArchive	boolean	optional	`false`	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	`false`	False by default, but when true the command will also return deleted objects.
limit	uint16	optional		When using , sets the maximum number of objects retrieved from the archive.
your-company-id	uint64	aliased	`{your-company-id}`	Your own Company's identifier.

PATCH/assets/messages

Creates a new or updates an existing AssetMessage.

HTTP Request body description

Property	Type	Required	Description
assetMessage	Object.<string, ?>	always	A simple object to contain the AssetMessage parameters.
assetMessage.asset	uint64?	create	The Asset that this AssetMessage was sent from or to. After creation, this value is read-only.
assetMessage.body	string	create	The body of the AssetMessage. After creation, this value is read-only.
assetMessage.folder	MessageFolder?	optional	The folder where this AssetMessage is stored.
assetMessage.id	uint64?	update	The unique identifier of the AssetMessage you want to update.
assetMessage.kind	MessageType?	create	The kind of protocol used for this AssetMessage. After creation, this value is read-only.
assetMessage.read	boolean	optional	Set to true to log that the AssetMessage was received and read by yourself. Once set, the AssetMessage.readBy value will be your login, and cannot be set by anyone else.
assetMessage.subject	string	optional	The AssetMessage subject field. After creation, this value is read-only. This is used exclusively with MessageType.email type AssetMessages.
assetMessage.to	string	create	Optional to address used when creating the AssetMessage if no messaging address is available. After creation, this value is read-only.
assetMessage.v	Array.<int32>	optional
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"assetMessage": {
		"asset": number,
		"body": string,
		"folder": string,
		"id": number,
		"kind": string,
		"read": boolean,
		"subject": string,
		"to": string,
		"v": [
			number
		]
	},
	"reqId": number
}

Response description

Property	Type	Description
assetMessage	RespIdAsset	An object which contains the "id", "company", and "asset" keys when there is no error.
assetMessage.asset	uint64	Identifier of the Asset to which this object belongs
assetMessage.company	uint64	Identifier of the Company to which this object belongs.
assetMessage.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"assetMessage": {
		"asset": number,
		"company": number,
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain an assetMessage object, or it is invalid.
400	3	Not enough keys exist in the assetMessage object.
400	3	The folder was given, but is invalid.
400	3	During create: When creating a new AssetMessage, an assetMessage.asset was not given.
400	3	During create: When creating a new AssetMessage, a assetMessage.kind was not given.
400	3	During create: When creating a new AssetMessage, the assetMessage.kind was an invalid value.
400	3	During update: When updating a AssetMessage, the assetMessage.id was invalid.
400	3	During update: When updating a AssetMessage, the v was not an array, or contained too few numbers.
400	3	During update after read: When updating a AssetMessage after it has been read, the readBy field can not be changed.
401	5	You do not have permission to view the Asset to which the AssetMessage belongs.
401	5	During create: You do not have permission to send new AssetMessages.
401	5	During update: You do not have permission to update AssetMessages.
400	6	During update: When updating a AssetMessage, the wrong version key(s) were given.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	20	During create: The Asset that owns this AssetMessage was not found.
404	63	During update: The AssetMessage was not found by its unique identifier.
403	96	During create: The Asset that owns this AssetMessage is suspended. Before sending or updating AssetMessages from a Asset, it must be reactivated.
409	130	During update: When updating a AssetMessage, the asset can not be changed.
409	130	During update: When updating a AssetMessage, the kind field can not be changed.
409	130	During update: When updating a AssetMessage, the to field can not be changed.
409	130	During update after sent: When updating a AssetMessage after processing, the subject field can not be changed.
409	130	During update after sent: When updating a AssetMessage after processing, the body field can not be changed.

DELETE/assets/messages

Deletes an existing AssetMessage.

Response description

Property	Type	Description
assetMessage	RespAssetDeleted	An object which contains the AssetMessage's id, owning Company id, and deleted status.
assetMessage.asset	uint64	Identifier of the Asset to which this object belongs.
assetMessage.company	uint64	Identifier of the Company to which this object belongs.
assetMessage.deleted	boolean	Flag showing if the object is deleted.
assetMessage.id	uint64?	Identifier given as input for the command.
assetMessage.v	Array.<uint32>
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"assetMessage": {
		"asset": number,
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a assetMessage object, or it is invalid.
400	3	The assetMessage object does not contain an id, or it is invalid.
401	5	You do not have permission to delete AssetMessages.
401	5	You do not have permission to view the asset to which the AssetMessage belongs.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	20	The asset that owns this AssetMessage was not found. If you receive this error, please contact technical support.
404	63	The AssetMessage was not found by its unique identifier.
403	96	The asset that owns this AssetMessage is suspended. Before reading AssetMessages from an Asset, it must be reactivated.

GET/assets/messages/{msgId}?includeDeleted=boolean

Gets details of the specified AssetMessage.

URL Parameters

Parameter	Type	Required	Description
includeDeleted	boolean	optional	False by default, but when true the command will also return deleted objects.
msgId	uint64	required	Unique identifier of the AssetMessage.

Response description

Property	Type	Description
assetMessage	AssetMessage	The requested AssetMessage.
assetMessage.asset	uint64 see: Asset.id	The asset to which this message relates.
assetMessage.body	string	The main contents of the memo.
assetMessage.company	uint64 see: Company.id	The company to which this memo belongs.
assetMessage.delivered	datetime	Date/time stamp of when the memo was delivered (or sent if delivery information unavailable).
assetMessage.folder	MessageFolder	The folder under which this message is stored.
assetMessage.from	string maximum-length: 254 minimum-length: 6	Sender address
assetMessage.id	uint64	Unique identifier of this memo.
assetMessage.incoming	boolean	Indicates that this is a received message instead of a sent message.
assetMessage.kind	MessageType	Protocol type
assetMessage.processed	datetime	Date/time stamp of when the memo was processed.
assetMessage.processedUtc	datetime	When the was change procesed.
assetMessage.readBy	email see: User.login maximum-length: 254	The user that read this message. This field is blank/null when unread.
assetMessage.status	MessageStatus	Lifetime status
assetMessage.subject	string maximum-length: 100	The subject of this message.
assetMessage.to	string maximum-length: 254 minimum-length: 6	Recipient address
assetMessage.updated		by: login, from: monster
assetMessage.user	email see: User.login maximum-length: 254	The user who sent/received this message.
assetMessage.v	Array.<uint32>	Object version keys used to validate synchronization for all object properties.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"assetMessage": {
		"asset": number,
		"body": string,
		"company": number,
		"delivered": string,
		"folder": string,
		"from": string,
		"id": number,
		"incoming": boolean,
		"kind": string,
		"processed": string,
		"processedUtc": string,
		"readBy": string,
		"status": string,
		"subject": string,
		"to": string,
		"updated": {
		},
		"user": string,
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a assetMessage object, or it is invalid.
400	3	The assetMessage object does not contain an id, or it is invalid.
401	5	You do not have permission to view the AssetMessages.
401	5	You do not have permission to view the Asset to which the AssetMessage belongs.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	20	The Asset that owns this AssetMessage was not found. If you receive this error, please contact technical support.
404	63	The AssetMessage was not found by its unique identifier.
403	96	The Asset that owns this AssetMessage is suspended. Before reading AssetMessages from an Asset, it must be reactivated.

POST/assets/messages/{msgId}

Creates a new or updates an existing AssetMessage.

URL Parameters

Parameter	Type	Required	Description
msgId	uint64?	optional	Unique identifier of the AssetMessage. This value is optional, and ignored by the command.

HTTP Request body description

Property	Type	Required	Description
assetMessage	Object.<string, ?>	always	A simple object to contain the AssetMessage parameters.
assetMessage.asset	uint64?	create	The Asset that this AssetMessage was sent from or to. After creation, this value is read-only.
assetMessage.body	string	create	The body of the AssetMessage. After creation, this value is read-only.
assetMessage.folder	MessageFolder?	optional	The folder where this AssetMessage is stored.
assetMessage.id	uint64?	update	The unique identifier of the AssetMessage you want to update.
assetMessage.kind	MessageType?	create	The kind of protocol used for this AssetMessage. After creation, this value is read-only.
assetMessage.read	boolean	optional	Set to true to log that the AssetMessage was received and read by yourself. Once set, the AssetMessage.readBy value will be your login, and cannot be set by anyone else.
assetMessage.subject	string	optional	The AssetMessage subject field. After creation, this value is read-only. This is used exclusively with MessageType.email type AssetMessages.
assetMessage.to	string	create	Optional to address used when creating the AssetMessage if no messaging address is available. After creation, this value is read-only.
assetMessage.v	Array.<int32>	optional
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"assetMessage": {
		"asset": number,
		"body": string,
		"folder": string,
		"id": number,
		"kind": string,
		"read": boolean,
		"subject": string,
		"to": string,
		"v": [
			number
		]
	},
	"reqId": number
}

Response description

Property	Type	Description
assetMessage	RespIdAsset	An object which contains the "id", "company", and "asset" keys when there is no error.
assetMessage.asset	uint64	Identifier of the Asset to which this object belongs
assetMessage.company	uint64	Identifier of the Company to which this object belongs.
assetMessage.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"assetMessage": {
		"asset": number,
		"company": number,
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain an assetMessage object, or it is invalid.
400	3	Not enough keys exist in the assetMessage object.
400	3	The folder was given, but is invalid.
400	3	During create: When creating a new AssetMessage, an assetMessage.asset was not given.
400	3	During create: When creating a new AssetMessage, a assetMessage.kind was not given.
400	3	During create: When creating a new AssetMessage, the assetMessage.kind was an invalid value.
400	3	During update: When updating a AssetMessage, the assetMessage.id was invalid.
400	3	During update: When updating a AssetMessage, the v was not an array, or contained too few numbers.
400	3	During update after read: When updating a AssetMessage after it has been read, the readBy field can not be changed.
401	5	You do not have permission to view the Asset to which the AssetMessage belongs.
401	5	During create: You do not have permission to send new AssetMessages.
401	5	During update: You do not have permission to update AssetMessages.
400	6	During update: When updating a AssetMessage, the wrong version key(s) were given.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	20	During create: The Asset that owns this AssetMessage was not found.
404	63	During update: The AssetMessage was not found by its unique identifier.
403	96	During create: The Asset that owns this AssetMessage is suspended. Before sending or updating AssetMessages from a Asset, it must be reactivated.
409	130	During update: When updating a AssetMessage, the asset can not be changed.
409	130	During update: When updating a AssetMessage, the kind field can not be changed.
409	130	During update: When updating a AssetMessage, the to field can not be changed.
409	130	During update after sent: When updating a AssetMessage after processing, the subject field can not be changed.
409	130	During update after sent: When updating a AssetMessage after processing, the body field can not be changed.

DELETE/assets/messages/{msgId}

Deletes an existing AssetMessage.

URL Parameters

Parameter	Type	Required	Description
msgId	uint64	required	Unique identifier of the AssetMessage.

Response description

Property	Type	Description
assetMessage	RespAssetDeleted	An object which contains the AssetMessage's id, owning Company id, and deleted status.
assetMessage.asset	uint64	Identifier of the Asset to which this object belongs.
assetMessage.company	uint64	Identifier of the Company to which this object belongs.
assetMessage.deleted	boolean	Flag showing if the object is deleted.
assetMessage.id	uint64?	Identifier given as input for the command.
assetMessage.v	Array.<uint32>
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"assetMessage": {
		"asset": number,
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a assetMessage object, or it is invalid.
400	3	The assetMessage object does not contain an id, or it is invalid.
401	5	You do not have permission to delete AssetMessages.
401	5	You do not have permission to view the asset to which the AssetMessage belongs.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	20	The asset that owns this AssetMessage was not found. If you receive this error, please contact technical support.
404	63	The AssetMessage was not found by its unique identifier.
403	96	The asset that owns this AssetMessage is suspended. Before reading AssetMessages from an Asset, it must be reactivated.

PATCH/assets/messages/{msgId}/restore

Restores the specified AssetMessage to its previous version.

URL Parameters

Parameter	Type	Required	Description
msgId	uint64	required	Unique identifier of the AssetMessage.

HTTP Request body description

Property	Type	Required	Description
assetMessage	ParamId	always	An object to contain the "id" key.
assetMessage.id	uint64	always	Identifier given as input for the command.
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"assetMessage": {
		"id": number
	},
	"reqId": number
}

Response description

Property	Type	Description
assetMessage	RespAssetDeleted	An object which contains the AssetMessage's id, owning Company id, and deleted status.
assetMessage.asset	uint64	Identifier of the Asset to which this object belongs.
assetMessage.company	uint64	Identifier of the Company to which this object belongs.
assetMessage.deleted	boolean	Flag showing if the object is deleted.
assetMessage.id	uint64?	Identifier given as input for the command.
assetMessage.v	Array.<uint32>
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"assetMessage": {
		"asset": number,
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a assetMessage object, or it is invalid.
400	3	The assetMessage object does not contain an id, or it is invalid.
401	5	You do not have permission to restore AssetMessages.
401	5	You do not have permission to view the Asset to which the AssetMessage belongs.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	20	The Asset that owns this AssetMessage was not found. If you receive this error, please contact technical support.
404	63	The AssetMessage was not found by its unique identifier.
403	96	The Asset that owns this AssetMessage is suspended. Before reading AssetMessages from an Asset, it must be reactivated.
400	101	The AssetMessage was found, but is not marked as deleted.

GET/companies/{companyId}/assets/messages?includeDeleted=boolean&includeArchive=boolean&limit=number&after=string&before=string

Gets the list of AssetMessages for the specified Company.

URL Parameters

Parameter	Type	Required	Description
after	datetime	optional	When using , sets the earliest objects (by dts) to retrieve from the archive.
before	datetime	optional	When using , sets the most recent objects (by dts) to retrieve from the archive.
companyId	uint64	required	Unique identifier of the Company.
includeArchive	boolean	optional	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	False by default, but when true the command will also return deleted objects.
limit	uint16?	optional	When using , sets the maximum number of objects retrieved from the archive.

Response description

Property	Type	Description
assetMessages	Array.<AssetMessage>	The list of requested AssetMessages.
company	RespId	An object to contain the "id" of the Company to which the array of AssetMessages belong.
company.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"assetMessages": [
		{
			"asset": number,
			"body": string,
			"company": number,
			"delivered": string,
			"folder": string,
			"from": string,
			"id": number,
			"incoming": boolean,
			"kind": string,
			"processed": string,
			"processedUtc": string,
			"readBy": string,
			"status": string,
			"subject": string,
			"to": string,
			"updated": {
			},
			"user": string,
			"v": [
				number
			]
		}
	],
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request contains a folder value, but it is not valid.
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
401	5	You do not have permission to view any Assets in the given Company.
401	5	You do not have permission to view AssetMessages.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company was not found.

Places

GET/companies/{companyId}/places?includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

Gets the list of Places for the specified Company.

URL Parameters

Parameter	Type	Required	Description
companyId	uint64	required	Unique identifier of the Company.
highest	uint64?	optional	When using , sets the largest valued id objects to retrieve.
includeArchive	boolean	optional	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	False by default, but when true, the command will also return deleted objects.
limit	uint16?	optional	When using , sets the maximum number of objects retrieved from the archive.
lowest	uint64?	optional	When using , sets the smallest valued id objects to retrieve.

Response description

Property	Type	Description
company	RespId	An object to contain the "id" of the Company to which the array of Places belong.
company.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
places	Array.<Place>	The list of requested Places.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"places": [
		{
			"address": string,
			"anchor": {
				"lat": number,
				"lng": number
			},
			"colour": string,
			"company": number,
			"icon": number,
			"id": number,
			"kind": string,
			"labels": [
				string
			],
			"name": string,
			"notes": string,
			"pictures": [
				number
			],
			"processedUtc": string,
			"radius": number,
			"reference": string,
			"shape": [
				{
					"lat": number,
					"lng": number
				}
			],
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
401	5	You do not have permission to view any Places for this Company.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company was not found by its unique identifier.

GET/companies/{companyId}/places?labels={string}&includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

Gets the list of Places for the specified Company only if the Place.labels matches all of the given labels.

URL Parameters

Parameter	Type	Required	Description
companyId	uint64	required	Unique identifier of the Company.
highest	uint64?	optional	When using , sets the largest valued id objects to retrieve.
includeArchive	boolean	optional	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	False by default, but when true, the command will also return deleted objects.
labels	string	required	Labels to match the Place.
limit	uint16?	optional	When using , sets the maximum number of objects retrieved from the archive.
lowest	uint64?	optional	When using , sets the smallest valued id objects to retrieve.

Response description

Property	Type	Description
company	RespId	An object to contain the "id" of the Company to which the array of Places belong.
company.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
labels	Array.<string>	The labels given as input.
message	string	An English description of the error.
places	Array.<Place>	The list of requested Places.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"labels": [
		string
	],
	"message": string,
	"places": [
		{
			"address": string,
			"anchor": {
				"lat": number,
				"lng": number
			},
			"colour": string,
			"company": number,
			"icon": number,
			"id": number,
			"kind": string,
			"labels": [
				string
			],
			"name": string,
			"notes": string,
			"pictures": [
				number
			],
			"processedUtc": string,
			"radius": number,
			"reference": string,
			"shape": [
				{
					"lat": number,
					"lng": number
				}
			],
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
400	3	The labels is not an array.
401	5	You do not have permission to view any Places for this Company.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company was not found by its unique identifier.

GET/companies/{companyId}/places?reference={string}&includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

Gets the list of Places for the specified Company only if the Place reference field is a match.

URL Parameters

Parameter	Type	Required	Description
companyId	uint64	required	Unique identifier of the Company.
highest	uint64?	optional	When using , sets the largest valued id objects to retrieve.
includeArchive	boolean	optional	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	False by default, but when true, the command will also return deleted objects.
limit	uint16?	optional	When using , sets the maximum number of objects retrieved from the archive.
lowest	uint64?	optional	When using , sets the smallest valued id objects to retrieve.
reference	string	required	Value to search in the Place.reference field.

Response description

Property	Type	Description
company	RespId	An object to contain the "id" of the Company to which the array of Places belong.
company.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
places	Array.<Place>	The list of requested Places.
reference	string	The reference string given as input.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"places": [
		{
			"address": string,
			"anchor": {
				"lat": number,
				"lng": number
			},
			"colour": string,
			"company": number,
			"icon": number,
			"id": number,
			"kind": string,
			"labels": [
				string
			],
			"name": string,
			"notes": string,
			"pictures": [
				number
			],
			"processedUtc": string,
			"radius": number,
			"reference": string,
			"shape": [
				{
					"lat": number,
					"lng": number
				}
			],
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"reference": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
400	3	The reference is blank or null.
401	5	You do not have permission to view any Places for this Company.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company was not found by its unique identifier.

GET/places?includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

This request is an alias of /companies/{your-company-id}/places.

URL Parameters

Parameter	Type	Required	Default	Description
highest	uint64	optional		When using , sets the maximum id when listing from the database.
includeArchive	boolean	optional	`false`	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	`false`	False by default, but when true the command will also return deleted objects.
limit	uint16	optional		When using , sets the maximum number of objects in this response.
lowest	uint64	optional		When using , sets the minimum id when listing from the database.
your-company-id	uint64	aliased	`{your-company-id}`	Your own Company's identifier.

PATCH/places

Creates a new, or updates an existing Place.

HTTP Request body description

Property	Type	Required	Description
place	Object.<string, ?>	always	A simple object to contain the Place parameters.
place.address	string	optional	Full street address including province/state, country, and postal/zip code.
place.anchor	LatLng	optional	Central lat/long coordinates. When not present, the shape centre is used for routing.
place.anchor.lat	double	optional	Latitude
place.anchor.lng	double	optional	Longitude
place.colour	colour maximum-length: 22	optional	The fill colour given to this Place for easy visual identification on the map.
place.company	uint64?	create	The Company to which this Place belongs. After creation, this value is read-only.
place.icon	uint64? see: Icon.id	create	The Icon used to display this POI in lists and on the map.
place.id	uint64?	update	The unique identifier of the Place you want to update.
place.kind	PlaceType?	create	The kind of shape being created.
place.labels	Array.<codified> for values see: LabelStyle.code	optional	The codified names of labels
place.name	string maximum-length: 100	create	Name for the Place.
place.notes	string	optional	Notes for the Place.
place.pictures	Array.<uint64> for values see: Picture.id	optional	The identifiers of Pictures of this Place.
place.radius	double?	create (radial)	Boundary threshold (in meters)
place.reference	string maximum-length: 100	optional	A custom field used to refer to an external system.
place.shape	Array.<LatLng>	create (rectangle or polygon)	For a PlaceType.rectangle, the input contains the north east and south west corner coordinates. For a PlaceType.polygon, the input lists all coordinates (oriented as counter-clockwise) needed to draw the geofence.
place.v	Array.<int32>	optional
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"place": {
		"address": string,
		"anchor": {
			"lat": number,
			"lng": number
		},
		"colour": string,
		"company": number,
		"icon": number,
		"id": number,
		"kind": string,
		"labels": [
			string
		],
		"name": string,
		"notes": string,
		"pictures": [
			number
		],
		"radius": number,
		"reference": string,
		"shape": [
			{
				"lat": number,
				"lng": number
			}
		],
		"v": [
			number
		]
	},
	"reqId": number
}

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
place	RespIdCompany	An object which contains the "id" and "company" keys.
place.company	uint64	Identifier of the Company to which this object belongs.
place.id	uint64?	Identifier given as input for the command.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"place": {
		"company": number,
		"id": number
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a place object, or it is invalid.
400	3	No valid changes would be performed.
400	3	For a PlaceType.rectangle shape, the shape has fewer than 2 coordinates.
400	3	For a PlaceType.polygon shape, the shape has fewer than 3 coordinates.
400	3	During create: When creating a new Place, a name was not given.
400	3	During create: When creating a new Place, a company was not given.
400	3	During create: When creating a new Place, an icon was not given.
400	3	During update: When updating a Place, the name was given as null or blank.
400	3	During update: When updating a Place, the v was not an array, or contained too few numbers.
400	3	The place.kind was given, but it was invalid. Returns an ErrorDetailInput as the `errorDetails`.
400	3	The place.colour was given, but it was invalid. Returns an ErrorDetailInput as the `errorDetails`.
400	3	One of the place.pictures identifiers given in the array cannot be parsed, or is a value less than zero. Returns an ErrorDetailInput as the `errorDetails`.
400	3	The place.anchor was given, but it was invalid. Returns an ErrorDetailInput as the `errorDetails`.
400	3	One of the place.shape coordinates given in the array cannot be parsed, or is invalid. Returns an ErrorDetailInput as the `errorDetails`.
400	3	The place.shape string cannot be decoded using Google's Encoded Polyline algorithm. Returns an ErrorDetailInput as the `errorDetails`.
400	3	For a PlaceType.radial shape, the radius is outside of the size restrictions. Returns an ErrorDetailMinMax as the `errorDetails`.
400	3	For a PlaceType.rectangle shape, the diagonal distance is outside of the size restrictions. Returns an ErrorDetailMinMax as the `errorDetails`.
400	3	For a PlaceType.polygon shape, the widest diagonal distance is outside of the size restrictions. Returns an ErrorDetailMinMax as the `errorDetails`.
401	5	You do not have permission to create a new Place (with the given labels).
401	5	You do not have permission to update this Place.
400	6	During update: When updating a Place, an incorrect v value was given as input.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	33	The place.icon given as input was not found.
404	40	During update: The Place was not found by its unique identifier.
404	69	One or more of the Picture identifiers given as input in the place.pictures array was not found. Returns an ErrorDetailBadIds as the `errorDetails`.
401	71	During update: Changing the labels on this Place in the requested way would grant you elevated access to it. Returns an ErrorDetailEscalation as the `errorDetails`.
409	130	During create: When creating a new `point` or `radial` Place, an anchor or address was not given.
409	130	During update: When updating a Place, the place.company can not be changed.

DELETE/places

Deletes an existing Place.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
place	RespDeleted	An object which contains the place's id, owning company id, and deleted status.
place.company	uint64	Identifier of the Company to which this object belongs.
place.deleted	boolean	Flag showing if the object is deleted.
place.id	uint64?	Identifier given as input for the command.
place.v	Array.<uint32>
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"place": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a place object, or it is invalid.
400	3	The place object does not contain an id, or it is invalid.
401	5	You do not have permission to delete this Place.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	40	The Place was not found by its unique identifier.

GET/places/{placeId}?includeDeleted=boolean

Gets details of the specified Place.

URL Parameters

Parameter	Type	Required	Description
includeDeleted	boolean	optional	False by default, but when true the command will also return deleted objects.
placeId	uint64	required	Unique identifier of the Place.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
place	Place	The requested Place.
place.address	string maximum-length: 200	Full street address including province/state, country, and postal/zip code.
place.anchor	LatLng	A central point of the shape. This is the exact centre of a PlaceType.radial and PlaceType.point shaped places, and the location of the pin on the map for all types. When routing, PlaceType.polygon and PlaceType.rectangle shapes use the anchor as the location within the place for deliveries.
place.anchor.lat	double	Latitude
place.anchor.lng	double	Longitude
place.colour	colour maximum-length: 22	The fill colour given to this place for easy visual identification on the map (given in 24bit hex; #RRGGBB)
place.company	uint64 see: Company.id	The company to which this POI belongs.
place.icon	uint64 see: Icon.id	The icon used to display this POI in lists and on the map.
place.id	uint64	Unique identifier of this place.
place.kind	PlaceType	The kind of geography represented by this POI.
place.labels	Array.<codified> for values see: LabelStyle.code	The codified names of labels
place.name	string maximum-length: 100	POI's common name instead of street address.
place.notes	string	Notes!
place.pictures	Array.<uint64> for values see: Picture.id	Images of this POI.
place.processedUtc	datetime	When the was change procesed.
place.radius	double?	This member is only present for PlaceType.radial shapes, and is the radius in meters from the centre anchor.
place.reference	string maximum-length: 100	A custom field used to refer to an external system.
place.shape	Array.<LatLng>	The geography representing this POI for rectangle and polygon shape types. For PlaceType.radial and PlaceType.point shape types, the shape key is not present. For a PlaceType.rectangle, the array contains the north east and south west corner coordinates. For a PlaceType.polygon, the array lists all coordinates (oriented as counter-clockwise) needed to draw the geofence.
place.updated		by: login, from: monster
place.v	Array.<int32> fixed count: 2	Object version keys used to validate synchronization for all object properties.
place.v[0]	int32	The first element is for the general properties
place.v[1]	int32	The second element is not used
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"place": {
		"address": string,
		"anchor": {
			"lat": number,
			"lng": number
		},
		"colour": string,
		"company": number,
		"icon": number,
		"id": number,
		"kind": string,
		"labels": [
			string
		],
		"name": string,
		"notes": string,
		"pictures": [
			number
		],
		"processedUtc": string,
		"radius": number,
		"reference": string,
		"shape": [
			{
				"lat": number,
				"lng": number
			}
		],
		"updated": {
		},
		"v": [
			number
		]
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a place object, or it is invalid.
400	3	The place object does not contain an id, or it is invalid.
401	5	You do not have permission to view this Place.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	40	The Place was not found by its unique identifier.

POST/places/{placeId}

Creates a new, or updates an existing Place.

URL Parameters

Parameter	Type	Required	Description
placeId	uint64?	optional	Unique identifier of the Place. This value is optional, and ignored by the command.

HTTP Request body description

Property	Type	Required	Description
place	Object.<string, ?>	always	A simple object to contain the Place parameters.
place.address	string	optional	Full street address including province/state, country, and postal/zip code.
place.anchor	LatLng	optional	Central lat/long coordinates. When not present, the shape centre is used for routing.
place.anchor.lat	double	optional	Latitude
place.anchor.lng	double	optional	Longitude
place.colour	colour maximum-length: 22	optional	The fill colour given to this Place for easy visual identification on the map.
place.company	uint64?	create	The Company to which this Place belongs. After creation, this value is read-only.
place.icon	uint64? see: Icon.id	create	The Icon used to display this POI in lists and on the map.
place.id	uint64?	update	The unique identifier of the Place you want to update.
place.kind	PlaceType?	create	The kind of shape being created.
place.labels	Array.<codified> for values see: LabelStyle.code	optional	The codified names of labels
place.name	string maximum-length: 100	create	Name for the Place.
place.notes	string	optional	Notes for the Place.
place.pictures	Array.<uint64> for values see: Picture.id	optional	The identifiers of Pictures of this Place.
place.radius	double?	create (radial)	Boundary threshold (in meters)
place.reference	string maximum-length: 100	optional	A custom field used to refer to an external system.
place.shape	Array.<LatLng>	create (rectangle or polygon)	For a PlaceType.rectangle, the input contains the north east and south west corner coordinates. For a PlaceType.polygon, the input lists all coordinates (oriented as counter-clockwise) needed to draw the geofence.
place.v	Array.<int32>	optional
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"place": {
		"address": string,
		"anchor": {
			"lat": number,
			"lng": number
		},
		"colour": string,
		"company": number,
		"icon": number,
		"id": number,
		"kind": string,
		"labels": [
			string
		],
		"name": string,
		"notes": string,
		"pictures": [
			number
		],
		"radius": number,
		"reference": string,
		"shape": [
			{
				"lat": number,
				"lng": number
			}
		],
		"v": [
			number
		]
	},
	"reqId": number
}

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
place	RespIdCompany	An object which contains the "id" and "company" keys.
place.company	uint64	Identifier of the Company to which this object belongs.
place.id	uint64?	Identifier given as input for the command.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"place": {
		"company": number,
		"id": number
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a place object, or it is invalid.
400	3	No valid changes would be performed.
400	3	For a PlaceType.rectangle shape, the shape has fewer than 2 coordinates.
400	3	For a PlaceType.polygon shape, the shape has fewer than 3 coordinates.
400	3	During create: When creating a new Place, a name was not given.
400	3	During create: When creating a new Place, a company was not given.
400	3	During create: When creating a new Place, an icon was not given.
400	3	During update: When updating a Place, the name was given as null or blank.
400	3	During update: When updating a Place, the v was not an array, or contained too few numbers.
400	3	The place.kind was given, but it was invalid. Returns an ErrorDetailInput as the `errorDetails`.
400	3	The place.colour was given, but it was invalid. Returns an ErrorDetailInput as the `errorDetails`.
400	3	One of the place.pictures identifiers given in the array cannot be parsed, or is a value less than zero. Returns an ErrorDetailInput as the `errorDetails`.
400	3	The place.anchor was given, but it was invalid. Returns an ErrorDetailInput as the `errorDetails`.
400	3	One of the place.shape coordinates given in the array cannot be parsed, or is invalid. Returns an ErrorDetailInput as the `errorDetails`.
400	3	The place.shape string cannot be decoded using Google's Encoded Polyline algorithm. Returns an ErrorDetailInput as the `errorDetails`.
400	3	For a PlaceType.radial shape, the radius is outside of the size restrictions. Returns an ErrorDetailMinMax as the `errorDetails`.
400	3	For a PlaceType.rectangle shape, the diagonal distance is outside of the size restrictions. Returns an ErrorDetailMinMax as the `errorDetails`.
400	3	For a PlaceType.polygon shape, the widest diagonal distance is outside of the size restrictions. Returns an ErrorDetailMinMax as the `errorDetails`.
401	5	You do not have permission to create a new Place (with the given labels).
401	5	You do not have permission to update this Place.
400	6	During update: When updating a Place, an incorrect v value was given as input.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	33	The place.icon given as input was not found.
404	40	During update: The Place was not found by its unique identifier.
404	69	One or more of the Picture identifiers given as input in the place.pictures array was not found. Returns an ErrorDetailBadIds as the `errorDetails`.
401	71	During update: Changing the labels on this Place in the requested way would grant you elevated access to it. Returns an ErrorDetailEscalation as the `errorDetails`.
409	130	During create: When creating a new `point` or `radial` Place, an anchor or address was not given.
409	130	During update: When updating a Place, the place.company can not be changed.

DELETE/places/{placeId}

Deletes an existing Place.

URL Parameters

Parameter	Type	Required	Description
placeId	uint64	required	Unique identifier of the Place.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
place	RespDeleted	An object which contains the place's id, owning company id, and deleted status.
place.company	uint64	Identifier of the Company to which this object belongs.
place.deleted	boolean	Flag showing if the object is deleted.
place.id	uint64?	Identifier given as input for the command.
place.v	Array.<uint32>
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"place": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a place object, or it is invalid.
400	3	The place object does not contain an id, or it is invalid.
401	5	You do not have permission to delete this Place.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	40	The Place was not found by its unique identifier.

PATCH/places/{placeId}/restore

Restores the specified Place.

URL Parameters

Parameter	Type	Required	Description
placeId	uint64	required	Unique identifier of the Place.

HTTP Request body description

Property	Type	Required	Description
place	ParamId	always	An object to contain the "id" of the Place.
place.id	uint64	always	Identifier given as input for the command.
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"place": {
		"id": number
	},
	"reqId": number
}

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
place	RespDeleted	An object which contains the place's id, owning company id, and deleted status.
place.company	uint64	Identifier of the Company to which this object belongs.
place.deleted	boolean	Flag showing if the object is deleted.
place.id	uint64?	Identifier given as input for the command.
place.v	Array.<uint32>
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"place": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a place object, or it is invalid.
400	3	The place object does not contain an id, or it is invalid.
401	5	You do not have permission to restore this Place.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	40	The Place was not found by its unique identifier.
400	41	The Place was found, but is not marked as deleted.

GET/places?labels={string}&includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

This request is an alias of /companies/{your-company-id}/places?labels={labels}.

URL Parameters

Parameter	Type	Required	Default	Description
highest	uint64	optional		When using , sets the maximum id when listing from the database.
includeArchive	boolean	optional	`false`	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	`false`	False by default, but when true the command will also return deleted objects.
labels	string	required		Labels to match the Place.
limit	uint16	optional		When using , sets the maximum number of objects in this response.
lowest	uint64	optional		When using , sets the minimum id when listing from the database.
your-company-id	uint64	aliased	`{your-company-id}`	Your own Company's identifier.

GET/places?reference={string}&includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

This request is an alias of /companies/{your-company-id}/places?reference={reference}.

URL Parameters

Parameter	Type	Required	Default	Description
highest	uint64	optional		When using , sets the maximum id when listing from the database.
includeArchive	boolean	optional	`false`	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	`false`	False by default, but when true the command will also return deleted objects.
limit	uint16	optional		When using , sets the maximum number of objects in this response.
lowest	uint64	optional		When using , sets the minimum id when listing from the database.
reference	string	required		Value to search in the Place.reference field.
your-company-id	uint64	aliased	`{your-company-id}`	Your own Company's identifier.

Providers and Configurations

GET/companies/{companyId}/providers?includeSuspended=boolean&includeDeleted=boolean&includeArchive=boolean&limit=number&first=string&last=string

Gets the list of Providers for the specified Company.

URL Parameters

Parameter	Type	Required	Default	Description
companyId	uint64	required		Unique identifier of the Company.
first	string	optional		When using , sets the first alphabetic Provider.id when listing from the database.
includeArchive	boolean	optional		Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional		False by default, but when true, the command will also return deleted objects.
includeSuspended	boolean	optional	`true`	When true (default), the command will also return Providers marked as Provider.suspended.
last	string	optional		When using , sets the last alphabetic Provider.id when listing from the database.
limit	uint16?	optional		When using , sets the maximum number of objects retrieved from the archive.

Response description

Property	Type	Description
company	RespId	An object to contain the "id" of the Company to which the array of Providers belong.
company.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
providers	Array.<Provider>	The list of requested Providers.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"providers": [
		{
			"asset": number,
			"attributes": {
				string: {
					string: {
						"dts": string,
						"unit": string,
						"value": Object
					}
				}
			},
			"commands": {
				string: {
					"created": string,
					"parameters": [
						string
					],
					"processed": string,
					"status": string
				}
			},
			"company": number,
			"configuration": number,
			"control": {
				"commands": {
					string: {
						"created": string,
						"parameters": [
							string
						],
						"processed": string,
						"status": string
					}
				},
				"company": number,
				"id": string,
				"processedUtc": string,
				"updated": {
				},
				"v": [
					number
				]
			},
			"firmware": string,
			"firmwareStatus": string,
			"geofenceLast": string,
			"geofenceStatus": string,
			"id": string,
			"information": {
				string: string
			},
			"kind": string,
			"lastCheckIn": string,
			"lastIP": string,
			"name": string,
			"notes": string,
			"password": string,
			"phoneNumber": number,
			"pnd": string,
			"processedUtc": string,
			"scriptLast": string,
			"scriptStatus": string,
			"sim": string,
			"snf": {
				string: string
			},
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
401	5	You do not have permission to view Providers for this Company.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company was not found by its unique identifier.

GET/companies/{companyId}/providers/advanceds?includeSuspended=boolean&includeDeleted=boolean&includeArchive=boolean&limit=number&first=string&last=string

Gets the list of Providers for the specified Company.

URL Parameters

Parameter	Type	Required	Default	Description
companyId	uint64	required		Unique identifier of the Company.
first	string	optional		When using , sets the first alphabetic Provider.id when listing from the database.
includeArchive	boolean	optional		Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional		False by default, but when true, the command will also return deleted objects.
includeSuspended	boolean	optional	`true`	When true (default), the command will also return Providers marked as Provider.suspended.
last	string	optional		When using , sets the last alphabetic Provider.id when listing from the database.
limit	uint16?	optional		When using , sets the maximum number of objects retrieved from the archive.

Response description

Property	Type	Description
company	RespId	An object to contain the "id" of the Company to which the array of Providers belong.
company.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
providerAdvanceds	Array.<ProviderAdvanced>	The list of requested Providers.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"providerAdvanceds": [
		{
			"attributes": {
				string: {
					string: {
						"dts": string,
						"unit": string,
						"value": Object
					}
				}
			},
			"company": number,
			"id": string,
			"lastIP": string,
			"processedUtc": string,
			"snf": {
				string: string
			},
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
401	5	You do not have permission to view Providers for this Company.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company was not found by its unique identifier.

GET/companies/{companyId}/providers/configs?includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

Gets the list of ProviderConfigs for the specified Company.

URL Parameters

Parameter	Type	Required	Description
companyId	uint64	required	Unique identifier of the Company.
highest	uint64?	optional	When using , sets the largest valued id objects to retrieve.
includeArchive	boolean	optional	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	False by default, but when true, the command will also return deleted objects.
limit	uint16?	optional	When using , sets the maximum number of objects retrieved from the archive.
lowest	uint64?	optional	When using , sets the smallest valued id objects to retrieve.

Response description

Property	Type	Description
company	RespId	An object to contain the "id" of the Company to which the array of ProviderConfigs belong.
company.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
providerConfigs	Array.<ProviderConfig>	The list of reqested ProviderConfigs.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"providerConfigs": [
		{
			"company": number,
			"geofences": string,
			"id": number,
			"name": string,
			"notes": string,
			"parameters": {
				string: string
			},
			"processedUtc": string,
			"script": number,
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
401	5	You do not have permission to view this Company.
401	5	You do not have permission to view ProviderConfigs for this Company.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company was not found by its unique identifier.

GET/companies/{companyId}/providers/configurations?includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

Gets the list of ProviderConfigurations for the specified Company.

URL Parameters

Parameter	Type	Required	Description
companyId	uint64	required	Unique identifier of the Company.
highest	uint64?	optional	When using , sets the largest valued id objects to retrieve.
includeArchive	boolean	optional	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	False by default, but when true, the command will also return deleted objects.
limit	uint16?	optional	When using , sets the maximum number of objects retrieved from the archive.
lowest	uint64?	optional	When using , sets the smallest valued id objects to retrieve.

Response description

Property	Type	Description
company	RespId	An object to contain the "id" of the Company.
company.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
providerConfigurations	Array.<ProviderConfiguration>	The list of reqested ProviderConfigurations.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"providerConfigurations": [
		{
			"company": number,
			"geofences": [
				number
			],
			"id": number,
			"name": string,
			"notes": string,
			"processedUtc": string,
			"scriptParameters": {
				string: Object
			},
			"type": number,
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
401	5	You do not have permission to view this Company.
401	5	You do not have permission to view ProviderConfigurations for this Company.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company was not found by its unique identifier.

GET/companies/{companyId}/providers/generals?includeSuspended=boolean&includeDeleted=boolean&includeArchive=boolean&limit=number&first=string&last=string

Gets the list of Providers for the specified Company.

URL Parameters

Parameter	Type	Required	Default	Description
companyId	uint64	required		Unique identifier of the Company.
first	string	optional		When using , sets the first alphabetic Provider.id when listing from the database.
includeArchive	boolean	optional		Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional		False by default, but when true, the command will also return deleted objects.
includeSuspended	boolean	optional	`true`	When true (default), the command will also return Providers marked as Provider.suspended.
last	string	optional		When using , sets the last alphabetic Provider.id when listing from the database.
limit	uint16?	optional		When using , sets the maximum number of objects retrieved from the archive.

Response description

Property	Type	Description
company	RespId	An object to contain the "id" of the Company to which the array of Providers belong.
company.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
providerGenerals	Array.<ProviderGeneral>	The list of requested Providers.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"providerGenerals": [
		{
			"asset": number,
			"company": number,
			"configuration": number,
			"firmware": string,
			"firmwareStatus": string,
			"geofenceLast": string,
			"geofenceStatus": string,
			"id": string,
			"information": {
				string: string
			},
			"kind": string,
			"lastCheckIn": string,
			"name": string,
			"notes": string,
			"password": string,
			"phoneNumber": number,
			"pnd": string,
			"processedUtc": string,
			"scriptLast": string,
			"scriptStatus": string,
			"sim": string,
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
401	5	You do not have permission to view Providers for this Company.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company was not found by its unique identifier.

GET/companies/{companyId}/providers/registrations?includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

Gets the list of ProviderRegistrations for the specified Company.

URL Parameters

Parameter	Type	Required	Description
companyId	uint64	required	Unique identifier of the Company.
highest	uint64?	optional	When using , sets the largest valued id objects to retrieve.
includeArchive	boolean	optional	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	False by default, but when true, the command will also return deleted objects.
limit	uint16?	optional	When using , sets the maximum number of objects retrieved from the archive.
lowest	uint64?	optional	When using , sets the smallest valued id objects to retrieve.

Response description

Property	Type	Description
company	RespId	An object to contain the "id" of the Company to which the array of providers belong.
company.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
providerRegistrations	Array.<ProviderRegistration>	The list of ProviderRegistrations.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"providerRegistrations": [
		{
			"asset": number,
			"code": string,
			"company": number,
			"completed": string,
			"config": number,
			"expires": string,
			"identifier": string,
			"kind": string,
			"name": string,
			"notes": string,
			"password": string,
			"phoneNumber": number,
			"since": string,
			"user": string
		}
	],
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a company object, or it is invalid.
400	3	The company id is not an integer or is less than zero.
401	5	You do not have access to the ProviderConfigs/ProviderConfigurations.
401	5	You do not have access to view Providers.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company value is valid, but could not be found.

GET/companies/{companyId}/providers/registrations?kind={string}&includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

Gets the list of ProviderRegistrations for the specified Company.

URL Parameters

Parameter	Type	Required	Description
companyId	uint64	required	Unique identifier of the Company.
highest	uint64?	optional	When using , sets the largest valued id objects to retrieve.
includeArchive	boolean	optional	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	False by default, but when true, the command will also return deleted objects.
kind	string	required	The ProviderType used to filter the results.
limit	uint16?	optional	When using , sets the maximum number of objects retrieved from the archive.
lowest	uint64?	optional	When using , sets the smallest valued id objects to retrieve.

Response description

Property	Type	Description
company	RespId	An object to contain the "id" of the Company to which the array of providers belong.
company.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
providerRegistrations	Array.<ProviderRegistration>	The list of ProviderRegistrations.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"providerRegistrations": [
		{
			"asset": number,
			"code": string,
			"company": number,
			"completed": string,
			"config": number,
			"expires": string,
			"identifier": string,
			"kind": string,
			"name": string,
			"notes": string,
			"password": string,
			"phoneNumber": number,
			"since": string,
			"user": string
		}
	],
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a company object, or it is invalid.
400	3	The company id is not an integer or is less than zero.
401	5	You do not have access to the ProviderConfigs/ProviderConfigurations.
401	5	You do not have access to view Providers.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company value is valid, but could not be found.

GET/companies/{companyId}/providers/scripts?trunk=boolean&includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

Gets the list of ProviderScripts for the specified Company.

URL Parameters

Parameter	Type	Required	Default	Description
companyId	uint64	required		Unique identifier of the Company.
highest	uint64?	optional		When using , sets the largest valued id objects to retrieve.
includeArchive	boolean	optional		Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional		False by default, but when true, the command will also return deleted objects.
limit	uint16?	optional		When using , sets the maximum number of objects retrieved from the archive.
lowest	uint64?	optional		When using , sets the smallest valued id objects to retrieve.
trunk	boolean	optional	`true`	When true (default) the getter to retrieve the given Company's list of ProviderScripts as well as any publicly available ProviderScripts for the Company's parent(s).

Response description

Property	Type	Description
company	RespId	An object to contain the "id" of the Company to which the array of ProviderScripts belong.
company.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
providerScripts	Array.<ProviderScript>	The list of requested ProviderScripts.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"providerScripts": [
		{
			"blocks": [
				{
					"condition": string,
					"content": string,
					"replace": string,
					"validate": string
				}
			],
			"company": number,
			"fill": string,
			"global": boolean,
			"graphic": string,
			"id": number,
			"kind": string,
			"name": string,
			"notes": string,
			"parameters": {
				string: {
					"advanced": boolean,
					"context": string,
					"notes": string,
					"order": number,
					"type": string,
					"value": string
				}
			},
			"processedUtc": string,
			"stroke": string,
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
401	5	You do not have permission to view ProviderScripts for this Company.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company was not found by its unique identifier.

GET/providers?includeSuspended=boolean&includeDeleted=boolean&includeArchive=boolean&limit=number&first=string&last=string

This request is an alias of /companies/{your-company-id}/providers.

URL Parameters

Parameter	Type	Required	Default	Description
first	string	optional		When using , sets the first alphabetic Provider.id when listing from the database.
includeArchive	boolean	optional	`false`	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	`false`	False by default, but when true the command will also return deleted objects.
last	string	optional		When using , sets the last alphabetic Provider.id when listing from the database.
limit	uint16	optional		When using , sets the maximum number of objects in this response.
your-company-id	uint64	aliased	`{your-company-id}`	Your own Company's identifier.

PATCH/providers

Creates a new, or updates an existing Provider.

HTTP Request body description

Property	Type	Required	Description
provider	Object.<string, ?>	always	A simple object to contain the Provider parameters.
provider.asset	uint64?	optional	A reference to the Asset with which to provide events.
provider.config	uint64?	create	Identifier of the ProviderConfig/ProviderConfiguration this Provider will use.
provider.id	string maximum-length: 50 minimum-length: 10	always	Unique identifier of the Provider.
provider.kind	ProviderType?	create	The type of Provider.
provider.name	string maximum-length: 100	create	A name for the Provider.
provider.notes	string	optional	Notes for this Provider.
provider.password	string	optional	The password required to communicate and program this Provider.
provider.phone	uint64?	optional	The phone number this Provider uses (if known).
provider.pnd	string	optional	The name of the Personal Navigation Device connected to this Provider.
provider.v	Array.<int32>	optional
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"provider": {
		"asset": number,
		"config": number,
		"id": string,
		"kind": string,
		"name": string,
		"notes": string,
		"password": string,
		"phone": number,
		"pnd": string,
		"v": [
			number
		]
	},
	"reqId": number
}

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
provider	RespIdendifierCompany	An object which contains the "id" and "company" keys when there is no error.
provider.company	uint64	Identifier of the Company to which this object belongs.
provider.id	string	Identifier given as input for the command.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"provider": {
		"company": number,
		"id": string
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	A name was given, but the value is blank or white-space only.
400	3	During create: When creating a new Provider, a name was not given.
400	3	During create: When creating a new Provider, a company was not given.
400	3	During create: When creating a new Provider, a kind was not given.
400	3	During create: When creating a new Provider, a configuration was not given.
400	3	During update: When updating a Provider, the name was given as null or blank.
400	3	During update: When updating a Provider, the v was not an array, or contained too few numbers.
400	3	During update: Not enough data was given to perform a change.
400	3	The kind value was given, but it is not a valid member of the enum. Returns an ErrorDetailEnum as the `errorDetails`.
400	3	The id was an invalid length. See the errorDetails for length requirements. Returns an ErrorDetailMinMax as the `errorDetails`.
400	3	The phone value was given, but it is not an integer. Returns an ErrorDetailPhone as the `errorDetails`.
401	5	You do not have permission to create Providers in the given company.
401	5	You do not have permission to the Asset for which this Provider is currently providing events.
401	5	You do not have permission to the Asset specified for this Provider to provide events.
401	5	You do not have permission to change ProviderConfigs/ProviderConfigurations.
401	5	During update: The specified ProviderConfig/ProviderConfiguration belongs to a different Company and you do not have permission to delete the Provider from its current Company.
401	5	During update: The specified ProviderConfig/ProviderConfiguration belongs to a different Company and you do not have permission to create the Provider in the new Company.
400	6	During update: When updating a Provider, an incorrect v value was given as input.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	20	The specified Asset was not found.
404	43	The Provider you are trying to update was not found.
400	44	The command values are set to create a new Provider, but a Provider of the given id already exists.
404	47	The specified ProviderConfigurationType was not found. If you receive this error, please contact technical support.
404	48	The specified ProviderConfig/ProviderConfiguration was not found.
403	98	During update: When updating a Provider, the Provider is suspended. Before making changes to a Provider, it must be reactivated.
404	102	The specified ProviderScript was not found. If you receive this error, please contact technical support.
409	130	The specified ProviderConfig/ProviderConfiguration if for a different ProviderType.
409	130	The specified Asset belongs to a different Company.
409	130	The specified ProviderConfig/ProviderConfiguration belongs to a different Company and the Asset was not null (and not set to null or an asset from the new company).
409	130	During update: The Provider's provider.kind can not be changed after it is created.

DELETE/providers

Deletes the specified Provider from the system.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
provider	RespIdendifierDeleted	An object which contains the Provider's id, owning Company id, and deleted status.
provider.company	uint64	Identifier of the Company to which this object belongs.
provider.deleted	boolean	Flag showing if the object is deleted.
provider.id	string	Identifier given as input for the command.
provider.v	Array.<uint32>
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"provider": {
		"company": number,
		"deleted": boolean,
		"id": string,
		"v": [
			number
		]
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a provider object, or it is invalid.
400	3	The provider object does not contain an id, or it is invalid.
401	5	You do not have permission to delete this Provider.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	43	The Provider was not found by its unique identifier.

GET/providers/{providerId}?includeDeleted=boolean

Gets details of the specified Provider.

URL Parameters

Parameter	Type	Required	Description
includeDeleted	boolean	optional	False by default, but when true the command will also return deleted objects.
providerId	string	required	Unique identifier of the Provider.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
provider	Provider	The requested Provider.
provider.asset	uint64? see: Asset.id	The asset for which this device provides field data.
provider.attributes	Object.<string, Object.<string, ProviderData>> for keys see: ProviderDataGroup for value-keys see: ProviderDataName	Often changing values like latitude, longitude, speed, wiring state, VBus information, etc...
provider.commands	Object.<ProviderCommandType, ProviderCommand>	Collection of commands for this provider.
provider.company	uint64 see: Company.id	The company to which this device belongs.
provider.configuration	uint64 see: ProviderConfig.id see: ProviderConfiguration.id	The provider's current (or pending) configuration profile.
provider.control	ProviderControl	Managing and controlling communication with this provider.
provider.control.commands	Object.<ProviderCommandType, ProviderCommand>	Collection of commands for this provider.
provider.control.company	uint64 see: Company.id	The company to which this device belongs.
provider.control.id	string see: Provider.id maximum-length: 50 minimum-length: 10	Unique identifier of this device.
provider.control.processedUtc	datetime	When the was change procesed.
provider.control.updated		by: login, from: monster
provider.control.v	Array.<uint32>	Object version keys used to validate synchronization for all object properties.
provider.firmware	string maximum-length: 100	The firmware/application version number.
provider.firmwareStatus	ProvisioningStatus	The system's progress of updating the device's firmware/application.
provider.geofenceLast	datetime	A timestamp from when the geofence list was updated by a User or a Provider.
provider.geofenceStatus	ProvisioningStatus	The system's progress of updating the device's on-board geofence definitions.
provider.id	string maximum-length: 50 minimum-length: 10	Unique identifier of this provider.
provider.information	Object.<string, string> for keys see: ProviderDataName	A list of read-only values about the device like IMEI, ESN, firmware version, hardware revision, etc...
provider.kind	ProviderType	The kind of communication protocol this device uses.
provider.lastCheckIn	datetime	A timestamp from when the provider last checked for a new script or new geofences.
provider.lastIP	ipv4	The last IP address of the device.
provider.name	string maximum-length: 100	A nickname given to the device/hardware.
provider.notes	string	Notes!
provider.password	string maximum-length: 50	The password programmed on the device used to ensure the system is the only client authorized to make changes.
provider.phoneNumber	uint64?	The phone number of this device.
provider.pnd	string maximum-length: 50	The short-name of the kind of PND attached to this device. Leave blank if none.
provider.processedUtc	datetime	When the was change procesed.
provider.scriptLast	datetime	A timestamp from when the script status was updated by a User or a Provider.
provider.scriptStatus	ProvisioningStatus	The system's progress of updating the device's programming.
provider.sim	string	ICCID of the SIM card installed in this provider
provider.snf	Object.<string, string>	Store-and-forward information like last sequence number of SnF window
provider.updated		by: login, from: monster
provider.v	Array.<int32> fixed count: 3	Object version keys used to validate synchronization for all object properties.
provider.v[0]	int32	The first element is for the general properties
provider.v[1]	int32	The second element is for the advanced properties
provider.v[2]	int32	The third element is for the control properties
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"provider": {
		"asset": number,
		"attributes": {
			string: {
				string: {
					"dts": string,
					"unit": string,
					"value": Object
				}
			}
		},
		"commands": {
			string: {
				"created": string,
				"parameters": [
					string
				],
				"processed": string,
				"status": string
			}
		},
		"company": number,
		"configuration": number,
		"control": {
			"commands": {
				string: {
					"created": string,
					"parameters": [
						string
					],
					"processed": string,
					"status": string
				}
			},
			"company": number,
			"id": string,
			"processedUtc": string,
			"updated": {
			},
			"v": [
				number
			]
		},
		"firmware": string,
		"firmwareStatus": string,
		"geofenceLast": string,
		"geofenceStatus": string,
		"id": string,
		"information": {
			string: string
		},
		"kind": string,
		"lastCheckIn": string,
		"lastIP": string,
		"name": string,
		"notes": string,
		"password": string,
		"phoneNumber": number,
		"pnd": string,
		"processedUtc": string,
		"scriptLast": string,
		"scriptStatus": string,
		"sim": string,
		"snf": {
			string: string
		},
		"updated": {
		},
		"v": [
			number
		]
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a provider object, or it is invalid.
400	3	The provider object does not contain an id, or it is invalid.
401	5	You do not have permission to view this Provider.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	43	The Provider was not found by its unique identifier.

POST/providers/{providerId}

Creates a new, or updates an existing Provider.

URL Parameters

Parameter	Type	Required	Description
providerId	string	optional	Unique identifier of the Provider. This value is optional, and ignored by the command.

HTTP Request body description

Property	Type	Required	Description
provider	Object.<string, ?>	always	A simple object to contain the Provider parameters.
provider.asset	uint64?	optional	A reference to the Asset with which to provide events.
provider.config	uint64?	create	Identifier of the ProviderConfig/ProviderConfiguration this Provider will use.
provider.id	string maximum-length: 50 minimum-length: 10	always	Unique identifier of the Provider.
provider.kind	ProviderType?	create	The type of Provider.
provider.name	string maximum-length: 100	create	A name for the Provider.
provider.notes	string	optional	Notes for this Provider.
provider.password	string	optional	The password required to communicate and program this Provider.
provider.phone	uint64?	optional	The phone number this Provider uses (if known).
provider.pnd	string	optional	The name of the Personal Navigation Device connected to this Provider.
provider.v	Array.<int32>	optional
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"provider": {
		"asset": number,
		"config": number,
		"id": string,
		"kind": string,
		"name": string,
		"notes": string,
		"password": string,
		"phone": number,
		"pnd": string,
		"v": [
			number
		]
	},
	"reqId": number
}

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
provider	RespIdendifierCompany	An object which contains the "id" and "company" keys when there is no error.
provider.company	uint64	Identifier of the Company to which this object belongs.
provider.id	string	Identifier given as input for the command.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"provider": {
		"company": number,
		"id": string
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	A name was given, but the value is blank or white-space only.
400	3	During create: When creating a new Provider, a name was not given.
400	3	During create: When creating a new Provider, a company was not given.
400	3	During create: When creating a new Provider, a kind was not given.
400	3	During create: When creating a new Provider, a configuration was not given.
400	3	During update: When updating a Provider, the name was given as null or blank.
400	3	During update: When updating a Provider, the v was not an array, or contained too few numbers.
400	3	During update: Not enough data was given to perform a change.
400	3	The kind value was given, but it is not a valid member of the enum. Returns an ErrorDetailEnum as the `errorDetails`.
400	3	The id was an invalid length. See the errorDetails for length requirements. Returns an ErrorDetailMinMax as the `errorDetails`.
400	3	The phone value was given, but it is not an integer. Returns an ErrorDetailPhone as the `errorDetails`.
401	5	You do not have permission to create Providers in the given company.
401	5	You do not have permission to the Asset for which this Provider is currently providing events.
401	5	You do not have permission to the Asset specified for this Provider to provide events.
401	5	You do not have permission to change ProviderConfigs/ProviderConfigurations.
401	5	During update: The specified ProviderConfig/ProviderConfiguration belongs to a different Company and you do not have permission to delete the Provider from its current Company.
401	5	During update: The specified ProviderConfig/ProviderConfiguration belongs to a different Company and you do not have permission to create the Provider in the new Company.
400	6	During update: When updating a Provider, an incorrect v value was given as input.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	20	The specified Asset was not found.
404	43	The Provider you are trying to update was not found.
400	44	The command values are set to create a new Provider, but a Provider of the given id already exists.
404	47	The specified ProviderConfigurationType was not found. If you receive this error, please contact technical support.
404	48	The specified ProviderConfig/ProviderConfiguration was not found.
403	98	During update: When updating a Provider, the Provider is suspended. Before making changes to a Provider, it must be reactivated.
404	102	The specified ProviderScript was not found. If you receive this error, please contact technical support.
409	130	The specified ProviderConfig/ProviderConfiguration if for a different ProviderType.
409	130	The specified Asset belongs to a different Company.
409	130	The specified ProviderConfig/ProviderConfiguration belongs to a different Company and the Asset was not null (and not set to null or an asset from the new company).
409	130	During update: The Provider's provider.kind can not be changed after it is created.

DELETE/providers/{providerId}

Deletes the specified Provider from the system.

URL Parameters

Parameter	Type	Required	Description
providerId	string	required	Unique identifier of the Provider.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
provider	RespIdendifierDeleted	An object which contains the Provider's id, owning Company id, and deleted status.
provider.company	uint64	Identifier of the Company to which this object belongs.
provider.deleted	boolean	Flag showing if the object is deleted.
provider.id	string	Identifier given as input for the command.
provider.v	Array.<uint32>
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"provider": {
		"company": number,
		"deleted": boolean,
		"id": string,
		"v": [
			number
		]
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a provider object, or it is invalid.
400	3	The provider object does not contain an id, or it is invalid.
401	5	You do not have permission to delete this Provider.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	43	The Provider was not found by its unique identifier.

GET/providers/{providerId}/advanceds?includeDeleted=boolean

Gets details of the specified Provider.

URL Parameters

Parameter	Type	Required	Description
includeDeleted	boolean	optional	False by default, but when true the command will also return deleted objects.
providerId	string	required	Unique identifier of the Provider.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
providerAdvanced	ProviderAdvanced	The requested Provider.
providerAdvanced.attributes	Object.<string, Object.<string, ProviderData>> for keys see: ProviderDataGroup for value-keys see: ProviderDataName	Often changing values like latitude, longitude, speed, wiring state, VBus information, etc...
providerAdvanced.company	uint64 see: Company.id	The company to which this device belongs.
providerAdvanced.id	string see: Provider.id maximum-length: 50 minimum-length: 10	Unique identifier of this device.
providerAdvanced.lastIP	ipv4	The last IP address of the device.
providerAdvanced.processedUtc	datetime	When the was change procesed.
providerAdvanced.snf	Object.<string, string>	Store-and-forward information like last sequence number of SnF window
providerAdvanced.updated		by: login, from: monster
providerAdvanced.v	Array.<uint32>	Object version keys used to validate synchronization for all object properties.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"providerAdvanced": {
		"attributes": {
			string: {
				string: {
					"dts": string,
					"unit": string,
					"value": Object
				}
			}
		},
		"company": number,
		"id": string,
		"lastIP": string,
		"processedUtc": string,
		"snf": {
			string: string
		},
		"updated": {
		},
		"v": [
			number
		]
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a provider object, or it is invalid.
400	3	The provider object does not contain an id, or it is invalid.
401	5	You do not have permission to view this Provider.
401	5	You do not have permission to view this Provider's advanced details.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	43	The Provider was not found by its unique identifier.

GET/providers/{providerId}/generals?includeDeleted=boolean

Gets details of the specified Provider.

URL Parameters

Parameter	Type	Required	Description
includeDeleted	boolean	optional	False by default, but when true the command will also return deleted objects.
providerId	string	required	Unique identifier of the Provider.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
providerGeneral	ProviderGeneral	The requested Provider.
providerGeneral.asset	uint64? see: Asset.id	The asset for which this device provides field data.
providerGeneral.company	uint64 see: Company.id	The company to which this device belongs.
providerGeneral.configuration	uint64 see: ProviderConfig.id see: ProviderConfiguration.id	The provider's current (or pending) configuration profile.
providerGeneral.firmware	string maximum-length: 100	The firmware/application version number.
providerGeneral.firmwareStatus	ProvisioningStatus	The system's progress of updating the device's firmware/application.
providerGeneral.geofenceLast	datetime	A timestamp from when the geofence list was updated by a User or a Provider.
providerGeneral.geofenceStatus	ProvisioningStatus	The system's progress of updating the device's on-board geofence definitions.
providerGeneral.id	string see: Provider.id maximum-length: 50 minimum-length: 10	Unique identifier of this device.
providerGeneral.information	Object.<string, string> for keys see: ProviderDataName	A list of read-only values about the device like IMEI, ESN, firmware version, hardware revision, etc...
providerGeneral.kind	ProviderType	The kind of communication protocol this device uses.
providerGeneral.lastCheckIn	datetime	A timestamp from when the provider last checked for a new script or new geofences.
providerGeneral.name	string maximum-length: 100	A nickname given to the device/hardware.
providerGeneral.notes	string	Notes!
providerGeneral.password	string maximum-length: 50	The password programmed on the device used to ensure the system is the only client authorized to make changes.
providerGeneral.phoneNumber	uint64?	The phone number of this device.
providerGeneral.pnd	string maximum-length: 50	The short-name of the kind of PND attached to this device. Leave blank if none.
providerGeneral.processedUtc	datetime	When the was change procesed.
providerGeneral.scriptLast	datetime	A timestamp from when the script status was updated by a User or a Provider.
providerGeneral.scriptStatus	ProvisioningStatus	The system's progress of updating the device's programming.
providerGeneral.sim	string	ICCID of the SIM card installed in this provider
providerGeneral.updated		by: login, from: monster
providerGeneral.v	Array.<uint32>	Object version keys used to validate synchronization for all object properties.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"providerGeneral": {
		"asset": number,
		"company": number,
		"configuration": number,
		"firmware": string,
		"firmwareStatus": string,
		"geofenceLast": string,
		"geofenceStatus": string,
		"id": string,
		"information": {
			string: string
		},
		"kind": string,
		"lastCheckIn": string,
		"name": string,
		"notes": string,
		"password": string,
		"phoneNumber": number,
		"pnd": string,
		"processedUtc": string,
		"scriptLast": string,
		"scriptStatus": string,
		"sim": string,
		"updated": {
		},
		"v": [
			number
		]
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a provider object, or it is invalid.
400	3	The provider object does not contain an id, or it is invalid.
401	5	You do not have permission to view this Provider.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	43	The Provider was not found by its unique identifier.

PATCH/providers/{providerId}/restore

Restores a deleted Provider.

URL Parameters

Parameter	Type	Required	Description
providerId	string	required	Unique identifier of the Provider.

HTTP Request body description

Property	Type	Required	Description
provider	ParamIdentifier	always	An object to contain the "id" of the Provider.
provider.id	string	always	The Provider's identifier.
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"provider": {
		"id": string
	},
	"reqId": number
}

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
provider	RespIdendifierDeleted	An object which contains the Provider's id, owning Company id, and deleted status.
provider.company	uint64	Identifier of the Company to which this object belongs.
provider.deleted	boolean	Flag showing if the object is deleted.
provider.id	string	Identifier given as input for the command.
provider.v	Array.<uint32>
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"provider": {
		"company": number,
		"deleted": boolean,
		"id": string,
		"v": [
			number
		]
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a provider object, or it is invalid.
400	3	The provider object does not contain an id, or it is invalid.
401	5	You do not have permission to restore this Provider.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	43	The Provider was not found by its unique identifier.
400	44	The Provider was found, but is not marked as deleted.

GET/providers/advanceds?includeSuspended=boolean&includeDeleted=boolean&includeArchive=boolean&limit=number&first=string&last=string

This request is an alias of /companies/{your-company-id}/providers.

URL Parameters

Parameter	Type	Required	Default	Description
first	string	optional		When using , sets the first alphabetic Provider.id when listing from the database.
includeArchive	boolean	optional	`false`	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	`false`	False by default, but when true the command will also return deleted objects.
last	string	optional		When using , sets the last alphabetic Provider.id when listing from the database.
limit	uint16	optional		When using , sets the maximum number of objects in this response.
your-company-id	uint64	aliased	`{your-company-id}`	Your own Company's identifier.

GET/providers/advanceds?config={uint64}&includeSuspended=boolean&includeDeleted=boolean&includeArchive=boolean&limit=number&first=string&last=string

Gets the list of Providers for the specified Company.

URL Parameters

Parameter	Type	Required	Default	Description
config	uint64	required		Unique identifier of the ProviderConfig or ProviderConfiguration.
first	string	optional		When using , sets the first alphabetic Provider.id when listing from the database.
includeArchive	boolean	optional		Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional		False by default, but when true, the command will also return deleted objects.
includeSuspended	boolean	optional	`true`	When true (default), the command will also return Providers marked as Provider.suspended.
last	string	optional		When using , sets the last alphabetic Provider.id when listing from the database.
limit	uint16?	optional		When using , sets the maximum number of objects retrieved from the archive.

Response description

Property	Type	Description
company	RespId	An object to contain the "id" of the Company to which the array of Providers belong.
company.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
providerAdvanceds	Array.<ProviderAdvanced>	The list of requested Providers.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"providerAdvanceds": [
		{
			"attributes": {
				string: {
					string: {
						"dts": string,
						"unit": string,
						"value": Object
					}
				}
			},
			"company": number,
			"id": string,
			"lastIP": string,
			"processedUtc": string,
			"snf": {
				string: string
			},
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
401	5	You do not have permission to view Providers for this Company.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company was not found by its unique identifier.

GET/providers/configs?includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

This request is an alias of /companies/{your-company-id}/providers/configs/.

URL Parameters

Parameter	Type	Required	Default	Description
highest	uint64	optional		When using , sets the maximum id when listing from the database.
includeArchive	boolean	optional	`false`	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	`false`	False by default, but when true the command will also return deleted objects.
limit	uint16	optional		When using , sets the maximum number of objects in this response.
lowest	uint64	optional		When using , sets the minimum id when listing from the database.
your-company-id	uint64	aliased	`{your-company-id}`	Your own Company's identifier.

PATCH/providers/configs

Creates a new or updates an existing ProviderConfig.

HTTP Request body description

Property	Type	Required	Description
providerConfig	Object.<string, ?>	always	A simple object to contain the ProviderConfig parameters.
providerConfig.company	uint64?	create	The Company to which the ProviderConfig belongs.
providerConfig.geofences	expression	optional	A search pattern used to filter which Places' geometry are used as geofences. Use null or blank string to disable. Use "*" to match all the Places the Provider's Asset can match. Or use "#123456" or "label:term" like other Place search patterns.
providerConfig.id	uint64?	update	The unique identifier of the ProviderConfig you want to update.
providerConfig.name	string maximum-length: 100	create	Name for the ProviderConfig.
providerConfig.notes	string	optional	Notes for the ProviderConfig.
providerConfig.parameters	Object.<string, string>	optional	The values needed to implement the script. Each key in this object is the name of a required script variable.
providerConfig.script	uint64?	create	The ProviderScript to the ProviderConfig implements. After creation, this value is read-only.
providerConfig.v	Array.<int32>	optional
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"providerConfig": {
		"company": number,
		"geofences": string,
		"id": number,
		"name": string,
		"notes": string,
		"parameters": {
			string: string
		},
		"script": number,
		"v": [
			number
		]
	},
	"reqId": number
}

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
providerConfig	RespIdScript	An object which contains the "id", "company", and "script" keys when there is no error.
providerConfig.company	uint64	Identifier of the Company to which this object belongs.
providerConfig.id	uint64?	Identifier given as input for the command.
providerConfig.script	uint64	Identifier of the script to which this object belongs.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"providerConfig": {
		"company": number,
		"id": number,
		"script": number
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a providerConfig object, or it is invalid.
400	3	Not enough keys exist in the providerConfig object.
400	3	During create: When creating a new ProviderConfig, a name was not given, or it is invalid.
400	3	During create: When creating a new ProviderConfig, a company was not given.
400	3	During create: When creating a new ProviderConfig, a script was not given.
400	3	During update: When updating a ProviderConfig, the id was invalid.
400	3	During update: When updating a ProviderConfig, the name was given as blank.
400	3	During update: When updating a ProviderConfig, the v was not an array, or contained too few numbers.
400	3	One of the providerConfig.parameters was invalid. Returns an ErrorDetailBadKeys as the `errorDetails`.
400	3	One of the providerConfig.parameters keys was blank or white-space. Returns an ErrorDetailInput as the `errorDetails`.
401	5	You do not have permission to create a new ProviderConfig.
401	5	You do not have permission to update this ProviderConfig.
400	6	During update: When updating a ProviderConfig, an incorrect v value was given as input.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	48	During update: The ProviderConfig was not found by its unique identifier.
404	102	The ProviderScript was not found by its unique identifier.
404	102	The ProviderScript was found, but does not belong in the target company's tree.
409	130	There is one or more missing or invalid providerConfig.parameters required by the ProviderScript.
409	130	During update: When updating a ProviderConfig, the providerConfig.script can not be changed.
409	130	During update: When updating a ProviderConfig, the providerConfig.company can not be changed.

DELETE/providers/configs

Deletes a ProviderConfig.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
providerConfig	RespDeleted	An object which contains the ProviderConfig's id, owning Company id, and deleted status.
providerConfig.company	uint64	Identifier of the Company to which this object belongs.
providerConfig.deleted	boolean	Flag showing if the object is deleted.
providerConfig.id	uint64?	Identifier given as input for the command.
providerConfig.v	Array.<uint32>
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"providerConfig": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a providerConfig object, or it is invalid.
400	3	The providerConfig object does not contain an id, or it is invalid.
401	5	You do not have permission to delete this ProviderConfig.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	48	The ProviderConfig was not found by its unique identifier.

GET/providers/configs/{configId}?includeDeleted=boolean

Gets details of the specified Provider Config.

URL Parameters

Parameter	Type	Required	Description
configId	uint64	required	Unique identifier of the ProviderConfig.
includeDeleted	boolean	optional	False by default, but when true the command will also return deleted objects.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
providerConfig	ProviderConfig	The requested ProviderConfig.
providerConfig.company	uint64 see: Company.id	The company to which this configuration belongs.
providerConfig.geofences	expression	A search pattern used to filter which Places' geometry are used as geofences. Use null to disable. Use "*" to match all the Places the Provider's Asset can match. Or use "#123456" or "label:term" like other Place search patterns.
providerConfig.id	uint64	Unique identifier of this configuration.
providerConfig.name	string maximum-length: 100	The nickname given to this configuration
providerConfig.notes	string	Simple details about how the providers are expected to behave.
providerConfig.parameters	Object.<string, string>	The list of defined variable name/value pairs that the script requires.
providerConfig.processedUtc	datetime	When the was change procesed.
providerConfig.script	uint64 see: ProviderScript.id	The script which this configuration implements.
providerConfig.updated		by: login, from: monster
providerConfig.v	Array.<uint32>	Object version keys used to validate synchronization for all object properties.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"providerConfig": {
		"company": number,
		"geofences": string,
		"id": number,
		"name": string,
		"notes": string,
		"parameters": {
			string: string
		},
		"processedUtc": string,
		"script": number,
		"updated": {
		},
		"v": [
			number
		]
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a providerConfig object, or it is invalid.
400	3	The providerConfig object does not contain an id, or it is invalid.
401	5	You do not have permission to view this ProviderConfig.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	26	The ProviderConfig was not found by its unique identifier.

POST/providers/configs/{configId}

Creates a new or updates an existing ProviderConfig.

URL Parameters

Parameter	Type	Required	Description
configId	uint64?	optional	Unique identifier of the ProviderConfig. This value is optional, and ignored by the command.

HTTP Request body description

Property	Type	Required	Description
providerConfig	Object.<string, ?>	always	A simple object to contain the ProviderConfig parameters.
providerConfig.company	uint64?	create	The Company to which the ProviderConfig belongs.
providerConfig.geofences	expression	optional	A search pattern used to filter which Places' geometry are used as geofences. Use null or blank string to disable. Use "*" to match all the Places the Provider's Asset can match. Or use "#123456" or "label:term" like other Place search patterns.
providerConfig.id	uint64?	update	The unique identifier of the ProviderConfig you want to update.
providerConfig.name	string maximum-length: 100	create	Name for the ProviderConfig.
providerConfig.notes	string	optional	Notes for the ProviderConfig.
providerConfig.parameters	Object.<string, string>	optional	The values needed to implement the script. Each key in this object is the name of a required script variable.
providerConfig.script	uint64?	create	The ProviderScript to the ProviderConfig implements. After creation, this value is read-only.
providerConfig.v	Array.<int32>	optional
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"providerConfig": {
		"company": number,
		"geofences": string,
		"id": number,
		"name": string,
		"notes": string,
		"parameters": {
			string: string
		},
		"script": number,
		"v": [
			number
		]
	},
	"reqId": number
}

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
providerConfig	RespIdScript	An object which contains the "id", "company", and "script" keys when there is no error.
providerConfig.company	uint64	Identifier of the Company to which this object belongs.
providerConfig.id	uint64?	Identifier given as input for the command.
providerConfig.script	uint64	Identifier of the script to which this object belongs.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"providerConfig": {
		"company": number,
		"id": number,
		"script": number
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a providerConfig object, or it is invalid.
400	3	Not enough keys exist in the providerConfig object.
400	3	During create: When creating a new ProviderConfig, a name was not given, or it is invalid.
400	3	During create: When creating a new ProviderConfig, a company was not given.
400	3	During create: When creating a new ProviderConfig, a script was not given.
400	3	During update: When updating a ProviderConfig, the id was invalid.
400	3	During update: When updating a ProviderConfig, the name was given as blank.
400	3	During update: When updating a ProviderConfig, the v was not an array, or contained too few numbers.
400	3	One of the providerConfig.parameters was invalid. Returns an ErrorDetailBadKeys as the `errorDetails`.
400	3	One of the providerConfig.parameters keys was blank or white-space. Returns an ErrorDetailInput as the `errorDetails`.
401	5	You do not have permission to create a new ProviderConfig.
401	5	You do not have permission to update this ProviderConfig.
400	6	During update: When updating a ProviderConfig, an incorrect v value was given as input.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	48	During update: The ProviderConfig was not found by its unique identifier.
404	102	The ProviderScript was not found by its unique identifier.
404	102	The ProviderScript was found, but does not belong in the target company's tree.
409	130	There is one or more missing or invalid providerConfig.parameters required by the ProviderScript.
409	130	During update: When updating a ProviderConfig, the providerConfig.script can not be changed.
409	130	During update: When updating a ProviderConfig, the providerConfig.company can not be changed.

DELETE/providers/configs/{configId}

Deletes a ProviderConfig.

URL Parameters

Parameter	Type	Required	Description
configId	uint64	required	Unique identifier of the ProviderConfig.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
providerConfig	RespDeleted	An object which contains the ProviderConfig's id, owning Company id, and deleted status.
providerConfig.company	uint64	Identifier of the Company to which this object belongs.
providerConfig.deleted	boolean	Flag showing if the object is deleted.
providerConfig.id	uint64?	Identifier given as input for the command.
providerConfig.v	Array.<uint32>
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"providerConfig": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a providerConfig object, or it is invalid.
400	3	The providerConfig object does not contain an id, or it is invalid.
401	5	You do not have permission to delete this ProviderConfig.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	48	The ProviderConfig was not found by its unique identifier.

PATCH/providers/configs/{configId}/restore

Restores a deleted ProviderConfig.

URL Parameters

Parameter	Type	Required	Description
configId	uint64	required	Unique identifier of the ProviderConfig.

HTTP Request body description

Property	Type	Required	Description
providerConfig	ParamId	always	An object to contain the "id" key.
providerConfig.id	uint64	always	Identifier given as input for the command.
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"providerConfig": {
		"id": number
	},
	"reqId": number
}

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
providerConfig	RespDeleted	An object which contains the ProviderConfig's id, owning Company id, and deleted status.
providerConfig.company	uint64	Identifier of the Company to which this object belongs.
providerConfig.deleted	boolean	Flag showing if the object is deleted.
providerConfig.id	uint64?	Identifier given as input for the command.
providerConfig.v	Array.<uint32>
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"providerConfig": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a providerConfig object, or it is invalid.
400	3	The providerConfig object does not contain an id, or it is invalid.
401	5	You do not have permission to restore this ProviderConfig.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	48	The ProviderConfig was not found by its unique identifier.
400	49	The ProviderConfig was found, but is not marked as deleted.

GET/providers/configurations?includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

This request is an alias of /companies/{your-company-id}/providers/configurations/.

URL Parameters

Parameter	Type	Required	Default	Description
highest	uint64	optional		When using , sets the maximum id when listing from the database.
includeArchive	boolean	optional	`false`	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	`false`	False by default, but when true the command will also return deleted objects.
limit	uint16	optional		When using , sets the maximum number of objects in this response.
lowest	uint64	optional		When using , sets the minimum id when listing from the database.
your-company-id	uint64	aliased	`{your-company-id}`	Your own Company's identifier.

DELETE/providers/configurations

Deletes a ProviderConfiguration.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
providerConfiguration	RespDeleted	An object which contains the ProviderConfiguration's id, owning Company id, and deleted status.
providerConfiguration.company	uint64	Identifier of the Company to which this object belongs.
providerConfiguration.deleted	boolean	Flag showing if the object is deleted.
providerConfiguration.id	uint64?	Identifier given as input for the command.
providerConfiguration.v	Array.<uint32>
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"providerConfiguration": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a providerConfiguration object, or it is invalid.
400	3	The providerConfiguration object does not contain an id, or it is invalid.
401	5	You do not have permission to delete this ProviderConfiguration.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	48	The ProviderConfiguration was not found by its unique identifier.

GET/providers/configurations/{configurationId}?includeDeleted=boolean

Gets details of the specified ProviderConfiguration.

URL Parameters

Parameter	Type	Required	Description
configurationId	uint64	required	Unique identifier of the ProviderConfiguration.
includeDeleted	boolean	optional	False by default, but when true the command will also return deleted objects.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
providerConfiguration Deprecated	ProviderConfiguration	The requested ProviderConfiguration. Use ProviderConfig instead.
providerConfiguration.company	uint64 see: Company.id	The company to which this configuration belongs.
providerConfiguration.geofences	Array.<uint64>	List of Places loaded directly onto the provider.
providerConfiguration.id	uint64	Unique identifier of this configuration.
providerConfiguration.name	string maximum-length: 100	The nickname given to this configuration
providerConfiguration.notes	string	Simple details about how the providers are expected to behave.
providerConfiguration.processedUtc	datetime	When the was change procesed.
providerConfiguration.scriptParameters	Object.<string, Object>	The list of defined variables given to the logic type's options pairs for the logic type requires.
providerConfiguration.type	uint64 see: ProviderConfigurationType.id	The logic type which this configuration implements.
providerConfiguration.updated		by: login, from: monster
providerConfiguration.v	Array.<uint32>	Object version keys used to validate synchronization for all object properties.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"providerConfiguration": {
		"company": number,
		"geofences": [
			number
		],
		"id": number,
		"name": string,
		"notes": string,
		"processedUtc": string,
		"scriptParameters": {
			string: Object
		},
		"type": number,
		"updated": {
		},
		"v": [
			number
		]
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a providerConfiguration object, or it is invalid.
400	3	The providerConfiguration object does not contain an id, or it is invalid.
401	5	You do not have permission to view this ProviderConfiguration.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	26	The ProviderConfiguration was not found by its unique identifier.

POST/providers/configurations/{configurationId}

Creates a new or updates an existing ProviderConfiguration.

URL Parameters

Parameter	Type	Required	Description
configurationId	uint64?	optional	Unique identifier of the ProviderConfiguration. This value is optional, and ignored by the command.

HTTP Request body description

Property	Type	Required	Description
providerConfiguration	Object.<string, ?>	always	A simple object to contain the ProviderConfiguration parameters.
providerConfiguration.company	uint64?	create	The Company to which the ProviderConfiguration belongs.
providerConfiguration.geofences	Array.<uint64> for values see: Place.id	optional	A list of Places whose shape is programmed directly onto Providers to raise instant boundary events.
providerConfiguration.id	uint64?	update	The unique identifier of the ProviderConfiguration you want to update.
providerConfiguration.name	string maximum-length: 100	create	Name for the ProviderConfiguration.
providerConfiguration.notes	string	optional	Notes for the ProviderConfiguration.
providerConfiguration.scriptParameters	Object.<string, Object>	optional	The values needed to implement the ProviderConfigurationType. Each key in this object is the identifier of a required ProviderConfigurationNode. This command does not support patch semantics; all keys must be sent if any are sent.
providerConfiguration.type	uint64?	create	The ProviderConfigurationType that the ProviderConfiguration implements. After creation, this value is read-only.
providerConfiguration.v	Array.<int32>	optional
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"providerConfiguration": {
		"company": number,
		"geofences": [
			number
		],
		"id": number,
		"name": string,
		"notes": string,
		"scriptParameters": {
			string: Object
		},
		"type": number,
		"v": [
			number
		]
	},
	"reqId": number
}

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
providerConfiguration	RespIdScript	An object which contains the "id", "company", and "script" keys when there is no error.
providerConfiguration.company	uint64	Identifier of the Company to which this object belongs.
providerConfiguration.id	uint64?	Identifier given as input for the command.
providerConfiguration.script	uint64	Identifier of the script to which this object belongs.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"providerConfiguration": {
		"company": number,
		"id": number,
		"script": number
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a providerConfiguration object, or it is invalid.
400	3	Not enough keys exist in the providerConfiguration object.
400	3	During create: When creating a new ProviderConfiguration, a name was not given, or it is invalid.
400	3	During create: When creating a new ProviderConfiguration, a company was not given.
400	3	During create: When creating a new ProviderConfiguration, a type was not given.
400	3	During update: When updating a ProviderConfiguration, the id was invalid.
400	3	During update: When updating a ProviderConfiguration, the name was given as blank.
400	3	During update: When updating a ProviderConfiguration, the v was not an array, or contained too few numbers.
400	3	One of the providerConfiguration.scriptParameters was invalid. Returns an ErrorDetailBadKeys as the `errorDetails`.
400	3	There is one or more missing or invalid providerConfiguration.scriptParameters required by the ProviderConfigurationType. Returns an ErrorDetailBadKeys as the `errorDetails`.
400	3	One or more of the providerConfiguration.geofences Places were not a supported shape. Returns an ErrorDetailExternals as the `errorDetails`.
400	3	One of the providerConfiguration.scriptParameters keys was blank or white-space. Returns an ErrorDetailInput as the `errorDetails`.
400	3	One of the providerConfiguration.geofences values was not a valid number. Returns an ErrorDetailInput as the `errorDetails`.
401	5	You do not have permission to create a new ProviderConfiguration.
401	5	You do not have permission to update this ProviderConfiguration.
401	5	You do not have permission to one or more Places specified as a providerConfiguration.geofences value.
400	6	During update: When updating a ProviderConfiguration, an incorrect v value was given as input.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	42	One or more of the providerConfiguration.geofences Places were not found by its unique identifier.
404	47	During create: The ProviderConfigurationType was not found by its unique identifier.
404	48	During update: The ProviderConfiguration was not found by its unique identifier.
400	51	One or more of the providerConfiguration.scriptParameters or providerConfiguration.geofences values was invalid. Returns an ErrorDetailExternals as the `errorDetails`.
409	130	During update: When updating a ProviderConfiguration, the providerConfiguration.company can not be changed.
409	130	During update: When updating a ProviderConfiguration, the providerConfiguration.type can not be changed.

DELETE/providers/configurations/{configurationId}

Deletes a ProviderConfiguration.

URL Parameters

Parameter	Type	Required	Description
configurationId	uint64	required	Unique identifier of the ProviderConfiguration.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
providerConfiguration	RespDeleted	An object which contains the ProviderConfiguration's id, owning Company id, and deleted status.
providerConfiguration.company	uint64	Identifier of the Company to which this object belongs.
providerConfiguration.deleted	boolean	Flag showing if the object is deleted.
providerConfiguration.id	uint64?	Identifier given as input for the command.
providerConfiguration.v	Array.<uint32>
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"providerConfiguration": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a providerConfiguration object, or it is invalid.
400	3	The providerConfiguration object does not contain an id, or it is invalid.
401	5	You do not have permission to delete this ProviderConfiguration.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	48	The ProviderConfiguration was not found by its unique identifier.

PATCH/providers/configurations/{configurationId}/restore

Restores a deleted ProviderConfiguration.

URL Parameters

Parameter	Type	Required	Description
configurationId	uint64	required	Unique identifier of the ProviderConfiguration.

HTTP Request body description

Property	Type	Required	Description
providerConfiguration	ParamId	always	An object to contain the "id" key.
providerConfiguration.id	uint64	always	Identifier given as input for the command.
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"providerConfiguration": {
		"id": number
	},
	"reqId": number
}

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
providerConfiguration	RespDeleted	An object which contains the ProviderConfiguration's id, owning Company id, and deleted status.
providerConfiguration.company	uint64	Identifier of the Company to which this object belongs.
providerConfiguration.deleted	boolean	Flag showing if the object is deleted.
providerConfiguration.id	uint64?	Identifier given as input for the command.
providerConfiguration.v	Array.<uint32>
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"providerConfiguration": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a providerConfiguration object, or it is invalid.
400	3	The providerConfiguration object does not contain an id, or it is invalid.
401	5	You do not have permission to restore this ProviderConfiguration.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	48	The ProviderConfiguration was not found by its unique identifier.
400	49	The ProviderConfiguration was found, but is not marked as deleted.

GET/providers/configurations/types?includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

Lists all the ProviderConfigurationTypes in the system.

URL Parameters

Parameter	Type	Required	Description
highest	uint64?	optional	When using , sets the largest valued id objects to retrieve.
includeArchive	boolean	optional	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	False by default, but when true, the command will also return deleted objects.
limit	uint16?	optional	When using , sets the maximum number of objects retrieved from the archive.
lowest	uint64?	optional	When using , sets the smallest valued id objects to retrieve.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
providerConfigurationTypes	Array.<ProviderConfigurationType>	The list of requested ProviderConfigurationTypes.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"providerConfigurationTypes": [
		{
			"geofenceTypes": [
				string
			],
			"id": number,
			"maxGeofenceCount": number,
			"minGeofenceCount": number,
			"name": string,
			"notes": string,
			"processedUtc": string,
			"providerType": string,
			"scriptOptions": {
				string: {
					"id": string,
					"isAdvanced": boolean,
					"max": Object,
					"min": Object,
					"nodes": {
						string: { /* recursive ProviderConfigurationNode objects */ }
					},
					"notes": string,
					"type": string,
					"unit": string,
					"value": Object
				}
			},
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
401	5	You do not have permission to view ProviderConfigurationTypes.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.

GET/providers/configurations/types/{typeId}

Gets details of the specified ProviderConfigurationType.

URL Parameters

Parameter	Type	Required	Description
typeId	uint64	required	Unique identifier of the provider type

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
providerConfigurationType Deprecated	ProviderConfigurationType	The requested ProviderConfigurationTypes. Use ProviderScript instead.
providerConfigurationType.geofenceTypes	Array.<PlaceType>	A list of supported types of geofences which can be programmed directly onto the device.
providerConfigurationType.id	uint64	Unique identifier.
providerConfigurationType.maxGeofenceCount	uint32	The maximum number of geofences that can be programmed onto a device. This number changes based on device make and model, and can also change based on the supported geofence types.
providerConfigurationType.minGeofenceCount	uint32	The minimum number of geofences that need to be programmed onto the device. This value is almost always zero.
providerConfigurationType.name	string maximum-length: 100	Name of the configuration type.
providerConfigurationType.notes	string	Notes regarding the use of this configuration.
providerConfigurationType.processedUtc	datetime	When the was change procesed.
providerConfigurationType.providerType	ProviderType	The applicable type of provider for which this configuration type can be created.
providerConfigurationType.scriptOptions	Object.<string, ProviderConfigurationNode>	A tree-structure of configurations required (or optionally available) for programming a device.
providerConfigurationType.updated		by: login, from: monster
providerConfigurationType.v	Array.<uint32>	Object version keys used to validate synchronization for all object properties.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"providerConfigurationType": {
		"geofenceTypes": [
			string
		],
		"id": number,
		"maxGeofenceCount": number,
		"minGeofenceCount": number,
		"name": string,
		"notes": string,
		"processedUtc": string,
		"providerType": string,
		"scriptOptions": {
			string: {
				"id": string,
				"isAdvanced": boolean,
				"max": Object,
				"min": Object,
				"nodes": {
					string: { /* recursive ProviderConfigurationNode objects */ }
				},
				"notes": string,
				"type": string,
				"unit": string,
				"value": Object
			}
		},
		"updated": {
		},
		"v": [
			number
		]
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a providerConfigurationType object, or it is invalid.
400	3	The providerConfigurationType object does not contain an id, or it is invalid.
401	5	You do not have permission to view ProviderConfigurationTypes.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	47	The ProviderConfigurationType was not found by its unique identifier.

GET/providers/configurations/types?kind={string}&includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

Lists all the ProviderConfigurationTypes in the system by the given ProviderType.

URL Parameters

Parameter	Type	Required	Description
highest	uint64?	optional	When using , sets the largest valued id objects to retrieve.
includeArchive	boolean	optional	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	False by default, but when true, the command will also return deleted objects.
kind	ProviderType?	optional	Filters the list based on the given ProviderType.
limit	uint16?	optional	When using , sets the maximum number of objects retrieved from the archive.
lowest	uint64?	optional	When using , sets the smallest valued id objects to retrieve.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
providerConfigurationTypes	Array.<ProviderConfigurationType>	The list of requested ProviderConfigurationTypes.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"providerConfigurationTypes": [
		{
			"geofenceTypes": [
				string
			],
			"id": number,
			"maxGeofenceCount": number,
			"minGeofenceCount": number,
			"name": string,
			"notes": string,
			"processedUtc": string,
			"providerType": string,
			"scriptOptions": {
				string: {
					"id": string,
					"isAdvanced": boolean,
					"max": Object,
					"min": Object,
					"nodes": {
						string: { /* recursive ProviderConfigurationNode objects */ }
					},
					"notes": string,
					"type": string,
					"unit": string,
					"value": Object
				}
			},
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The kind is invalid no a valid ProviderType value.
401	5	You do not have permission to view ProviderConfigurationTypes.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.

GET/providers/generals?includeSuspended=boolean&includeDeleted=boolean&includeArchive=boolean&limit=number&first=string&last=string

This request is an alias of /companies/{your-company-id}/providers.

URL Parameters

Parameter	Type	Required	Default	Description
first	string	optional		When using , sets the first alphabetic Provider.id when listing from the database.
includeArchive	boolean	optional	`false`	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	`false`	False by default, but when true the command will also return deleted objects.
last	string	optional		When using , sets the last alphabetic Provider.id when listing from the database.
limit	uint16	optional		When using , sets the maximum number of objects in this response.
your-company-id	uint64	aliased	`{your-company-id}`	Your own Company's identifier.

GET/providers/generals?config={uint64}&includeSuspended=boolean&includeDeleted=boolean&includeArchive=boolean&limit=number&first=string&last=string

Gets the list of Providers for the specified Company.

URL Parameters

Parameter	Type	Required	Default	Description
config	uint64	required		Unique identifier of the ProviderConfig or ProviderConfiguration.
first	string	optional		When using , sets the first alphabetic Provider.id when listing from the database.
includeArchive	boolean	optional		Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional		False by default, but when true, the command will also return deleted objects.
includeSuspended	boolean	optional	`true`	When true (default), the command will also return Providers marked as Provider.suspended.
last	string	optional		When using , sets the last alphabetic Provider.id when listing from the database.
limit	uint16?	optional		When using , sets the maximum number of objects retrieved from the archive.

Response description

Property	Type	Description
company	RespId	An object to contain the "id" of the Company to which the array of Providers belong.
company.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
providerGenerals	Array.<ProviderGeneral>	The list of requested Providers.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"providerGenerals": [
		{
			"asset": number,
			"company": number,
			"configuration": number,
			"firmware": string,
			"firmwareStatus": string,
			"geofenceLast": string,
			"geofenceStatus": string,
			"id": string,
			"information": {
				string: string
			},
			"kind": string,
			"lastCheckIn": string,
			"name": string,
			"notes": string,
			"password": string,
			"phoneNumber": number,
			"pnd": string,
			"processedUtc": string,
			"scriptLast": string,
			"scriptStatus": string,
			"sim": string,
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
401	5	You do not have permission to view Providers for this Company.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company was not found by its unique identifier.

GET/providers/registrations?includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

This request is an alias of /companies/{your-company-id}/providers/registrations.

URL Parameters

Parameter	Type	Required	Default	Description
highest	uint64	optional		When using , sets the maximum id when listing from the database.
includeArchive	boolean	optional	`false`	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	`false`	False by default, but when true the command will also return deleted objects.
limit	uint16	optional		When using , sets the maximum number of objects in this response.
lowest	uint64	optional		When using , sets the minimum id when listing from the database.
your-company-id	uint64	aliased	`{your-company-id}`	Your own Company's identifier.

PATCH/providers/registrations

Creates a new ProviderRegistration for a provider pending configuration.

HTTP Request body description

Property	Type	Required	Description
providerRegistration	Object.<string, ?>	always	A simple object to contain the ProviderRegistration parameters.
providerRegistration.asset	uint64?	optional	An optional Asset to which the new Provider will be assigned.
providerRegistration.config	uint64	create	The identifier of the ProviderConfig/ProviderConfiguration that will be loaded onto the new Provider.
providerRegistration.identifier	string see: Provider.id maximum-length: 50	optional	Identifier of the Provider to setup. This is helpful for long-term deployments, but will be overwritten during provisioning.
providerRegistration.lifetime	timespan	optional	The lifetime of the ProviderRegistration. The default value (if not specified) is 10 minutes. It can be specified as up to 2 months to allow for longer deployments.
providerRegistration.name	string maximum-length: 100	optional	A nickname given to the Provider once it has been provisioned.
providerRegistration.notes	string	optional	Notes about the Provider for after it's been programmed.
providerRegistration.password	string maximum-length: 50	optional	The password programmed on the Provider used to ensure the system is the only client authorized to make changes.
providerRegistration.phone	uint64?	optional	If known beforehand, a phone number can be specified for new Providers.
providerRegistration.v	Array.<int32>	optional
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"providerRegistration": {
		"asset": number,
		"config": number,
		"identifier": string,
		"lifetime": string,
		"name": string,
		"notes": string,
		"password": string,
		"phone": number,
		"v": [
			number
		]
	},
	"reqId": number
}

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
providerRegistration	ProviderRegistration	The complete ProviderRegistration object.
providerRegistration.asset	uint64? see: Asset.id	The Asset for which this device will provide data.
providerRegistration.code	string fixed length: 6	A unique six digit code.
providerRegistration.company	uint64 see: Company.id	The company to which the device will belong.
providerRegistration.completed	datetime	Date/time stamp of when this registration ended successfully.
providerRegistration.config	uint64 see: ProviderConfig.id see: ProviderConfiguration.id	The predefined configuration this device will use.
providerRegistration.expires	datetime	The expiry date for this registration.
providerRegistration.identifier	string see: Provider.id maximum-length: 50	The unique identifier of the device that completed this registration.
providerRegistration.kind	ProviderType	The kind of protocol this device supports.
providerRegistration.name	string maximum-length: 100	A nickname given to the device once it has been provisioned.
providerRegistration.notes	string	Notes!
providerRegistration.password	string maximum-length: 50	The password programmed on the device used to ensure the system is the only client authorized to make changes.
providerRegistration.phoneNumber	uint64?	The phone number of the device being provisioned. This is set by the user for long-term registrations, or by the client during serial port setup.
providerRegistration.since	datetime	Date/time stamp of when this registration began.
providerRegistration.user	email see: User.login maximum-length: 254	The unique identifier the user who generated this registration.
registration Deprecated	ProviderRegistration	Use providerRegistration instead..
registration.asset	uint64? see: Asset.id	The Asset for which this device will provide data.
registration.code	string fixed length: 6	A unique six digit code.
registration.company	uint64 see: Company.id	The company to which the device will belong.
registration.completed	datetime	Date/time stamp of when this registration ended successfully.
registration.config	uint64 see: ProviderConfig.id see: ProviderConfiguration.id	The predefined configuration this device will use.
registration.expires	datetime	The expiry date for this registration.
registration.identifier	string see: Provider.id maximum-length: 50	The unique identifier of the device that completed this registration.
registration.kind	ProviderType	The kind of protocol this device supports.
registration.name	string maximum-length: 100	A nickname given to the device once it has been provisioned.
registration.notes	string	Notes!
registration.password	string maximum-length: 50	The password programmed on the device used to ensure the system is the only client authorized to make changes.
registration.phoneNumber	uint64?	The phone number of the device being provisioned. This is set by the user for long-term registrations, or by the client during serial port setup.
registration.since	datetime	Date/time stamp of when this registration began.
registration.user	email see: User.login maximum-length: 254	The unique identifier the user who generated this registration.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"providerRegistration": {
		"asset": number,
		"code": string,
		"company": number,
		"completed": string,
		"config": number,
		"expires": string,
		"identifier": string,
		"kind": string,
		"name": string,
		"notes": string,
		"password": string,
		"phoneNumber": number,
		"since": string,
		"user": string
	},
	"registration": {
		"asset": number,
		"code": string,
		"company": number,
		"completed": string,
		"config": number,
		"expires": string,
		"identifier": string,
		"kind": string,
		"name": string,
		"notes": string,
		"password": string,
		"phoneNumber": number,
		"since": string,
		"user": string
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	The service was not abe to generate a unique code. If you receive this error, please contact technical support.
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a providerRegistration object, or it is invalid.
400	3	The providerRegistration.config value is not an integer.
400	3	The providerRegistration.asset value was given, but it is not an integer.
400	3	The lifetime value was given and valid, but was too long of a time-span. Returns an ErrorDetailInput as the `errorDetails`.
400	3	The phone value was given, but it is not an integer. Returns an ErrorDetailPhone as the `errorDetails`.
401	5	You do not have access to the ProviderConfigs/ProviderConfigurations.
401	5	You do not have access to create new Provider.
401	5	You do not have access to the Asset being associated.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	20	The specified Asset was not found.
404	47	The specified ProviderConfiguration is invalid. If you receive this error, please contact technical support.
404	48	The specified ProviderConfig/ProviderConfiguration was not found.
404	102	The specified ProviderConfig is invalid. If you receive this error, please contact technical support.
409	130	The specified Asset was found, but was not in the same Company as the given ProviderConfig/ProviderConfiguration.

DELETE/providers/registrations

Gets details of the specified ProviderRegistration.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
providerRegistration	ProviderRegistration	The requested provider.
providerRegistration.asset	uint64? see: Asset.id	The Asset for which this device will provide data.
providerRegistration.code	string fixed length: 6	A unique six digit code.
providerRegistration.company	uint64 see: Company.id	The company to which the device will belong.
providerRegistration.completed	datetime	Date/time stamp of when this registration ended successfully.
providerRegistration.config	uint64 see: ProviderConfig.id see: ProviderConfiguration.id	The predefined configuration this device will use.
providerRegistration.expires	datetime	The expiry date for this registration.
providerRegistration.identifier	string see: Provider.id maximum-length: 50	The unique identifier of the device that completed this registration.
providerRegistration.kind	ProviderType	The kind of protocol this device supports.
providerRegistration.name	string maximum-length: 100	A nickname given to the device once it has been provisioned.
providerRegistration.notes	string	Notes!
providerRegistration.password	string maximum-length: 50	The password programmed on the device used to ensure the system is the only client authorized to make changes.
providerRegistration.phoneNumber	uint64?	The phone number of the device being provisioned. This is set by the user for long-term registrations, or by the client during serial port setup.
providerRegistration.since	datetime	Date/time stamp of when this registration began.
providerRegistration.user	email see: User.login maximum-length: 254	The unique identifier the user who generated this registration.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"providerRegistration": {
		"asset": number,
		"code": string,
		"company": number,
		"completed": string,
		"config": number,
		"expires": string,
		"identifier": string,
		"kind": string,
		"name": string,
		"notes": string,
		"password": string,
		"phoneNumber": number,
		"since": string,
		"user": string
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a providerRegistration object, or it is invalid.
400	3	The providerRegistration code is not an integer or is less than zero.
401	5	You do not have access to the ProviderConfig/ProviderConfigurations.
401	5	You do not have access to create new Providers.
401	5	You do not have access to the associated Asset.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
400	86	The code is valid, but the ProviderRegistration was not found, or has already been completed.

GET/providers/registrations/{keyCode}

Gets details of the specified ProviderRegistration.

URL Parameters

Parameter	Type	Required	Description
keyCode	string	required	Unique identifier of the ProviderRegistration.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
providerRegistration	ProviderRegistration	The requested provider.
providerRegistration.asset	uint64? see: Asset.id	The Asset for which this device will provide data.
providerRegistration.code	string fixed length: 6	A unique six digit code.
providerRegistration.company	uint64 see: Company.id	The company to which the device will belong.
providerRegistration.completed	datetime	Date/time stamp of when this registration ended successfully.
providerRegistration.config	uint64 see: ProviderConfig.id see: ProviderConfiguration.id	The predefined configuration this device will use.
providerRegistration.expires	datetime	The expiry date for this registration.
providerRegistration.identifier	string see: Provider.id maximum-length: 50	The unique identifier of the device that completed this registration.
providerRegistration.kind	ProviderType	The kind of protocol this device supports.
providerRegistration.name	string maximum-length: 100	A nickname given to the device once it has been provisioned.
providerRegistration.notes	string	Notes!
providerRegistration.password	string maximum-length: 50	The password programmed on the device used to ensure the system is the only client authorized to make changes.
providerRegistration.phoneNumber	uint64?	The phone number of the device being provisioned. This is set by the user for long-term registrations, or by the client during serial port setup.
providerRegistration.since	datetime	Date/time stamp of when this registration began.
providerRegistration.user	email see: User.login maximum-length: 254	The unique identifier the user who generated this registration.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"providerRegistration": {
		"asset": number,
		"code": string,
		"company": number,
		"completed": string,
		"config": number,
		"expires": string,
		"identifier": string,
		"kind": string,
		"name": string,
		"notes": string,
		"password": string,
		"phoneNumber": number,
		"since": string,
		"user": string
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a providerRegistration object, or it is invalid.
400	3	The providerRegistration code is not an integer or is less than zero.
401	5	You do not have access to the ProviderConfig/ProviderConfigurations.
401	5	You do not have access to view Providers.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
400	86	The code is valid, but the ProviderRegistration was not found.

POST/providers/registrations/{keyCode}

Creates a new ProviderRegistration for a provider pending configuration.

URL Parameters

Parameter	Type	Required	Description
keyCode	string	optional

HTTP Request body description

Property	Type	Required	Description
providerRegistration	Object.<string, ?>	always	A simple object to contain the ProviderRegistration parameters.
providerRegistration.asset	uint64?	optional	An optional Asset to which the new Provider will be assigned.
providerRegistration.config	uint64	create	The identifier of the ProviderConfig/ProviderConfiguration that will be loaded onto the new Provider.
providerRegistration.identifier	string see: Provider.id maximum-length: 50	optional	Identifier of the Provider to setup. This is helpful for long-term deployments, but will be overwritten during provisioning.
providerRegistration.lifetime	timespan	optional	The lifetime of the ProviderRegistration. The default value (if not specified) is 10 minutes. It can be specified as up to 2 months to allow for longer deployments.
providerRegistration.name	string maximum-length: 100	optional	A nickname given to the Provider once it has been provisioned.
providerRegistration.notes	string	optional	Notes about the Provider for after it's been programmed.
providerRegistration.password	string maximum-length: 50	optional	The password programmed on the Provider used to ensure the system is the only client authorized to make changes.
providerRegistration.phone	uint64?	optional	If known beforehand, a phone number can be specified for new Providers.
providerRegistration.v	Array.<int32>	optional
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"providerRegistration": {
		"asset": number,
		"config": number,
		"identifier": string,
		"lifetime": string,
		"name": string,
		"notes": string,
		"password": string,
		"phone": number,
		"v": [
			number
		]
	},
	"reqId": number
}

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
providerRegistration	ProviderRegistration	The complete ProviderRegistration object.
providerRegistration.asset	uint64? see: Asset.id	The Asset for which this device will provide data.
providerRegistration.code	string fixed length: 6	A unique six digit code.
providerRegistration.company	uint64 see: Company.id	The company to which the device will belong.
providerRegistration.completed	datetime	Date/time stamp of when this registration ended successfully.
providerRegistration.config	uint64 see: ProviderConfig.id see: ProviderConfiguration.id	The predefined configuration this device will use.
providerRegistration.expires	datetime	The expiry date for this registration.
providerRegistration.identifier	string see: Provider.id maximum-length: 50	The unique identifier of the device that completed this registration.
providerRegistration.kind	ProviderType	The kind of protocol this device supports.
providerRegistration.name	string maximum-length: 100	A nickname given to the device once it has been provisioned.
providerRegistration.notes	string	Notes!
providerRegistration.password	string maximum-length: 50	The password programmed on the device used to ensure the system is the only client authorized to make changes.
providerRegistration.phoneNumber	uint64?	The phone number of the device being provisioned. This is set by the user for long-term registrations, or by the client during serial port setup.
providerRegistration.since	datetime	Date/time stamp of when this registration began.
providerRegistration.user	email see: User.login maximum-length: 254	The unique identifier the user who generated this registration.
registration Deprecated	ProviderRegistration	Use providerRegistration instead..
registration.asset	uint64? see: Asset.id	The Asset for which this device will provide data.
registration.code	string fixed length: 6	A unique six digit code.
registration.company	uint64 see: Company.id	The company to which the device will belong.
registration.completed	datetime	Date/time stamp of when this registration ended successfully.
registration.config	uint64 see: ProviderConfig.id see: ProviderConfiguration.id	The predefined configuration this device will use.
registration.expires	datetime	The expiry date for this registration.
registration.identifier	string see: Provider.id maximum-length: 50	The unique identifier of the device that completed this registration.
registration.kind	ProviderType	The kind of protocol this device supports.
registration.name	string maximum-length: 100	A nickname given to the device once it has been provisioned.
registration.notes	string	Notes!
registration.password	string maximum-length: 50	The password programmed on the device used to ensure the system is the only client authorized to make changes.
registration.phoneNumber	uint64?	The phone number of the device being provisioned. This is set by the user for long-term registrations, or by the client during serial port setup.
registration.since	datetime	Date/time stamp of when this registration began.
registration.user	email see: User.login maximum-length: 254	The unique identifier the user who generated this registration.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"providerRegistration": {
		"asset": number,
		"code": string,
		"company": number,
		"completed": string,
		"config": number,
		"expires": string,
		"identifier": string,
		"kind": string,
		"name": string,
		"notes": string,
		"password": string,
		"phoneNumber": number,
		"since": string,
		"user": string
	},
	"registration": {
		"asset": number,
		"code": string,
		"company": number,
		"completed": string,
		"config": number,
		"expires": string,
		"identifier": string,
		"kind": string,
		"name": string,
		"notes": string,
		"password": string,
		"phoneNumber": number,
		"since": string,
		"user": string
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	The service was not abe to generate a unique code. If you receive this error, please contact technical support.
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a providerRegistration object, or it is invalid.
400	3	The providerRegistration.config value is not an integer.
400	3	The providerRegistration.asset value was given, but it is not an integer.
400	3	The lifetime value was given and valid, but was too long of a time-span. Returns an ErrorDetailInput as the `errorDetails`.
400	3	The phone value was given, but it is not an integer. Returns an ErrorDetailPhone as the `errorDetails`.
401	5	You do not have access to the ProviderConfigs/ProviderConfigurations.
401	5	You do not have access to create new Provider.
401	5	You do not have access to the Asset being associated.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	20	The specified Asset was not found.
404	47	The specified ProviderConfiguration is invalid. If you receive this error, please contact technical support.
404	48	The specified ProviderConfig/ProviderConfiguration was not found.
404	102	The specified ProviderConfig is invalid. If you receive this error, please contact technical support.
409	130	The specified Asset was found, but was not in the same Company as the given ProviderConfig/ProviderConfiguration.

DELETE/providers/registrations/{keyCode}

Gets details of the specified ProviderRegistration.

URL Parameters

Parameter	Type	Required	Description
keyCode	string	required	Unique identifier of the ProviderRegistration.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
providerRegistration	ProviderRegistration	The requested provider.
providerRegistration.asset	uint64? see: Asset.id	The Asset for which this device will provide data.
providerRegistration.code	string fixed length: 6	A unique six digit code.
providerRegistration.company	uint64 see: Company.id	The company to which the device will belong.
providerRegistration.completed	datetime	Date/time stamp of when this registration ended successfully.
providerRegistration.config	uint64 see: ProviderConfig.id see: ProviderConfiguration.id	The predefined configuration this device will use.
providerRegistration.expires	datetime	The expiry date for this registration.
providerRegistration.identifier	string see: Provider.id maximum-length: 50	The unique identifier of the device that completed this registration.
providerRegistration.kind	ProviderType	The kind of protocol this device supports.
providerRegistration.name	string maximum-length: 100	A nickname given to the device once it has been provisioned.
providerRegistration.notes	string	Notes!
providerRegistration.password	string maximum-length: 50	The password programmed on the device used to ensure the system is the only client authorized to make changes.
providerRegistration.phoneNumber	uint64?	The phone number of the device being provisioned. This is set by the user for long-term registrations, or by the client during serial port setup.
providerRegistration.since	datetime	Date/time stamp of when this registration began.
providerRegistration.user	email see: User.login maximum-length: 254	The unique identifier the user who generated this registration.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"providerRegistration": {
		"asset": number,
		"code": string,
		"company": number,
		"completed": string,
		"config": number,
		"expires": string,
		"identifier": string,
		"kind": string,
		"name": string,
		"notes": string,
		"password": string,
		"phoneNumber": number,
		"since": string,
		"user": string
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a providerRegistration object, or it is invalid.
400	3	The providerRegistration code is not an integer or is less than zero.
401	5	You do not have access to the ProviderConfig/ProviderConfigurations.
401	5	You do not have access to create new Providers.
401	5	You do not have access to the associated Asset.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
400	86	The code is valid, but the ProviderRegistration was not found, or has already been completed.

GET/providers/registrations?configId={uint64}&includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

Gets the list of ProviderRegistrations for the specified Company.

URL Parameters

Parameter	Type	Required	Description
configId	uint64	required	Unique identifier of the ProviderConfig or ProviderConfiguration.
highest	uint64?	optional	When using , sets the largest valued id objects to retrieve.
includeArchive	boolean	optional	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	False by default, but when true, the command will also return deleted objects.
limit	uint16?	optional	When using , sets the maximum number of objects retrieved from the archive.
lowest	uint64?	optional	When using , sets the smallest valued id objects to retrieve.

Response description

Property	Type	Description
company	RespId	An object to contain the "id" of the Company to which the array of providers belong.
company.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
providerRegistrations	Array.<ProviderRegistration>	The list of ProviderRegistrations.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"providerRegistrations": [
		{
			"asset": number,
			"code": string,
			"company": number,
			"completed": string,
			"config": number,
			"expires": string,
			"identifier": string,
			"kind": string,
			"name": string,
			"notes": string,
			"password": string,
			"phoneNumber": number,
			"since": string,
			"user": string
		}
	],
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a company object, or it is invalid.
400	3	The company id is not an integer or is less than zero.
401	5	You do not have access to the ProviderConfigs/ProviderConfigurations.
401	5	You do not have access to view Providers.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company value is valid, but could not be found.

GET/providers/scripts?trunk=boolean&includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

This request is an alias of /companies/{your-company-id}/providers/scripts/.

URL Parameters

Parameter	Type	Required	Default	Description
highest	uint64	optional		When using , sets the maximum id when listing from the database.
includeArchive	boolean	optional	`false`	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	`false`	False by default, but when true the command will also return deleted objects.
limit	uint16	optional		When using , sets the maximum number of objects in this response.
lowest	uint64	optional		When using , sets the minimum id when listing from the database.
trunk	boolean	optional	`true`	Defaults to true for this alias.
your-company-id	uint64	aliased	`{your-company-id}`	Your own Company's identifier.

PATCH/providers/scripts

Creates a new or updates an existing ProviderScript.

HTTP Request body description

Property	Type	Required	Description
providerScript	Object.<string, ?>	always	A simple object to contain the ProviderScript parameters.
providerScript.blocks	Array.<ProviderScriptBlock> minimum-count of values: 1	create	Blocks of file data which are (optionally) included in the ProviderScript data file.
providerScript.company	uint64?	create	The Company to which this ProviderScript belongs. After creation, this value is read-only.
providerScript.fill	string	optional	Background and fill colour in the UI.
providerScript.global	boolean	optional	Indicates whether this ProviderScript is available to child companies.
providerScript.graphic	string	optional	The name of the symbol shown in the UI.
providerScript.id	uint64?	update	The unique identifier of the ProviderScript you want to update.
providerScript.kind	ProviderType?	create	The type of provider for which this ProviderScript can be used. Limiting to a specific model from a manufacturer is accomplished through the block conditions.
providerScript.name	string maximum-length: 100	optional	Name for the ProviderScript.
providerScript.notes	string	optional	Notes for the ProviderScript.
providerScript.parameters	Object.<string, ProviderScriptParameter>	optional	Parameter definitions for this ProviderScript, including type-hints and default values.
providerScript.stroke	string	optional	Text and outline colour in the UI.
providerScript.v	Array.<int32>	optional
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"providerScript": {
		"blocks": [
			{
				"condition": string,
				"content": string,
				"replace": string,
				"validate": string
			}
		],
		"company": number,
		"fill": string,
		"global": boolean,
		"graphic": string,
		"id": number,
		"kind": string,
		"name": string,
		"notes": string,
		"parameters": {
			string: {
				"advanced": boolean,
				"context": string,
				"notes": string,
				"order": number,
				"type": string,
				"value": string
			}
		},
		"stroke": string,
		"v": [
			number
		]
	},
	"reqId": number
}

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
providerScript	RespIdCompany	An object which contains the "id" and "company" keys when there is no error.
providerScript.company	uint64	Identifier of the Company to which this object belongs.
providerScript.id	uint64?	Identifier given as input for the command.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"providerScript": {
		"company": number,
		"id": number
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a providerScript object, or it is invalid.
400	3	Not enough keys exist in the providerScript object.
400	3	The given kind was not valid ProviderType.
400	3	During create: When creating a new ProviderScript, a name was not given, or it is invalid.
400	3	During create: When creating a new ProviderScript, a company was not given.
400	3	During create: When creating a new ProviderScript, a kind was not given, or it is invalid.
400	3	During create: When creating a new ProviderScript, at least one block must be given.
400	3	During update: When updating a ProviderScript, the id was invalid.
400	3	During update: When updating a ProviderScript, the name was given as blank.
400	3	During update: When updating a ProviderScript, the v was not an array, or contained too few numbers.
400	3	One of the providerScript.blocks was invalid. Returns an ErrorDetailInput as the `errorDetails`.
400	3	One of the providerScript.blocks `replace` value was not a valid regular expression. Returns an ErrorDetailInput as the `errorDetails`.
400	3	One of the providerScript.parameters was invalid. Returns an ErrorDetailInput as the `errorDetails`.
400	3	One of the providerScript.parameters keys was blank or white-space. Returns an ErrorDetailInput as the `errorDetails`.
401	5	You do not have permission to create a new ProviderScript.
401	5	You do not have permission to update this ProviderScript.
400	6	During update: When updating a ProviderScript, an incorrect v value was given as input.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	102	During update: The ProviderScript was not found by its unique identifier.
409	104	During update: When updating a ProviderScript which is marked as global, but is being set as private, but is implemented by ProviderConfigs from child companies. Returns an ErrorDetailCount as the `errorDetails`.
409	130	During update: When updating a ProviderScript, the providerScript.company can not be changed.
409	130	During update: When updating a ProviderScript, the providerScript.kind can not be changed.
409	130	There is one or more missing parameters identified as variables in the providerScript.blocks. Returns an ErrorDetailBadKeys as the `errorDetails`.

DELETE/providers/scripts

Deletes an existing ProviderScript.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
providerScript	RespDeleted	An object which contains the ProviderScript's id, owning company id, and deleted status.
providerScript.company	uint64	Identifier of the Company to which this object belongs.
providerScript.deleted	boolean	Flag showing if the object is deleted.
providerScript.id	uint64?	Identifier given as input for the command.
providerScript.v	Array.<uint32>
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"providerScript": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a providerScript object, or it is invalid.
400	3	The providerScript object does not contain an id, or it is invalid.
401	5	You do not have permission to delete this ProviderScript.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	102	The ProviderScript was not found by its unique identifier.
409	104	This ProviderScript is still being used by one of more ProviderConfigs. Returns an ErrorDetailCount as the `errorDetails`.

GET/providers/scripts/{scriptId}?includeDeleted=boolean

Gets details of the specified ProviderScript.

URL Parameters

Parameter	Type	Required	Description
includeDeleted	boolean	optional	False by default, but when true the command will also return deleted objects.
scriptId	uint64	required	Unique identifier of the ProviderScript.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
providerScript	ProviderScript	The requested ProviderScript.
providerScript.blocks	Array.<ProviderScriptBlock>	Blocks of file data which are (optionally) included in the script data file.
providerScript.company	uint64 see: Company.id	The company to which this configuration belongs.
providerScript.fill	colour maximum-length: 22	The fill/background colour of the icon.
providerScript.global	boolean	Indicates whether this script is available to child companies.
providerScript.graphic	codified maximum-length: 22	The name of the symbol for this script.
providerScript.id	uint64	Unique identifier of this configuration.
providerScript.kind	ProviderType	The type of provider for which this script can be used. Limiting to a specific model from a manufacturer is accomplished through the block conditions.
providerScript.name	string maximum-length: 100	The nickname given to this configuration
providerScript.notes	string	Simple details about how the providers are expected to behave.
providerScript.parameters	Object.<string, ProviderScriptParameter>	Parameter definitions for this script, including type-hints and default values.
providerScript.processedUtc	datetime	When the was change procesed.
providerScript.stroke	colour maximum-length: 22	Outline and graphic colour.
providerScript.updated		by: login, from: monster
providerScript.v	Array.<uint32>	Object version keys used to validate synchronization for all object properties.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"providerScript": {
		"blocks": [
			{
				"condition": string,
				"content": string,
				"replace": string,
				"validate": string
			}
		],
		"company": number,
		"fill": string,
		"global": boolean,
		"graphic": string,
		"id": number,
		"kind": string,
		"name": string,
		"notes": string,
		"parameters": {
			string: {
				"advanced": boolean,
				"context": string,
				"notes": string,
				"order": number,
				"type": string,
				"value": string
			}
		},
		"processedUtc": string,
		"stroke": string,
		"updated": {
		},
		"v": [
			number
		]
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a providerScript object, or it is invalid.
400	3	The providerScript object does not contain an id, or it is invalid.
401	5	You do not have permission to view this ProviderScript.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	102	The ProviderScript was not found by its unique identifier.

POST/providers/scripts/{scriptId}

Creates a new or updates an existing ProviderScript.

URL Parameters

Parameter	Type	Required	Description
scriptId	uint64?	optional	Unique identifier of the ProviderScript. This value is optional, and ignored by the command.

HTTP Request body description

Property	Type	Required	Description
providerScript	Object.<string, ?>	always	A simple object to contain the ProviderScript parameters.
providerScript.blocks	Array.<ProviderScriptBlock> minimum-count of values: 1	create	Blocks of file data which are (optionally) included in the ProviderScript data file.
providerScript.company	uint64?	create	The Company to which this ProviderScript belongs. After creation, this value is read-only.
providerScript.fill	string	optional	Background and fill colour in the UI.
providerScript.global	boolean	optional	Indicates whether this ProviderScript is available to child companies.
providerScript.graphic	string	optional	The name of the symbol shown in the UI.
providerScript.id	uint64?	update	The unique identifier of the ProviderScript you want to update.
providerScript.kind	ProviderType?	create	The type of provider for which this ProviderScript can be used. Limiting to a specific model from a manufacturer is accomplished through the block conditions.
providerScript.name	string maximum-length: 100	optional	Name for the ProviderScript.
providerScript.notes	string	optional	Notes for the ProviderScript.
providerScript.parameters	Object.<string, ProviderScriptParameter>	optional	Parameter definitions for this ProviderScript, including type-hints and default values.
providerScript.stroke	string	optional	Text and outline colour in the UI.
providerScript.v	Array.<int32>	optional
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"providerScript": {
		"blocks": [
			{
				"condition": string,
				"content": string,
				"replace": string,
				"validate": string
			}
		],
		"company": number,
		"fill": string,
		"global": boolean,
		"graphic": string,
		"id": number,
		"kind": string,
		"name": string,
		"notes": string,
		"parameters": {
			string: {
				"advanced": boolean,
				"context": string,
				"notes": string,
				"order": number,
				"type": string,
				"value": string
			}
		},
		"stroke": string,
		"v": [
			number
		]
	},
	"reqId": number
}

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
providerScript	RespIdCompany	An object which contains the "id" and "company" keys when there is no error.
providerScript.company	uint64	Identifier of the Company to which this object belongs.
providerScript.id	uint64?	Identifier given as input for the command.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"providerScript": {
		"company": number,
		"id": number
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a providerScript object, or it is invalid.
400	3	Not enough keys exist in the providerScript object.
400	3	The given kind was not valid ProviderType.
400	3	During create: When creating a new ProviderScript, a name was not given, or it is invalid.
400	3	During create: When creating a new ProviderScript, a company was not given.
400	3	During create: When creating a new ProviderScript, a kind was not given, or it is invalid.
400	3	During create: When creating a new ProviderScript, at least one block must be given.
400	3	During update: When updating a ProviderScript, the id was invalid.
400	3	During update: When updating a ProviderScript, the name was given as blank.
400	3	During update: When updating a ProviderScript, the v was not an array, or contained too few numbers.
400	3	One of the providerScript.blocks was invalid. Returns an ErrorDetailInput as the `errorDetails`.
400	3	One of the providerScript.blocks `replace` value was not a valid regular expression. Returns an ErrorDetailInput as the `errorDetails`.
400	3	One of the providerScript.parameters was invalid. Returns an ErrorDetailInput as the `errorDetails`.
400	3	One of the providerScript.parameters keys was blank or white-space. Returns an ErrorDetailInput as the `errorDetails`.
401	5	You do not have permission to create a new ProviderScript.
401	5	You do not have permission to update this ProviderScript.
400	6	During update: When updating a ProviderScript, an incorrect v value was given as input.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	102	During update: The ProviderScript was not found by its unique identifier.
409	104	During update: When updating a ProviderScript which is marked as global, but is being set as private, but is implemented by ProviderConfigs from child companies. Returns an ErrorDetailCount as the `errorDetails`.
409	130	During update: When updating a ProviderScript, the providerScript.company can not be changed.
409	130	During update: When updating a ProviderScript, the providerScript.kind can not be changed.
409	130	There is one or more missing parameters identified as variables in the providerScript.blocks. Returns an ErrorDetailBadKeys as the `errorDetails`.

DELETE/providers/scripts/{scriptId}

Deletes an existing ProviderScript.

URL Parameters

Parameter	Type	Required	Description
scriptId	uint64	required	Unique identifier of the ProviderScript.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
providerScript	RespDeleted	An object which contains the ProviderScript's id, owning company id, and deleted status.
providerScript.company	uint64	Identifier of the Company to which this object belongs.
providerScript.deleted	boolean	Flag showing if the object is deleted.
providerScript.id	uint64?	Identifier given as input for the command.
providerScript.v	Array.<uint32>
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"providerScript": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a providerScript object, or it is invalid.
400	3	The providerScript object does not contain an id, or it is invalid.
401	5	You do not have permission to delete this ProviderScript.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	102	The ProviderScript was not found by its unique identifier.
409	104	This ProviderScript is still being used by one of more ProviderConfigs. Returns an ErrorDetailCount as the `errorDetails`.

PATCH/providers/scripts/{scriptId}/restore

Restores the specified ProviderScript.

URL Parameters

Parameter	Type	Required	Description
scriptId	uint64	required	Unique identifier of the ProviderScript.

HTTP Request body description

Property	Type	Required	Description
providerScript	ParamId	always	An object to contain the "id" of the ProviderScript.
providerScript.id	uint64	always	Identifier given as input for the command.
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"providerScript": {
		"id": number
	},
	"reqId": number
}

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
providerScript	RespDeleted	An object which contains the ProviderScript's id, owning company id, and deleted status.
providerScript.company	uint64	Identifier of the Company to which this object belongs.
providerScript.deleted	boolean	Flag showing if the object is deleted.
providerScript.id	uint64?	Identifier given as input for the command.
providerScript.v	Array.<uint32>
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"providerScript": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a providerScript object, or it is invalid.
400	3	The providerScript object does not contain an id, or it is invalid.
401	5	You do not have permission to restore this ProviderScript.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	102	The ProviderScript was not found by its unique identifier.
400	103	The ProviderScript was found, but is not marked as deleted.

GET/providers?config={uint64}&includeSuspended=boolean&includeDeleted=boolean&includeArchive=boolean&limit=number&first=string&last=string

Gets the list of Providers for the specified Company.

URL Parameters

Parameter	Type	Required	Default	Description
config	uint64	required		Unique identifier of the ProviderConfig or ProviderConfiguration.
first	string	optional		When using , sets the first alphabetic Provider.id when listing from the database.
includeArchive	boolean	optional		Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional		False by default, but when true, the command will also return deleted objects.
includeSuspended	boolean	optional	`true`	When true (default), the command will also return Providers marked as Provider.suspended.
last	string	optional		When using , sets the last alphabetic Provider.id when listing from the database.
limit	uint16?	optional		When using , sets the maximum number of objects retrieved from the archive.

Response description

Property	Type	Description
company	RespId	An object to contain the "id" of the Company to which the array of Providers belong.
company.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
providers	Array.<Provider>	The list of requested Providers.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"providers": [
		{
			"asset": number,
			"attributes": {
				string: {
					string: {
						"dts": string,
						"unit": string,
						"value": Object
					}
				}
			},
			"commands": {
				string: {
					"created": string,
					"parameters": [
						string
					],
					"processed": string,
					"status": string
				}
			},
			"company": number,
			"configuration": number,
			"control": {
				"commands": {
					string: {
						"created": string,
						"parameters": [
							string
						],
						"processed": string,
						"status": string
					}
				},
				"company": number,
				"id": string,
				"processedUtc": string,
				"updated": {
				},
				"v": [
					number
				]
			},
			"firmware": string,
			"firmwareStatus": string,
			"geofenceLast": string,
			"geofenceStatus": string,
			"id": string,
			"information": {
				string: string
			},
			"kind": string,
			"lastCheckIn": string,
			"lastIP": string,
			"name": string,
			"notes": string,
			"password": string,
			"phoneNumber": number,
			"pnd": string,
			"processedUtc": string,
			"scriptLast": string,
			"scriptStatus": string,
			"sim": string,
			"snf": {
				string: string
			},
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
401	5	You do not have permission to view Providers for this Company.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company was not found by its unique identifier.

Reports

GET/companies/{companyId}/reports/results?includeDeleted=boolean&includeArchive=boolean&limit=number&after=string&before=string

Gets the list of ReportResult for the specified Company.

URL Parameters

Parameter	Type	Required	Description
after	datetime	optional	When using , sets the earliest objects (by dts) to retrieve from the archive.
before	datetime	optional	When using , sets the most recent objects (by dts) to retrieve from the archive.
companyId	uint64	required	Unique identifier of the Company.
includeArchive	boolean	optional	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	False by default, but when true the command will also return deleted objects.
limit	uint16?	optional	When using , sets the maximum number of objects retrieved from the archive.

Response description

Property	Type	Description
company	RespId	An object to contain the "id" of the Company to which the array of ReportResults belong.
company.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reportResults	Array.<ReportResult>	The list of requested ReportResults.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reportResults": [
		{
			"archive": boolean,
			"bounds": {
				"east": number,
				"north": number,
				"south": number,
				"west": number
			},
			"company": number,
			"completed": string,
			"created": string,
			"error": string,
			"filtered": [
				number
			],
			"id": number,
			"name": string,
			"notes": string,
			"options": {
				"filtering": string,
				"parameters": [
					{
						"type": string,
						"value": string
					}
				],
				"places": string,
				"regions": [
					string
				],
				"scorecardRules": {
					"baseScore": number,
					"parameters": [
						{
							"condition": string,
							"duration": string,
							"points": number
						}
					]
				},
				"targets": string
			},
			"processedUtc": string,
			"progress": number,
			"runBy": string,
			"schedule": number,
			"scorecards": [
				{
					"asset": number,
					"rulePoints": {
						string: number
					},
					"score": number
				}
			],
			"status": string,
			"targeted": [
				number
			],
			"template": number,
			"timezone": string,
			"totals": [
				{
					"asset": number,
					"distance": number,
					"duration": string,
					"stateDetail": string,
					"summaryCount": number,
					"value": number,
					"valueType": string
				}
			],
			"type": string,
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
401	5	You do not have permission to view ReportResult.
401	5	You do not have permission to any of the Assets in the Company.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company whose ReportResults you are trying to list was not found.

GET/companies/{companyId}/reports/schedules?includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

Gets the list of ReportSchedules for the specified Company.

URL Parameters

Parameter	Type	Required	Description
companyId	uint64	required	Unique identifier of the Company.
highest	uint64?	optional	When using , sets the largest valued id objects to retrieve.
includeArchive	boolean	optional	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	False by default, but when true, the command will also return deleted objects.
limit	uint16?	optional	When using , sets the maximum number of objects retrieved from the archive.
lowest	uint64?	optional	When using , sets the smallest valued id objects to retrieve.

Response description

Property	Type	Description
company	RespId	An object which contains only one key "id" when there is no error. The "id" key is the unique identifier of the company to which the array of objects relate.
company.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reportSchedules	Array.<ReportSchedule>	The list of schedules.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reportSchedules": [
		{
			"company": number,
			"enabled": boolean,
			"id": number,
			"name": string,
			"notes": string,
			"notify": {
				"assets": string,
				"users": [
					string
				]
			},
			"options": {
				"filtering": string,
				"parameters": [
					{
						"type": string,
						"value": string
					}
				],
				"places": string,
				"regions": [
					string
				],
				"scorecardRules": {
					"baseScore": number,
					"parameters": [
						{
							"condition": string,
							"duration": string,
							"points": number
						}
					]
				},
				"targets": string
			},
			"owner": string,
			"processedUtc": string,
			"repetition": {
				"end": string,
				"iterations": number,
				"kind": string,
				"lastEndDate": string,
				"lastResult": number,
				"lastStartDate": string,
				"nextEndDate": string,
				"nextStartDate": string,
				"start": string,
				"timezone": string,
				"weekday": number,
				"weekdays": [
					boolean
				]
			},
			"template": number,
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
401	5	You do not have permission to view ReportSchedules.
401	5	You do not have permission to view Asset history.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The company whose ReportSchedules you are trying to list was not found.

GET/companies/{companyId}/reports/templates?includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

Gets the list of ReportTemplate for the specified Company.

URL Parameters

Parameter	Type	Required	Description
companyId	uint64	required	Unique identifier of the Company.
highest	uint64?	optional	When using , sets the largest valued id objects to retrieve.
includeArchive	boolean	optional	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	False by default, but when true, the command will also return deleted objects.
limit	uint16?	optional	When using , sets the maximum number of objects retrieved from the archive.
lowest	uint64?	optional	When using , sets the smallest valued id objects to retrieve.

Response description

Property	Type	Description
company	RespId	An object to contain the "id" of the Company to which the array of ReportTemplates belong.
company.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reportTemplates	Array.<ReportTemplate>	The list of requested ReportTemplates.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reportTemplates": [
		{
			"company": number,
			"fill": string,
			"graphic": string,
			"id": number,
			"name": string,
			"notes": string,
			"options": {
				"filtering": string,
				"parameters": [
					{
						"type": string,
						"value": string
					}
				],
				"places": string,
				"regions": [
					string
				],
				"scorecardRules": {
					"baseScore": number,
					"parameters": [
						{
							"condition": string,
							"duration": string,
							"points": number
						}
					]
				},
				"targets": string
			},
			"processedUtc": string,
			"stroke": string,
			"type": string,
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
401	5	You do not have permission to view ReportTemplates.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.

GET/reports/results?includeDeleted=boolean&includeArchive=boolean&limit=number&after=string&before=string

This request is an alias of /companies/{your-company-id}/reports/results.

URL Parameters

Parameter	Type	Required	Default	Description
after	datetime	optional		When using , sets the earliest objects (by dts) to retrieve from the archive.
before	datetime	optional		When using , sets the most recent objects (by dts) to retrieve from the archive.
includeArchive	boolean	optional	`false`	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	`false`	False by default, but when true the command will also return deleted objects.
limit	uint16	optional		When using , sets the maximum number of objects retrieved from the archive.
your-company-id	uint64	aliased	`{your-company-id}`	Your own Company's identifier.

PATCH/reports/results

Creates a new ReportResult that will run automatically, or updates an existing ReportResult.

HTTP Request body description

Property	Type	Required	Description
reportResult	Object.<string, ?>	always	A simple object to contain the ReportResult parameters.
reportResult.archive	boolean	optional	Indicates whether this report should be archived. Archived report ReportResult are stored for six months. Non-archive reports are purged after 24 hours.
reportResult.company	uint64?	create (complex)	The Company to which these report ReportResult belongs.
reportResult.id	uint64?	update	The unique identifier of the ReportResult you want to update.
reportResult.name	string maximum-length: 100	create	Name for the report ReportResult.
reportResult.notes	string	optional	Notes for these report ReportResult.
reportResult.options	Object.<string, ?>	create (complex)	Specified parameters for the report logic, targeted Assets, and filtering Places and/or regions.
reportResult.options.filtering	ReportFilterMode?	optional	The mechanism to use for filtering based on Places and regions.
reportResult.options.parameters	Array.<ReportParameter>	optional	A list of parameters to better shape the ReportResult.
reportResult.options.places	expression	optional	A targeting expression for limiting results which only include data from Assets interacting with the targeted Places.
reportResult.options.regions	Array.<string>	optional	A list of provinces and states, where only Assets within those regions will be included in the ReportResult.
reportResult.options.scorecardRules	Object.<string, ?>	always	Rules used to generate ReportScorecard for the ReportResult.
reportResult.options.scorecardRules.baseScore	double	optional	Base score for the ReportScorecard.
reportResult.options.scorecardRules.parameters	Array.<ReportScorecardParameter>	optional	Infraction parameters used to generate the final ReportScorecard.score.
reportResult.options.targets	expression	optional	A targeting expression for including/excluding Assets.
reportResult.template	uint64?	create (simple)	Identifier of the ReportTemplate used to help create these ReportResult.
reportResult.timezone	codified see: Timezone.code	create	The Timezone.code of the local timezone used to calculate times.
reportResult.type	ReportType?	create (complex)	The kind of logic used to build the report ReportResult.
reportResult.v	Array.<int32>	optional
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"reportResult": {
		"archive": boolean,
		"company": number,
		"id": number,
		"name": string,
		"notes": string,
		"options": {
			"filtering": string,
			"parameters": [
				{
					"type": string,
					"value": string
				}
			],
			"places": string,
			"regions": [
				string
			],
			"scorecardRules": {
				"baseScore": number,
				"parameters": [
					{
						"condition": string,
						"duration": string,
						"points": number
					}
				]
			},
			"targets": string
		},
		"template": number,
		"timezone": string,
		"type": string,
		"v": [
			number
		]
	},
	"reqId": number
}

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reportResult	RespIdCompanyTemplate	An object which contains the "id", "company", and "template" keys.
reportResult.company	uint64	Identifier of the Company to which this object belongs.
reportResult.id	uint64?	Identifier given as input for the command.
reportResult.template	uint64?	Identifier of the ReportTemplate the report object implements.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reportResult": {
		"company": number,
		"id": number,
		"template": number
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
500	2	During update: When updating a ReportResult, you cannot change options after ReportResult begins running. If you receive this error, please contact technical support.
500	2	During update: When updating a ReportResult, you cannot change timezone after ReportResult begins running. If you receive this error, please contact technical support.
400	3	The request does not contain a reportResult object, or it is invalid.
400	3	No valid changes would be performed.
400	3	During create: When creating a new ReportResult, a timezone was not given.
400	3	During create: When creating a new ReportResult, a company or template was not given.
400	3	During create: When creating a new ReportResult, a type or template was not given.
400	3	During create: When creating a new ReportResult, a name or template was not given.
400	3	During create: When creating a new ReportResult, the options or template was not given.
400	3	During create: When creating a new ReportResult, given template does not match the given company.
400	3	During update: When updating a ReportResult, the v was not an array, or contained too few numbers.
400	3	During update: When updating a ReportResult, the name was given as null or blank.
401	5	There are no targeted assets, so the report would not run.
401	5	During create: You do not have permission to create new ReportResult.
401	5	During update: You do not have permission to update ReportResult.
400	6	During update: When updating a ReportResult, an incorrect v value was given as input.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company being targetted is not found.
404	52	During create: When creating a new ReportResult, the given ReportTemplate was not found.
404	67	During update: The ReportResult you are trying to update was not found.
409	130	During create: When creating a new ReportResult, and no reportResult.options.targets are given, and the ReportTemplate also has no targets.
409	130	During create: The specified reportResult.company was found, but was not in the same Company as the given ReportTemplate.
409	130	During update: When updating a ReportResult, the reportResult.company can not be changed.

DELETE/reports/results

Deletes the specified ReportResult.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reportResult	RespDeleted	An object which contains the ReportResult's id, owning Company id, and deleted status.
reportResult.company	uint64	Identifier of the Company to which this object belongs.
reportResult.deleted	boolean	Flag showing if the object is deleted.
reportResult.id	uint64?	Identifier given as input for the command.
reportResult.v	Array.<uint32>
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reportResult": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a reportResult object, or it is invalid.
400	3	The reportResult object does not contain an id, or it is invalid.
401	5	You do not have permission to delete ReportResults.
401	5	You do not have permission to view all of the Assets targetted by this ReportResult.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company to which the ReportResult belongs was not found.
404	67	The ReportResult you are trying to delete was not found.

GET/reports/results/{resultId}?summary=boolean&breakdown=boolean&includeDeleted=boolean

Gets details of the specified ReportResult. Optionally, can also retrieve the report summary and breakdown.

URL Parameters

Parameter	Type	Required	Default	Description
breakdown	boolean	optional	`false`	When true, will also return all the ReportBreakdowns.
includeDeleted	boolean	optional		False by default, but when true the command will also return deleted objects.
resultId	uint64	required		Unique identifier of the ReportResult.
summary	boolean	optional	`false`	When true, will also return all the ReportSummarys.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reportResult	ReportResult	The requested ReportResult.
reportResult.archive	boolean	Preserve these results for later review. Results are regularly culled from the system.
reportResult.bounds	LatLngBounds	After processing, the boundary of the results are given so that a map can be focused on that area.
reportResult.bounds.east	double	Eastern longitude
reportResult.bounds.north	double	Northern latitude
reportResult.bounds.south	double	Southern latitude
reportResult.bounds.west	double	Western longitude
reportResult.company	uint64 see: Company.id	The company to which this report belongs
reportResult.completed	datetime	The date/time this result was finished processing.
reportResult.created	datetime	The date/time this result was requested.
reportResult.error	string see: ReportStatus maximum-length: 250	A field which contains report error details if the ReportResult.status is ReportStatus.failed.
reportResult.filtered	Array.<uint64>	When the report runs, a list of filtered places is calculated based on the ReportOption's place filtering expression.
reportResult.id	uint64	Unique identifier
reportResult.name	string maximum-length: 100	Name of this report.
reportResult.notes	string	Notes about this report.
reportResult.options	ReportOptions	Specified parameters for the report logic, targeted Assets, and filtering Places.
reportResult.options.filtering	ReportFilterMode	The mechanism to use for filtering based on places and regions.
reportResult.options.parameters	Array.<ReportParameter>	A list of parameters to better shape the results.
reportResult.options.places	expression	A targeting expression for limiting results which only include data from Assets interacting with the targeted Places.
reportResult.options.regions	Array.<string>	A list of provinces and states, where only assets within those regions will be included in the results.
reportResult.options.scorecardRules	ReportScorecardRules	Rules used to generate scorecard for this report.
reportResult.options.scorecardRules.baseScore	double	Base score for the scorecard.
reportResult.options.scorecardRules.parameters	Array.<ReportScorecardParameter>	Infraction parameters used to generate the final score
reportResult.options.targets	expression	A targeting expression for including/excluding Assets.
reportResult.processedUtc	datetime	When the was change procesed.
reportResult.progress	byte	The progress in processing/saving this result is a number between 0 and 100.
reportResult.runBy	email see: User.login maximum-length: 254	The login of the user that ran this report.
reportResult.schedule	uint64? see: ReportSchedule.id	A reference to the schedule used to create this result. This field is optional as not all results are created on a schedule.
reportResult.scorecards	Array.<ReportScorecard>	Scorecards for all the targeted assets based on the scorecard rules.
reportResult.status	ReportStatus	The processing status of this report.
reportResult.targeted	Array.<uint64>	When the report runs, a list of targeted assets is calculated based on the ReportOption's targeting expression.
reportResult.template	uint64? see: ReportTemplate.id	A reference to the Template used to create this result. This field is optional because templates are not necessarily required; they just make life a lot easier.
reportResult.timezone	codified see: Timezone.code	The timezone code used to adjust dates/times used in processing and saving this report.
reportResult.totals	Array.<ReportTotal>	After processing, the report totals the values from all summary instances for a quick overview of the kind of results generated.
reportResult.type	ReportType	Refers to the type of logic used by this report.
reportResult.updated		by: login, from: monster
reportResult.v	Array.<uint32>	Object version keys used to validate synchronization for all object properties.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reportResult": {
		"archive": boolean,
		"bounds": {
			"east": number,
			"north": number,
			"south": number,
			"west": number
		},
		"company": number,
		"completed": string,
		"created": string,
		"error": string,
		"filtered": [
			number
		],
		"id": number,
		"name": string,
		"notes": string,
		"options": {
			"filtering": string,
			"parameters": [
				{
					"type": string,
					"value": string
				}
			],
			"places": string,
			"regions": [
				string
			],
			"scorecardRules": {
				"baseScore": number,
				"parameters": [
					{
						"condition": string,
						"duration": string,
						"points": number
					}
				]
			},
			"targets": string
		},
		"processedUtc": string,
		"progress": number,
		"runBy": string,
		"schedule": number,
		"scorecards": [
			{
				"asset": number,
				"rulePoints": {
					string: number
				},
				"score": number
			}
		],
		"status": string,
		"targeted": [
			number
		],
		"template": number,
		"timezone": string,
		"totals": [
			{
				"asset": number,
				"distance": number,
				"duration": string,
				"stateDetail": string,
				"summaryCount": number,
				"value": number,
				"valueType": string
			}
		],
		"type": string,
		"updated": {
		},
		"v": [
			number
		]
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a reportResult object, or it is invalid.
400	3	The reportResult object does not contain an id, or it is invalid.
401	5	You do not have permission to view ReportResults.
401	5	You do not have permission to any of the Assets targetted by this ReportResult.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company to which the ReportResult belongs was not found.
404	67	The ReportResult you are trying to retrieve was not found.
400	95	When trynig to get summary and/or breakdown, the ReportResult has not finished running.

POST/reports/results/{resultId}

Creates a new ReportResult that will run automatically, or updates an existing ReportResult.

URL Parameters

Parameter	Type	Required	Description
resultId	uint64?	optional	Unique identifier of the ReportResult. This value is optional, and ignored by the command.

HTTP Request body description

Property	Type	Required	Description
reportResult	Object.<string, ?>	always	A simple object to contain the ReportResult parameters.
reportResult.archive	boolean	optional	Indicates whether this report should be archived. Archived report ReportResult are stored for six months. Non-archive reports are purged after 24 hours.
reportResult.company	uint64?	create (complex)	The Company to which these report ReportResult belongs.
reportResult.id	uint64?	update	The unique identifier of the ReportResult you want to update.
reportResult.name	string maximum-length: 100	create	Name for the report ReportResult.
reportResult.notes	string	optional	Notes for these report ReportResult.
reportResult.options	Object.<string, ?>	create (complex)	Specified parameters for the report logic, targeted Assets, and filtering Places and/or regions.
reportResult.options.filtering	ReportFilterMode?	optional	The mechanism to use for filtering based on Places and regions.
reportResult.options.parameters	Array.<ReportParameter>	optional	A list of parameters to better shape the ReportResult.
reportResult.options.places	expression	optional	A targeting expression for limiting results which only include data from Assets interacting with the targeted Places.
reportResult.options.regions	Array.<string>	optional	A list of provinces and states, where only Assets within those regions will be included in the ReportResult.
reportResult.options.scorecardRules	Object.<string, ?>	always	Rules used to generate ReportScorecard for the ReportResult.
reportResult.options.scorecardRules.baseScore	double	optional	Base score for the ReportScorecard.
reportResult.options.scorecardRules.parameters	Array.<ReportScorecardParameter>	optional	Infraction parameters used to generate the final ReportScorecard.score.
reportResult.options.targets	expression	optional	A targeting expression for including/excluding Assets.
reportResult.template	uint64?	create (simple)	Identifier of the ReportTemplate used to help create these ReportResult.
reportResult.timezone	codified see: Timezone.code	create	The Timezone.code of the local timezone used to calculate times.
reportResult.type	ReportType?	create (complex)	The kind of logic used to build the report ReportResult.
reportResult.v	Array.<int32>	optional
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"reportResult": {
		"archive": boolean,
		"company": number,
		"id": number,
		"name": string,
		"notes": string,
		"options": {
			"filtering": string,
			"parameters": [
				{
					"type": string,
					"value": string
				}
			],
			"places": string,
			"regions": [
				string
			],
			"scorecardRules": {
				"baseScore": number,
				"parameters": [
					{
						"condition": string,
						"duration": string,
						"points": number
					}
				]
			},
			"targets": string
		},
		"template": number,
		"timezone": string,
		"type": string,
		"v": [
			number
		]
	},
	"reqId": number
}

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reportResult	RespIdCompanyTemplate	An object which contains the "id", "company", and "template" keys.
reportResult.company	uint64	Identifier of the Company to which this object belongs.
reportResult.id	uint64?	Identifier given as input for the command.
reportResult.template	uint64?	Identifier of the ReportTemplate the report object implements.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reportResult": {
		"company": number,
		"id": number,
		"template": number
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
500	2	During update: When updating a ReportResult, you cannot change options after ReportResult begins running. If you receive this error, please contact technical support.
500	2	During update: When updating a ReportResult, you cannot change timezone after ReportResult begins running. If you receive this error, please contact technical support.
400	3	The request does not contain a reportResult object, or it is invalid.
400	3	No valid changes would be performed.
400	3	During create: When creating a new ReportResult, a timezone was not given.
400	3	During create: When creating a new ReportResult, a company or template was not given.
400	3	During create: When creating a new ReportResult, a type or template was not given.
400	3	During create: When creating a new ReportResult, a name or template was not given.
400	3	During create: When creating a new ReportResult, the options or template was not given.
400	3	During create: When creating a new ReportResult, given template does not match the given company.
400	3	During update: When updating a ReportResult, the v was not an array, or contained too few numbers.
400	3	During update: When updating a ReportResult, the name was given as null or blank.
401	5	There are no targeted assets, so the report would not run.
401	5	During create: You do not have permission to create new ReportResult.
401	5	During update: You do not have permission to update ReportResult.
400	6	During update: When updating a ReportResult, an incorrect v value was given as input.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company being targetted is not found.
404	52	During create: When creating a new ReportResult, the given ReportTemplate was not found.
404	67	During update: The ReportResult you are trying to update was not found.
409	130	During create: When creating a new ReportResult, and no reportResult.options.targets are given, and the ReportTemplate also has no targets.
409	130	During create: The specified reportResult.company was found, but was not in the same Company as the given ReportTemplate.
409	130	During update: When updating a ReportResult, the reportResult.company can not be changed.

DELETE/reports/results/{resultId}

Deletes the specified ReportResult.

URL Parameters

Parameter	Type	Required	Description
resultId	uint64	required	Unique identifier of the ReportResult.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reportResult	RespDeleted	An object which contains the ReportResult's id, owning Company id, and deleted status.
reportResult.company	uint64	Identifier of the Company to which this object belongs.
reportResult.deleted	boolean	Flag showing if the object is deleted.
reportResult.id	uint64?	Identifier given as input for the command.
reportResult.v	Array.<uint32>
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reportResult": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a reportResult object, or it is invalid.
400	3	The reportResult object does not contain an id, or it is invalid.
401	5	You do not have permission to delete ReportResults.
401	5	You do not have permission to view all of the Assets targetted by this ReportResult.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company to which the ReportResult belongs was not found.
404	67	The ReportResult you are trying to delete was not found.

PATCH/reports/results/{resultId}/restore

Restores a deleted ReportResult.

URL Parameters

Parameter	Type	Required	Description
resultId	uint64	required	Unique identifier of the ReportResult.

HTTP Request body description

Property	Type	Required	Description
reportResult	ParamId	always	An object to contain the "id" of the ReportResult.
reportResult.id	uint64	always	Identifier given as input for the command.
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"reportResult": {
		"id": number
	},
	"reqId": number
}

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reportResult	RespDeleted	An object which contains the ReportResult's id, owning Company id, and deleted status.
reportResult.company	uint64	Identifier of the Company to which this object belongs.
reportResult.deleted	boolean	Flag showing if the object is deleted.
reportResult.id	uint64?	Identifier given as input for the command.
reportResult.v	Array.<uint32>
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reportResult": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a reportResult object, or it is invalid.
400	3	The reportResult object does not contain an id, or it is invalid.
401	5	You do not have permission to restore ReportResults.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	67	The ReportResult you are trying to restore was not found.
400	75	The ReportResult you are trying to restore is not deleted.

GET/reports/results?schedule={uint64}&includeDeleted=boolean&includeArchive=boolean&limit=number&after=string&before=string

Gets the list of ReportResult for the specified ReportSchedule.

URL Parameters

Parameter	Type	Required	Description
after	datetime	optional	When using , sets the earliest objects (by dts) to retrieve from the archive.
before	datetime	optional	When using , sets the most recent objects (by dts) to retrieve from the archive.
includeArchive	boolean	optional	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	False by default, but when true the command will also return deleted objects.
limit	uint16?	optional	When using , sets the maximum number of objects retrieved from the archive.
schedule	uint64	required	Unique identifier of the ReportSchedule.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reportResults	Array.<ReportResult>	The list of requested ReportResults.
reportSchedule	RespIdCompany	An object to contain the "id" of the ReportSchedule to which the array of ReportResults belong.
reportSchedule.company	uint64	Identifier of the Company to which this object belongs.
reportSchedule.id	uint64?	Identifier given as input for the command.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reportResults": [
		{
			"archive": boolean,
			"bounds": {
				"east": number,
				"north": number,
				"south": number,
				"west": number
			},
			"company": number,
			"completed": string,
			"created": string,
			"error": string,
			"filtered": [
				number
			],
			"id": number,
			"name": string,
			"notes": string,
			"options": {
				"filtering": string,
				"parameters": [
					{
						"type": string,
						"value": string
					}
				],
				"places": string,
				"regions": [
					string
				],
				"scorecardRules": {
					"baseScore": number,
					"parameters": [
						{
							"condition": string,
							"duration": string,
							"points": number
						}
					]
				},
				"targets": string
			},
			"processedUtc": string,
			"progress": number,
			"runBy": string,
			"schedule": number,
			"scorecards": [
				{
					"asset": number,
					"rulePoints": {
						string: number
					},
					"score": number
				}
			],
			"status": string,
			"targeted": [
				number
			],
			"template": number,
			"timezone": string,
			"totals": [
				{
					"asset": number,
					"distance": number,
					"duration": string,
					"stateDetail": string,
					"summaryCount": number,
					"value": number,
					"valueType": string
				}
			],
			"type": string,
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"reportSchedule": {
		"company": number,
		"id": number
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a reportSchedule object, or it is invalid.
400	3	The reportSchedule object does not contain an id, or it is invalid.
401	5	You do not have permission to view ReportResults.
401	5	You do not have permission to any of the Assets in the Company.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company whose ReportResults you are trying to list was not found.
404	93	The ReportSchedule whose ReportResults you are trying to list was not found.

GET/reports/results?template={uint64}&includeDeleted=boolean&includeArchive=boolean&limit=number&after=string&before=string

Gets the list of ReportResult for the specified ReportTemplate.

URL Parameters

Parameter	Type	Required	Description
after	datetime	optional	When using , sets the earliest objects (by dts) to retrieve from the archive.
before	datetime	optional	When using , sets the most recent objects (by dts) to retrieve from the archive.
includeArchive	boolean	optional	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	False by default, but when true the command will also return deleted objects.
limit	uint16?	optional	When using , sets the maximum number of objects retrieved from the archive.
template	uint64	required	Unique identifier of the ReportTemplate.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reportResults	Array.<ReportResult>	The list of requested ReportResults.
reportTemplate	RespIdCompany	An object to contain the "id" of the ReportTemplate to which the array of ReportResults belong.
reportTemplate.company	uint64	Identifier of the Company to which this object belongs.
reportTemplate.id	uint64?	Identifier given as input for the command.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reportResults": [
		{
			"archive": boolean,
			"bounds": {
				"east": number,
				"north": number,
				"south": number,
				"west": number
			},
			"company": number,
			"completed": string,
			"created": string,
			"error": string,
			"filtered": [
				number
			],
			"id": number,
			"name": string,
			"notes": string,
			"options": {
				"filtering": string,
				"parameters": [
					{
						"type": string,
						"value": string
					}
				],
				"places": string,
				"regions": [
					string
				],
				"scorecardRules": {
					"baseScore": number,
					"parameters": [
						{
							"condition": string,
							"duration": string,
							"points": number
						}
					]
				},
				"targets": string
			},
			"processedUtc": string,
			"progress": number,
			"runBy": string,
			"schedule": number,
			"scorecards": [
				{
					"asset": number,
					"rulePoints": {
						string: number
					},
					"score": number
				}
			],
			"status": string,
			"targeted": [
				number
			],
			"template": number,
			"timezone": string,
			"totals": [
				{
					"asset": number,
					"distance": number,
					"duration": string,
					"stateDetail": string,
					"summaryCount": number,
					"value": number,
					"valueType": string
				}
			],
			"type": string,
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"reportTemplate": {
		"company": number,
		"id": number
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a reportTemplate object, or it is invalid.
400	3	The reportTemplate object does not contain an id, or it is invalid.
401	5	You do not have permission to view ReportResults.
401	5	You do not have permission to any of the Assets in the Company.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company whose ReportResults you are trying to list was not found.
404	52	The ReportTemplate whose ReportResults you are trying to list was not found.

GET/reports/schedules?includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

This request is an alias of /companies/{your-company-id}/reports/schedules.

URL Parameters

Parameter	Type	Required	Default	Description
highest	uint64	optional		When using , sets the maximum id when listing from the database.
includeArchive	boolean	optional	`false`	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	`false`	False by default, but when true the command will also return deleted objects.
limit	uint16	optional		When using , sets the maximum number of objects in this response.
lowest	uint64	optional		When using , sets the minimum id when listing from the database.
your-company-id	uint64	aliased	`{your-company-id}`	Your own Company's identifier.

PATCH/reports/schedules

Creates a new, or updates an existing ReportSchedule.

HTTP Request body description

Property	Type	Required	Description
reportSchedule	Object.<string, ?>	always	A simple object to contain the ReportSchedule parameters.
reportSchedule.enabled	boolean	optional	Indicates whether this schedule is allowed to run.
reportSchedule.id	uint64?	update	The unique identifier of the ReportSchedule you want to update.
reportSchedule.name	string maximum-length: 100	create	Name for the ReportSchedule.
reportSchedule.notes	string	optional	Notes for the ReportSchedule.
reportSchedule.notify	Object.<string, ?>	always	A list of users and a targeting expression for Assets which receive report results notifications.
reportSchedule.notify.assets	expression maximum-length: 255	optional	A targeting expression to identify which Assets receive the ReportResult.
reportSchedule.notify.users	Array.<email> maximum-count: 50	optional	List of Users to send emailed report. Each email will only contain the ReportResult for the Assets each User is allowed to view.
reportSchedule.options	Object.<string, ?>	always	Specified parameters for the report logic, targeted Assets, and filtering Places.
reportSchedule.options.filtering	ReportFilterMode?	optional	The mechanism to use for filtering based on Places and regions.
reportSchedule.options.parameters	Array.<ReportParameter>	optional	A list of parameters to better shape the ReportResult.
reportSchedule.options.places	expression	optional	A targeting expression for limiting results which only include data from Assets interacting with the targeted Places.
reportSchedule.options.regions	Array.<string>	optional	A list of provinces and states, where only Assets within those regions will be included in the ReportResult.
reportSchedule.options.scorecardRules	Object.<string, ?>	always	Rules used to generate ReportScorecard for the ReportResult.
reportSchedule.options.scorecardRules.baseScore	double	optional	Base score for the ReportScorecard.
reportSchedule.options.scorecardRules.parameters	Array.<ReportScorecardParameter>	optional	Infraction parameters used to generate the final ReportScorecard.score.
reportSchedule.options.targets	expression	optional	A targeting expression for including/excluding Assets.
reportSchedule.owner	email	create	The user which owns the schedule. When report results are created, they will be created with this user's Asset permissions.
reportSchedule.repetition	Object.<string, ?>	create	The recurring schedule to generate report results.
reportSchedule.repetition.end	datetime	optional	The optional time when the ReportSchedule stops recurring in local-time (not UTC).
reportSchedule.repetition.kind	ReportRecurrenceType?	optional	How often the report is automatically run. Daily, weekly, monthly, etc...
reportSchedule.repetition.start	datetime	optional	When the ReportSchedule is to begin recurring in local-time (not UTC).
reportSchedule.repetition.weekday	byte?	optional	Used only for weekly schedules, it's a number between 0 and 6 representing the day of the week, with Sunday being the first day of the week.
reportSchedule.repetition.weekdays	Array.<boolean>	optional	Used only for daily schedules, this 7 item, boolean array, determines if the ReportSchedule should recur on that day of the week.
reportSchedule.template	uint64?	create	Identifier of the ReportTemplate used to help create results.
reportSchedule.v	Array.<int32>	optional
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"reportSchedule": {
		"enabled": boolean,
		"id": number,
		"name": string,
		"notes": string,
		"notify": {
			"assets": string,
			"users": [
				string
			]
		},
		"options": {
			"filtering": string,
			"parameters": [
				{
					"type": string,
					"value": string
				}
			],
			"places": string,
			"regions": [
				string
			],
			"scorecardRules": {
				"baseScore": number,
				"parameters": [
					{
						"condition": string,
						"duration": string,
						"points": number
					}
				]
			},
			"targets": string
		},
		"owner": string,
		"repetition": {
			"end": string,
			"kind": string,
			"start": string,
			"weekday": number,
			"weekdays": [
				boolean
			]
		},
		"template": number,
		"v": [
			number
		]
	},
	"reqId": number
}

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reportSchedule	RespIdCompanyTemplate	An object which contains the "id", "company", and "template" keys.
reportSchedule.company	uint64	Identifier of the Company to which this object belongs.
reportSchedule.id	uint64?	Identifier given as input for the command.
reportSchedule.template	uint64?	Identifier of the ReportTemplate the report object implements.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reportSchedule": {
		"company": number,
		"id": number,
		"template": number
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a reportSchedule object, or it is invalid.
400	3	No valid changes would be performed.
400	3	The reportSchedule.owner value is not a valid email address or SelfMachine.key.
400	3	The reportSchedule.repetition.kind is not a valid value.
400	3	The reportSchedule.repetition.weekdays is not a valid value.
400	3	The reportSchedule.repetition.weekday is not a valid value.
400	3	One or more of the reportSchedule.options.parameters was not a valid.
400	3	One or more of the reportSchedule.options parameters' type was not a valid.
400	3	One or more of the reportSchedule.options.scorecardRules.parameters was not a valid.
400	3	One or more of the reportSchedule.options.scorecardRules.parameters' ReportScorecardParameter.conditions was not a valid.
400	3	One or more of the reportSchedule.options.scorecardRules.parameters' ReportScorecardParameter.durations was not a valid.
400	3	One or more of the reportSchedule.options.scorecardRules.parameters' ReportScorecardParameter.points was not a valid.
400	3	During create: When creating a new ReportSchedule, a template was not given.
400	3	During create: When creating a new ReportSchedule, a name or template was not given.
400	3	During create: When creating a new ReportSchedule, the given repetition pattern parameters were incomplete.
400	3	During update: When updating a ReportSchedule, the v was not an array, or contained too few numbers.
400	3	During update: When updating a ReportSchedule, the name was given as null or blank.
400	3	The options filtering specified was not a valid. Returns an ErrorDetailEnum as the `errorDetails`.
400	3	One or more of the options parameters type was specified more than once. Returns an ErrorDetailInput as the `errorDetails`.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	54	During update: When updating the ReportSchedule.owner, and it is a User, and cannot be found.
404	54	During update: When updating the ReportSchedule.repetition, and the ReportSchedule.owner is a User, and cannot be found.
404	127	During update: When updating the ReportSchedule.owner, and it is a Machine, and cannot be found.
404	127	During update: When updating the ReportSchedule.repetition, and the ReportSchedule.owner is a Machine, and cannot be found.
409	130	During update: When updating a ReportSchedule, the reportSchedule.template can not be changed.

DELETE/reports/schedules

Deletes the specified ReportSchedule.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reportSchedule	RespDeleted	An object which contains the ReportSchedule's id, owning Company id, and deleted status.
reportSchedule.company	uint64	Identifier of the Company to which this object belongs.
reportSchedule.deleted	boolean	Flag showing if the object is deleted.
reportSchedule.id	uint64?	Identifier given as input for the command.
reportSchedule.v	Array.<uint32>
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reportSchedule": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a reportSchedule object, or it is invalid.
400	3	The reportSchedule object does not contain an id, or it is invalid.
401	5	You do not have permission to view ReportSchedules.
401	5	You do not have permission to all of the Assets targetted by this ReportSchedule (or ReportTemplate).
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company to which the ReportSchedule belongs was not found.
404	52	The ReportTemplate to which the ReportSchedule refers was not found.
404	93	The ReportSchedule you are trying to retrieve was not found.

GET/reports/schedules/{scheduleId}?includeDeleted=boolean

Gets details of the specified ReportSchedule.

URL Parameters

Parameter	Type	Required	Description
includeDeleted	boolean	optional	False by default, but when true the command will also return deleted objects.
scheduleId	uint64	required	Unique identifier of the ReportSchedule.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reportSchedule	ReportSchedule	The requested ReportSchedule.
reportSchedule.company	uint64 see: Company.id	The company to which this report belongs
reportSchedule.enabled	boolean	Indicates whether this schedule is allowed to run.
reportSchedule.id	uint64	Unique identifier
reportSchedule.name	string maximum-length: 100	Name of this report.
reportSchedule.notes	string	Notes about this report.
reportSchedule.notify	ReportNotifications	A list of users and a targeting expression for assets which receive report results notifications.
reportSchedule.notify.assets	expression	A targeting expression to identify which assets receive the report results. The results emailed to each asset will only be for themselves, not all assets. To receive the emailed results, the Asset must have a Asset.messagingAddress, or for a Person type asset, their Contact.emails["Email"].
reportSchedule.notify.users	Array.<email> for values see: UserGeneral.login maximum-length of values: 50	List of users to send emailed report. Each email will only contain the results for the assets each user is allowed to view.
reportSchedule.options	ReportOptions	Specified parameters for the report logic, targeted Assets, and filtering Places.
reportSchedule.options.filtering	ReportFilterMode	The mechanism to use for filtering based on places and regions.
reportSchedule.options.parameters	Array.<ReportParameter>	A list of parameters to better shape the results.
reportSchedule.options.places	expression	A targeting expression for limiting results which only include data from Assets interacting with the targeted Places.
reportSchedule.options.regions	Array.<string>	A list of provinces and states, where only assets within those regions will be included in the results.
reportSchedule.options.scorecardRules	ReportScorecardRules	Rules used to generate scorecard for this report.
reportSchedule.options.scorecardRules.baseScore	double	Base score for the scorecard.
reportSchedule.options.scorecardRules.parameters	Array.<ReportScorecardParameter>	Infraction parameters used to generate the final score
reportSchedule.options.targets	expression	A targeting expression for including/excluding Assets.
reportSchedule.owner	email see: User.login maximum-length: 254	Login of the user who has ownership of this report schedule.
reportSchedule.processedUtc	datetime	When the was change procesed.
reportSchedule.repetition	ReportRecurrence	The recurring schedule to generate report results.
reportSchedule.repetition.end	datetime	The optional time when the schedule stops recurring in local-time (not UTC).
reportSchedule.repetition.iterations	uint16	The number of times this schedule has been invoked to generate results.
reportSchedule.repetition.kind	ReportRecurrenceType	How often the report is automatically run. Daily, weekly, monthly, etc...
reportSchedule.repetition.lastEndDate	datetime	The date/time stamp from the last result used to inform the nextStartDate and nextEndDate properties. This value is null when the schedule has not yet run once.
reportSchedule.repetition.lastResult	uint64?	The unique identifier of the last ReportResult generated by this schedule.
reportSchedule.repetition.lastStartDate	datetime	The date/time stamp from the last result used to inform the nextStartDate and nextEndDate properties. This value is null when the schedule has not yet run once.
reportSchedule.repetition.nextEndDate	datetime	This date/time is used as the endDate ReportParameter for the next iteration of this recurring report. This value is null when the schedule is calculated to stop recurring.
reportSchedule.repetition.nextStartDate	datetime	This date/time is used as the startDate ReportParameter for the next iteration of this recurring report. This value is null when the schedule is calculated to stop recurring.
reportSchedule.repetition.start	datetime	When the schedule is to begin recurring in local-time (not UTC).
reportSchedule.repetition.timezone Deprecated	codified see: Timezone.code	The local timezone used to calculate recurring date/time ranges. Use owner.timezone instead.
reportSchedule.repetition.weekday	byte	Used only for weekly schedules, it's a number between 0 and 6 representing the day of the week, with Sunday being the first day of the week.
reportSchedule.repetition.weekdays	Array.<boolean> fixed count: 7	Used only for daily schedules, this 7 item, boolean array, determines if the schedule should recur on that day of the week.
reportSchedule.template	uint64 see: ReportTemplate.id	A reference to the Template used to create this result.
reportSchedule.updated		by: login, from: monster
reportSchedule.v	Array.<uint32>	Object version keys used to validate synchronization for all object properties.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reportSchedule": {
		"company": number,
		"enabled": boolean,
		"id": number,
		"name": string,
		"notes": string,
		"notify": {
			"assets": string,
			"users": [
				string
			]
		},
		"options": {
			"filtering": string,
			"parameters": [
				{
					"type": string,
					"value": string
				}
			],
			"places": string,
			"regions": [
				string
			],
			"scorecardRules": {
				"baseScore": number,
				"parameters": [
					{
						"condition": string,
						"duration": string,
						"points": number
					}
				]
			},
			"targets": string
		},
		"owner": string,
		"processedUtc": string,
		"repetition": {
			"end": string,
			"iterations": number,
			"kind": string,
			"lastEndDate": string,
			"lastResult": number,
			"lastStartDate": string,
			"nextEndDate": string,
			"nextStartDate": string,
			"start": string,
			"timezone": string,
			"weekday": number,
			"weekdays": [
				boolean
			]
		},
		"template": number,
		"updated": {
		},
		"v": [
			number
		]
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a reportSchedule object, or it is invalid.
400	3	The reportSchedule object does not contain an id, or it is invalid.
401	5	You do not have permission to view ReportSchedules.
401	5	You do not have permission to any of the Assets targetted by this ReportSchedule (or ReportTemplate).
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The company to which the report belongs was not found.
404	52	The ReportTemplate to which the ReportSchedule refers was not found.
404	93	The ReportSchedule you are trying to retrieve was not found.

POST/reports/schedules/{scheduleId}

Creates a new, or updates an existing ReportSchedule.

URL Parameters

Parameter	Type	Required	Description
scheduleId	uint64?	optional	Unique identifier of the ReportSchedule. This value is optional, and ignored by the command.

HTTP Request body description

Property	Type	Required	Description
reportSchedule	Object.<string, ?>	always	A simple object to contain the ReportSchedule parameters.
reportSchedule.enabled	boolean	optional	Indicates whether this schedule is allowed to run.
reportSchedule.id	uint64?	update	The unique identifier of the ReportSchedule you want to update.
reportSchedule.name	string maximum-length: 100	create	Name for the ReportSchedule.
reportSchedule.notes	string	optional	Notes for the ReportSchedule.
reportSchedule.notify	Object.<string, ?>	always	A list of users and a targeting expression for Assets which receive report results notifications.
reportSchedule.notify.assets	expression maximum-length: 255	optional	A targeting expression to identify which Assets receive the ReportResult.
reportSchedule.notify.users	Array.<email> maximum-count: 50	optional	List of Users to send emailed report. Each email will only contain the ReportResult for the Assets each User is allowed to view.
reportSchedule.options	Object.<string, ?>	always	Specified parameters for the report logic, targeted Assets, and filtering Places.
reportSchedule.options.filtering	ReportFilterMode?	optional	The mechanism to use for filtering based on Places and regions.
reportSchedule.options.parameters	Array.<ReportParameter>	optional	A list of parameters to better shape the ReportResult.
reportSchedule.options.places	expression	optional	A targeting expression for limiting results which only include data from Assets interacting with the targeted Places.
reportSchedule.options.regions	Array.<string>	optional	A list of provinces and states, where only Assets within those regions will be included in the ReportResult.
reportSchedule.options.scorecardRules	Object.<string, ?>	always	Rules used to generate ReportScorecard for the ReportResult.
reportSchedule.options.scorecardRules.baseScore	double	optional	Base score for the ReportScorecard.
reportSchedule.options.scorecardRules.parameters	Array.<ReportScorecardParameter>	optional	Infraction parameters used to generate the final ReportScorecard.score.
reportSchedule.options.targets	expression	optional	A targeting expression for including/excluding Assets.
reportSchedule.owner	email	create	The user which owns the schedule. When report results are created, they will be created with this user's Asset permissions.
reportSchedule.repetition	Object.<string, ?>	create	The recurring schedule to generate report results.
reportSchedule.repetition.end	datetime	optional	The optional time when the ReportSchedule stops recurring in local-time (not UTC).
reportSchedule.repetition.kind	ReportRecurrenceType?	optional	How often the report is automatically run. Daily, weekly, monthly, etc...
reportSchedule.repetition.start	datetime	optional	When the ReportSchedule is to begin recurring in local-time (not UTC).
reportSchedule.repetition.weekday	byte?	optional	Used only for weekly schedules, it's a number between 0 and 6 representing the day of the week, with Sunday being the first day of the week.
reportSchedule.repetition.weekdays	Array.<boolean>	optional	Used only for daily schedules, this 7 item, boolean array, determines if the ReportSchedule should recur on that day of the week.
reportSchedule.template	uint64?	create	Identifier of the ReportTemplate used to help create results.
reportSchedule.v	Array.<int32>	optional
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"reportSchedule": {
		"enabled": boolean,
		"id": number,
		"name": string,
		"notes": string,
		"notify": {
			"assets": string,
			"users": [
				string
			]
		},
		"options": {
			"filtering": string,
			"parameters": [
				{
					"type": string,
					"value": string
				}
			],
			"places": string,
			"regions": [
				string
			],
			"scorecardRules": {
				"baseScore": number,
				"parameters": [
					{
						"condition": string,
						"duration": string,
						"points": number
					}
				]
			},
			"targets": string
		},
		"owner": string,
		"repetition": {
			"end": string,
			"kind": string,
			"start": string,
			"weekday": number,
			"weekdays": [
				boolean
			]
		},
		"template": number,
		"v": [
			number
		]
	},
	"reqId": number
}

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reportSchedule	RespIdCompanyTemplate	An object which contains the "id", "company", and "template" keys.
reportSchedule.company	uint64	Identifier of the Company to which this object belongs.
reportSchedule.id	uint64?	Identifier given as input for the command.
reportSchedule.template	uint64?	Identifier of the ReportTemplate the report object implements.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reportSchedule": {
		"company": number,
		"id": number,
		"template": number
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a reportSchedule object, or it is invalid.
400	3	No valid changes would be performed.
400	3	The reportSchedule.owner value is not a valid email address or SelfMachine.key.
400	3	The reportSchedule.repetition.kind is not a valid value.
400	3	The reportSchedule.repetition.weekdays is not a valid value.
400	3	The reportSchedule.repetition.weekday is not a valid value.
400	3	One or more of the reportSchedule.options.parameters was not a valid.
400	3	One or more of the reportSchedule.options parameters' type was not a valid.
400	3	One or more of the reportSchedule.options.scorecardRules.parameters was not a valid.
400	3	One or more of the reportSchedule.options.scorecardRules.parameters' ReportScorecardParameter.conditions was not a valid.
400	3	One or more of the reportSchedule.options.scorecardRules.parameters' ReportScorecardParameter.durations was not a valid.
400	3	One or more of the reportSchedule.options.scorecardRules.parameters' ReportScorecardParameter.points was not a valid.
400	3	During create: When creating a new ReportSchedule, a template was not given.
400	3	During create: When creating a new ReportSchedule, a name or template was not given.
400	3	During create: When creating a new ReportSchedule, the given repetition pattern parameters were incomplete.
400	3	During update: When updating a ReportSchedule, the v was not an array, or contained too few numbers.
400	3	During update: When updating a ReportSchedule, the name was given as null or blank.
400	3	The options filtering specified was not a valid. Returns an ErrorDetailEnum as the `errorDetails`.
400	3	One or more of the options parameters type was specified more than once. Returns an ErrorDetailInput as the `errorDetails`.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	54	During update: When updating the ReportSchedule.owner, and it is a User, and cannot be found.
404	54	During update: When updating the ReportSchedule.repetition, and the ReportSchedule.owner is a User, and cannot be found.
404	127	During update: When updating the ReportSchedule.owner, and it is a Machine, and cannot be found.
404	127	During update: When updating the ReportSchedule.repetition, and the ReportSchedule.owner is a Machine, and cannot be found.
409	130	During update: When updating a ReportSchedule, the reportSchedule.template can not be changed.

DELETE/reports/schedules/{scheduleId}

Deletes the specified ReportSchedule.

URL Parameters

Parameter	Type	Required	Description
scheduleId	uint64	required	Unique identifier of the ReportSchedule.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reportSchedule	RespDeleted	An object which contains the ReportSchedule's id, owning Company id, and deleted status.
reportSchedule.company	uint64	Identifier of the Company to which this object belongs.
reportSchedule.deleted	boolean	Flag showing if the object is deleted.
reportSchedule.id	uint64?	Identifier given as input for the command.
reportSchedule.v	Array.<uint32>
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reportSchedule": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a reportSchedule object, or it is invalid.
400	3	The reportSchedule object does not contain an id, or it is invalid.
401	5	You do not have permission to view ReportSchedules.
401	5	You do not have permission to all of the Assets targetted by this ReportSchedule (or ReportTemplate).
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company to which the ReportSchedule belongs was not found.
404	52	The ReportTemplate to which the ReportSchedule refers was not found.
404	93	The ReportSchedule you are trying to retrieve was not found.

DELETE/reports/schedules/{scheduleId}/restore

Restores a deleted ReportSchedule.

URL Parameters

Parameter	Type	Required	Description
scheduleId	uint64	required	Unique identifier of the ReportSchedule.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reportSchedule	RespDeleted	An object which contains the ReportSchedule's id, owning Company id, and deleted status.
reportSchedule.company	uint64	Identifier of the Company to which this object belongs.
reportSchedule.deleted	boolean	Flag showing if the object is deleted.
reportSchedule.id	uint64?	Identifier given as input for the command.
reportSchedule.v	Array.<uint32>
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reportSchedule": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a reportSchedule object, or it is invalid.
400	3	The reportSchedule object does not contain an id, or it is invalid.
401	5	You do not have permission to restore ReportSchedules.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	93	The ReportSchedule you are trying to restore was not found.
400	94	The ReportSchedule you are trying to restore is not deleted.

GET/reports/schedules?template={uint64}&includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

Gets the list of ReportSchedules for the specified ReportTemplate.

URL Parameters

Parameter	Type	Required	Description
highest	uint64?	optional	When using , sets the largest valued id objects to retrieve.
includeArchive	boolean	optional	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	False by default, but when true, the command will also return deleted objects.
limit	uint16?	optional	When using , sets the maximum number of objects retrieved from the archive.
lowest	uint64?	optional	When using , sets the smallest valued id objects to retrieve.
template	uint64	required	Unique identifier of the ReportTemplate.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reportSchedules	Array.<ReportSchedule>	The list of schedules.
reportTemplate	RespIdCompany	An object which contains only one key "id" when there is no error. The "id" key is the unique identifier of the company to which the array of objects relate.
reportTemplate.company	uint64	Identifier of the Company to which this object belongs.
reportTemplate.id	uint64?	Identifier given as input for the command.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reportSchedules": [
		{
			"company": number,
			"enabled": boolean,
			"id": number,
			"name": string,
			"notes": string,
			"notify": {
				"assets": string,
				"users": [
					string
				]
			},
			"options": {
				"filtering": string,
				"parameters": [
					{
						"type": string,
						"value": string
					}
				],
				"places": string,
				"regions": [
					string
				],
				"scorecardRules": {
					"baseScore": number,
					"parameters": [
						{
							"condition": string,
							"duration": string,
							"points": number
						}
					]
				},
				"targets": string
			},
			"owner": string,
			"processedUtc": string,
			"repetition": {
				"end": string,
				"iterations": number,
				"kind": string,
				"lastEndDate": string,
				"lastResult": number,
				"lastStartDate": string,
				"nextEndDate": string,
				"nextStartDate": string,
				"start": string,
				"timezone": string,
				"weekday": number,
				"weekdays": [
					boolean
				]
			},
			"template": number,
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"reportTemplate": {
		"company": number,
		"id": number
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a reportTemplate object, or it is invalid.
400	3	The reportTemplate object does not contain an id, or it is invalid.
401	5	You do not have permission to view ReportTemplates.
401	5	You do not have permission to view ReportSchedules.
401	5	You do not have permission to view Asset history.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The company whose ReportSchedules you are trying to list was not found.
404	52	The ReportTemplate whose ReportSchedules you are trying to list was not found.

GET/reports/templates?includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

This request is an alias of /companies/{your-company-id}/reports/templates.

URL Parameters

Parameter	Type	Required	Default	Description
highest	uint64	optional		When using , sets the maximum id when listing from the database.
includeArchive	boolean	optional	`false`	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	`false`	False by default, but when true the command will also return deleted objects.
limit	uint16	optional		When using , sets the maximum number of objects in this response.
lowest	uint64	optional		When using , sets the minimum id when listing from the database.
your-company-id	uint64	aliased	`{your-company-id}`	Your own Company's identifier.

PATCH/reports/templates

Creates a new or, updates an existing ReportTemplate.

HTTP Request body description

Property	Type	Required	Description
reportTemplate	Object.<string, ?>	always	A simple object to contain the ReportTemplate parameters.
reportTemplate.company	uint64?	create	The Company to which this ReportTemplate belongs.
reportTemplate.fill	string	optional	Background and fill colour in the UI.
reportTemplate.graphic	string	optional	The name of the symbol shown in the UI.
reportTemplate.id	uint64?	update	The unique identifier of the ReportTemplate you want to update.
reportTemplate.name	string maximum-length: 100	create	Name for the ReportTemplate.
reportTemplate.notes	string	optional	Notes about the ReportTemplate.
reportTemplate.options	Object.<string, ?>	always	Specified parameters for the report logic, targeted Assets, and filtering Places and/or regions.
reportTemplate.options.filtering	ReportFilterMode?	optional	The mechanism to use for filtering based on Places and regions.
reportTemplate.options.parameters	Array.<ReportParameter>	optional	A list of parameters to better shape the ReportResult.
reportTemplate.options.places	expression	optional	A targeting expression for limiting results which only include data from Assets interacting with the targeted Places.
reportTemplate.options.regions	Array.<string>	optional	A list of provinces and states, where only Assets within those regions will be included in the ReportResult.
reportTemplate.options.scorecardRules	Object.<string, ?>	always	Rules used to generate ReportScorecard for the ReportResult.
reportTemplate.options.scorecardRules.baseScore	double	optional	Base score for the ReportScorecard.
reportTemplate.options.scorecardRules.parameters	Array.<ReportScorecardParameter>	optional	Infraction parameters used to generate the final ReportScorecard.score.
reportTemplate.options.targets	expression	optional	A targeting expression for including/excluding Assets.
reportTemplate.stroke	string	optional	Text and outline colour in the UI.
reportTemplate.type	ReportType?	create	The kind of logic used to build the report results.
reportTemplate.v	Array.<int32>	optional
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"reportTemplate": {
		"company": number,
		"fill": string,
		"graphic": string,
		"id": number,
		"name": string,
		"notes": string,
		"options": {
			"filtering": string,
			"parameters": [
				{
					"type": string,
					"value": string
				}
			],
			"places": string,
			"regions": [
				string
			],
			"scorecardRules": {
				"baseScore": number,
				"parameters": [
					{
						"condition": string,
						"duration": string,
						"points": number
					}
				]
			},
			"targets": string
		},
		"stroke": string,
		"type": string,
		"v": [
			number
		]
	},
	"reqId": number
}

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reportTemplate	RespIdCompany	An object which contains the "id" and "company" keys when there is no error.
reportTemplate.company	uint64	Identifier of the Company to which this object belongs.
reportTemplate.id	uint64?	Identifier given as input for the command.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reportTemplate": {
		"company": number,
		"id": number
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a reportTemplate object, or it is invalid.
400	3	Not enough keys exist in the reportTemplate object.
400	3	During create: When creating a new ReportTemplate, the name was given, but is blank or null.
400	3	During create: When creating a new ReportTemplate, a company was not given.
400	3	During create: When creating a new ReportTemplate, the type was not given.
400	3	During create: When creating a new ReportTemplate, the type was given, but is invalid.
400	3	During update: When updating a ReportTemplate, the id was invalid.
400	3	During update: When updating a ReportTemplate, the v was not an array, or contained too few numbers.
401	5	You do not have permission to either create a new ReportTemplate.
401	5	You do not have permission to either update ReportTemplates.
400	6	During update: When updating a ReportTemplate, the wrong version key(s) were given.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	52	During update: The ReportTemplate you are trying to update was not found.
409	130	During update: When updating a ReportTemplate, the reportTemplate.company can not be changed.
409	130	During update: When updating a ReportTemplate, the reportTemplate.type can not be changed.

DELETE/reports/templates

Removes the specified ReportTemplate.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reportTemplate	RespDeleted	An object which contains the ReportTemplate's id, owning Company id, and deleted status.
reportTemplate.company	uint64	Identifier of the Company to which this object belongs.
reportTemplate.deleted	boolean	Flag showing if the object is deleted.
reportTemplate.id	uint64?	Identifier given as input for the command.
reportTemplate.v	Array.<uint32>
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reportTemplate": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a reportTemplate object, or it is invalid.
400	3	The reportTemplate object does not contain an id, or it is invalid.
401	5	You do not have permission to delete ReportTemplates.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	52	The ReportTemplate you are trying to delete was not found.

GET/reports/templates/{templateId}?includeDeleted=boolean

Gets details of the specified ReportTemplate.

URL Parameters

Parameter	Type	Required	Description
includeDeleted	boolean	optional	False by default, but when true the command will also return deleted objects.
templateId	uint64	required	Unique identifier of the ReportTemplate.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reportTemplate	ReportTemplate	The requested ReportTemplate.
reportTemplate.company	uint64 see: Company.id	The company to which this report belongs
reportTemplate.fill	colour maximum-length: 22	The fill/background colour of the icon.
reportTemplate.graphic	codified maximum-length: 22	The name of the symbol for this report.
reportTemplate.id	uint64	Unique identifier
reportTemplate.name	string maximum-length: 100	Name of this report.
reportTemplate.notes	string	Notes about this report.
reportTemplate.options	ReportOptions	Specified parameters for the report logic, targeted Assets, and filtering Places.
reportTemplate.options.filtering	ReportFilterMode	The mechanism to use for filtering based on places and regions.
reportTemplate.options.parameters	Array.<ReportParameter>	A list of parameters to better shape the results.
reportTemplate.options.places	expression	A targeting expression for limiting results which only include data from Assets interacting with the targeted Places.
reportTemplate.options.regions	Array.<string>	A list of provinces and states, where only assets within those regions will be included in the results.
reportTemplate.options.scorecardRules	ReportScorecardRules	Rules used to generate scorecard for this report.
reportTemplate.options.scorecardRules.baseScore	double	Base score for the scorecard.
reportTemplate.options.scorecardRules.parameters	Array.<ReportScorecardParameter>	Infraction parameters used to generate the final score
reportTemplate.options.targets	expression	A targeting expression for including/excluding Assets.
reportTemplate.processedUtc	datetime	When the was change procesed.
reportTemplate.stroke	colour maximum-length: 22	Outline and graphic colour.
reportTemplate.type	ReportType	Refers to the type of logic used by this report.
reportTemplate.updated		by: login, from: monster
reportTemplate.v	Array.<uint32>	Object version keys used to validate synchronization for all object properties.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reportTemplate": {
		"company": number,
		"fill": string,
		"graphic": string,
		"id": number,
		"name": string,
		"notes": string,
		"options": {
			"filtering": string,
			"parameters": [
				{
					"type": string,
					"value": string
				}
			],
			"places": string,
			"regions": [
				string
			],
			"scorecardRules": {
				"baseScore": number,
				"parameters": [
					{
						"condition": string,
						"duration": string,
						"points": number
					}
				]
			},
			"targets": string
		},
		"processedUtc": string,
		"stroke": string,
		"type": string,
		"updated": {
		},
		"v": [
			number
		]
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a reportTemplate object, or it is invalid.
400	3	The reportTemplate object does not contain an id, or it is invalid.
401	5	You do not have permission to view ReportTemplates.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	52	The ReportTemplate you are trying to retrieve was not found.

POST/reports/templates/{templateId}

Creates a new or, updates an existing ReportTemplate.

URL Parameters

Parameter	Type	Required	Description
templateId	uint64?	optional	Unique identifier of the ReportTemplate. This value is optional, and ignored by the command.

HTTP Request body description

Property	Type	Required	Description
reportTemplate	Object.<string, ?>	always	A simple object to contain the ReportTemplate parameters.
reportTemplate.company	uint64?	create	The Company to which this ReportTemplate belongs.
reportTemplate.fill	string	optional	Background and fill colour in the UI.
reportTemplate.graphic	string	optional	The name of the symbol shown in the UI.
reportTemplate.id	uint64?	update	The unique identifier of the ReportTemplate you want to update.
reportTemplate.name	string maximum-length: 100	create	Name for the ReportTemplate.
reportTemplate.notes	string	optional	Notes about the ReportTemplate.
reportTemplate.options	Object.<string, ?>	always	Specified parameters for the report logic, targeted Assets, and filtering Places and/or regions.
reportTemplate.options.filtering	ReportFilterMode?	optional	The mechanism to use for filtering based on Places and regions.
reportTemplate.options.parameters	Array.<ReportParameter>	optional	A list of parameters to better shape the ReportResult.
reportTemplate.options.places	expression	optional	A targeting expression for limiting results which only include data from Assets interacting with the targeted Places.
reportTemplate.options.regions	Array.<string>	optional	A list of provinces and states, where only Assets within those regions will be included in the ReportResult.
reportTemplate.options.scorecardRules	Object.<string, ?>	always	Rules used to generate ReportScorecard for the ReportResult.
reportTemplate.options.scorecardRules.baseScore	double	optional	Base score for the ReportScorecard.
reportTemplate.options.scorecardRules.parameters	Array.<ReportScorecardParameter>	optional	Infraction parameters used to generate the final ReportScorecard.score.
reportTemplate.options.targets	expression	optional	A targeting expression for including/excluding Assets.
reportTemplate.stroke	string	optional	Text and outline colour in the UI.
reportTemplate.type	ReportType?	create	The kind of logic used to build the report results.
reportTemplate.v	Array.<int32>	optional
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"reportTemplate": {
		"company": number,
		"fill": string,
		"graphic": string,
		"id": number,
		"name": string,
		"notes": string,
		"options": {
			"filtering": string,
			"parameters": [
				{
					"type": string,
					"value": string
				}
			],
			"places": string,
			"regions": [
				string
			],
			"scorecardRules": {
				"baseScore": number,
				"parameters": [
					{
						"condition": string,
						"duration": string,
						"points": number
					}
				]
			},
			"targets": string
		},
		"stroke": string,
		"type": string,
		"v": [
			number
		]
	},
	"reqId": number
}

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reportTemplate	RespIdCompany	An object which contains the "id" and "company" keys when there is no error.
reportTemplate.company	uint64	Identifier of the Company to which this object belongs.
reportTemplate.id	uint64?	Identifier given as input for the command.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reportTemplate": {
		"company": number,
		"id": number
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a reportTemplate object, or it is invalid.
400	3	Not enough keys exist in the reportTemplate object.
400	3	During create: When creating a new ReportTemplate, the name was given, but is blank or null.
400	3	During create: When creating a new ReportTemplate, a company was not given.
400	3	During create: When creating a new ReportTemplate, the type was not given.
400	3	During create: When creating a new ReportTemplate, the type was given, but is invalid.
400	3	During update: When updating a ReportTemplate, the id was invalid.
400	3	During update: When updating a ReportTemplate, the v was not an array, or contained too few numbers.
401	5	You do not have permission to either create a new ReportTemplate.
401	5	You do not have permission to either update ReportTemplates.
400	6	During update: When updating a ReportTemplate, the wrong version key(s) were given.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	52	During update: The ReportTemplate you are trying to update was not found.
409	130	During update: When updating a ReportTemplate, the reportTemplate.company can not be changed.
409	130	During update: When updating a ReportTemplate, the reportTemplate.type can not be changed.

DELETE/reports/templates/{templateId}

Removes the specified ReportTemplate.

URL Parameters

Parameter	Type	Required	Description
templateId	uint64	required	Unique identifier of the ReportTemplate.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reportTemplate	RespDeleted	An object which contains the ReportTemplate's id, owning Company id, and deleted status.
reportTemplate.company	uint64	Identifier of the Company to which this object belongs.
reportTemplate.deleted	boolean	Flag showing if the object is deleted.
reportTemplate.id	uint64?	Identifier given as input for the command.
reportTemplate.v	Array.<uint32>
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reportTemplate": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a reportTemplate object, or it is invalid.
400	3	The reportTemplate object does not contain an id, or it is invalid.
401	5	You do not have permission to delete ReportTemplates.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	52	The ReportTemplate you are trying to delete was not found.

PATCH/reports/templates/{templateId}/restore

Restores a deleted ReportTemplate to its previous version.

URL Parameters

Parameter	Type	Required	Description
templateId	uint64	required	Unique identifier of the ReportTemplate.

HTTP Request body description

Property	Type	Required	Description
reportTemplate	ParamId	always	An object to contain the "id" of the ReportTemplate.
reportTemplate.id	uint64	always	Identifier given as input for the command.
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"reportTemplate": {
		"id": number
	},
	"reqId": number
}

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reportTemplate	RespDeleted	An object which contains the ReportTemplate's id, owning Company id, and deleted status.
reportTemplate.company	uint64	Identifier of the Company to which this object belongs.
reportTemplate.deleted	boolean	Flag showing if the object is deleted.
reportTemplate.id	uint64?	Identifier given as input for the command.
reportTemplate.v	Array.<uint32>
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reportTemplate": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a reportTemplate object, or it is invalid.
400	3	The reportTemplate object does not contain an id, or it is invalid.
401	5	You do not have permission to delete ReportTemplates.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	52	The ReportTemplate you are trying to restore was not found.
400	53	The ReportTemplate you are trying to restore was not found, but is not deleted.

Self

GET/self

Gets details of the current session (yourself) and User.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
expiry	datetime	The timestamp of when this session expires.
ghostId	string	Your session identifier.
machine	SelfMachine	This Machine's details (if the service is being used by a Machine). If this value is not present, then the session is not a machine account.
machine.company	uint64 see: Company.id	The company to which this user belongs.
machine.enabled	boolean	Indicates whether system access is disable.
machine.formats	Object.<codified, datetimetemplate> maximum-length of values: 20	The format strings defining the preferred way to display ambiguous values.
machine.groups	Array.<UserGroup>	The list of UserGroup to which this User belongs.
machine.insecure	boolean	When true, no access restrictions (machine.secret, machine.referrers, or machine.ipRanges) are enforced.
machine.ipRanges	Array.<ipv4> maximum-length of values: 19	Restrict service access to only the provided IP ranges. Currently we only support IPv4 ranges using CIDR slash-notation.
machine.key	string maximum-length: 50	The unique idenifier used to access the system.
machine.language	codified maximum-length: 5 minimum-length: 2	Preferred region/language for the UI and notifications. Valid formats use <ISO 639-1><dash><ISO 3166-2> such as "fr-CA" or "en-US".
machine.measurements	Object.<codified, SystemsOfUnits>	Preferred way of displaying ambiguous numbers in the context of measurements.
machine.nickname	string maximum-length: 100	Human friendly name for these credentials
machine.notAfter	datetime	An optional timestamp that restricts this machine account from being used after the given date.
machine.notBefore	datetime	An optional timestamp that restricts this machine account from being used before the given date.
machine.notes	string maximum-length: 8000	Notes about this machine.
machine.options	Object.<codified, string> maximum-length of values: 20	Additional options which do not fit in with the formats or measurements preferences.
machine.permissions	Array.<Permission>	Permission rules which override the group rules.
machine.processedUtc	datetime	When the was change procesed.
machine.referrers	Array.<url> maximum-length of values: 254	Optional list of your managed domains from which this machine account can be used.
machine.secret	string maximum-length: 1000	A token used to encode or validate requests.
machine.services	Array.<url> maximum-length of values: 254	List of system service URIs that this machine account is permitted to access.
machine.timezone	codified see: Timezone.code	The service account's local timezone.
machine.updated		by: login, from: monster
machine.v	Array.<uint32>
message	string	An English description of the error.
passwordPolicy	PasswordPolicy	This User's Company.passwordPolicy.
passwordPolicy.expireMode	PasswordExpiryMode	Defines how passwords expire.
passwordPolicy.expireThreshold	byte	The threshold for expiry.
passwordPolicy.includeLetters	boolean	Do passwords require alphabetical characters.
passwordPolicy.includeNumbers	boolean	Do passwords require numeric characters.
passwordPolicy.includeSpecial	boolean	Do passwords require non-alphanumeric characters.
passwordPolicy.includeUpperLower	boolean	Do passwords require upper-case and lower-case letters.
passwordPolicy.minimumLength	byte	The minimum number of characters required.
reqId	int32?	Identifier used by external system to correlate requests to responses.
serverTime	datetime	The UTC date/time of the server hosting the connection.
sessionPolicy	SessionPolicy	This User's Company.sessionPolicy.
sessionPolicy.applications	Array.<string>	The list of applications users are allowed to use to create sessions.
sessionPolicy.expireTimeout	uint16	The lifetime duration of a session in minutes.
sessionPolicy.idleAllowed	boolean	Defines whether a session should be automatically killed when the connection breaks.
sessionPolicy.ipv4Ranges	Array.<ipv4> maximum-length of values: 19	Restrict session creation to only the provided IPv4 ranges (using CIDR slash-notation). Leave blank for Internet access.
sessionPolicy.maxSessions	byte	The maximum number of sessions allowed per user.
sessionPolicy.multiUser	SessionMultiUser	Defines the behaviour of the system when a user creates multiple sessions.
user	SelfUser	This session's User details (if the service is being used by a User). If this value is not present, then the session is not yet authenticated.
user.company	uint64 see: Company.id	The company to which this user belongs.
user.contact	Contact	Associated contact information for this user.
user.contact.addresses	Object.<string, string>	Mailing addresses. Use the object key like a name of the address. Example keys: Home, Work, Park, etc.
user.contact.company	uint64 see: Company.id	The company to which this contact belongs
user.contact.dates	Object.<string, datetime>	Date information. Use the object key like a name of the date. Example keys: Birthday, Started Date, Retired On, etc.
user.contact.emails	Object.<string, email> maximum-length of values: 254	Email addresses. Use the object key like a name of the address. Example keys: Home, Work, Support, Old, etc.
user.contact.id	uint64	Unique identifier of this contact.
user.contact.name	string maximum-length: 100	The person's name
user.contact.notes	string	Notes about this person.
user.contact.options	Object.<string, string>	Uncategorized information. Use the object keys and values however you'd like.
user.contact.otherNames	Object.<string, string> maximum-length of values: 254	A collection of other names this person might go by. Use the object key like a name identifier. Example keys: Initials, Nickname, Maiden Name, etc.
user.contact.phones	Object.<string, phone>	Phone numbers. Use the object key like a name of the phone number. Example keys: Mobile, Fax, Home, Office, etc.
user.contact.pictures	Array.<uint64> for values see: Picture.id	Pictures of this Contact.
user.contact.processedUtc	datetime	When the was change procesed.
user.contact.roles	Array.<string>	A list of roles they play in the Company.
user.contact.updated		by: login, from: monster
user.contact.urls	Object.<string, url> maximum-length of values: 254	Websites and other online resources. Use the object key like a name of the address. Example keys: Downloads, Support, FTP, etc.
user.contact.v	Array.<uint32>	Object version keys used to validate synchronization for all object properties.
user.enabled	boolean	Indicates whether system access is disabled.
user.formats	Object.<codified, datetimetemplate> maximum-length of values: 20	The format strings defining the preferred way to display ambiguous values.
user.groups	Array.<UserGroup>	The list of UserGroups to which this User belongs.
user.language	codified maximum-length: 5 minimum-length: 2	Preferred region/language for the UI and notifications. Valid formats use <ISO 639-1><dash><ISO 3166-2> such as "fr-CA" or "en-US".
user.login	email see: User.login maximum-length: 254 minimum-length: 6	The unique public email address used to access the system.
user.measurements	Object.<codified, SystemsOfUnits>	Preferred way of displaying ambiguous numbers in the context of measurements.
user.nickname	string maximum-length: 100	Human friendly name for these credentials
user.notify	Array.<UserNotifications> maximum-count: 7	Definition of how and when to send alerts to the user.
user.options	Object.<codified, string> maximum-length of values: 20	Additional options which do not fit in with the formats or measurements preferences.
user.passwordExpired	boolean	Indicated whether the credentials have expired according to the company's policy.
user.permissions	Array.<Permission>	Individual permission rules which override the UserGroup rules.
user.processedUtc	datetime	When the was change procesed.
user.timezone	codified see: Timezone.code	The user's local timezone.
user.updated		by: login, from: monster
user.v	Array.<uint32>	Version keys for all parts of your User.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"expiry": string,
	"ghostId": string,
	"machine": {
		"company": number,
		"enabled": boolean,
		"formats": {
			string: string
		},
		"groups": [
			{
				"company": number,
				"id": number,
				"name": string,
				"notes": string,
				"permissions": [
					{
						"company": number,
						"kind": string,
						"labels": [
							string
						],
						"level": string,
						"method": string,
						"type": string
					}
				],
				"processedUtc": string,
				"updated": {
				},
				"v": [
					number
				]
			}
		],
		"insecure": boolean,
		"ipRanges": [
			string
		],
		"key": string,
		"language": string,
		"measurements": {
			string: string
		},
		"nickname": string,
		"notAfter": string,
		"notBefore": string,
		"notes": string,
		"options": {
			string: string
		},
		"permissions": [
			{
				"company": number,
				"kind": string,
				"labels": [
					string
				],
				"level": string,
				"method": string,
				"type": string
			}
		],
		"processedUtc": string,
		"referrers": [
			string
		],
		"secret": string,
		"services": [
			string
		],
		"timezone": string,
		"updated": {
		},
		"v": [
			number
		]
	},
	"message": string,
	"passwordPolicy": {
		"expireMode": string,
		"expireThreshold": number,
		"includeLetters": boolean,
		"includeNumbers": boolean,
		"includeSpecial": boolean,
		"includeUpperLower": boolean,
		"minimumLength": number
	},
	"reqId": number,
	"serverTime": string,
	"sessionPolicy": {
		"applications": [
			string
		],
		"expireTimeout": number,
		"idleAllowed": boolean,
		"ipv4Ranges": [
			string
		],
		"maxSessions": number,
		"multiUser": string
	},
	"user": {
		"company": number,
		"contact": {
			"addresses": {
				string: string
			},
			"company": number,
			"dates": {
				string: string
			},
			"emails": {
				string: string
			},
			"id": number,
			"name": string,
			"notes": string,
			"options": {
				string: string
			},
			"otherNames": {
				string: string
			},
			"phones": {
				string: number
			},
			"pictures": [
				number
			],
			"processedUtc": string,
			"roles": [
				string
			],
			"updated": {
			},
			"urls": {
				string: string
			},
			"v": [
				number
			]
		},
		"enabled": boolean,
		"formats": {
			string: string
		},
		"groups": [
			{
				"company": number,
				"id": number,
				"name": string,
				"notes": string,
				"permissions": [
					{
						"company": number,
						"kind": string,
						"labels": [
							string
						],
						"level": string,
						"method": string,
						"type": string
					}
				],
				"processedUtc": string,
				"updated": {
				},
				"v": [
					number
				]
			}
		],
		"language": string,
		"login": string,
		"measurements": {
			string: string
		},
		"nickname": string,
		"notify": [
			{
				"email": string,
				"enabled": boolean,
				"end": string,
				"name": string,
				"offline": [
					string
				],
				"online": [
					string
				],
				"sms": number,
				"start": string,
				"weekdays": [
					boolean
				]
			}
		],
		"options": {
			string: string
		},
		"passwordExpired": boolean,
		"permissions": [
			{
				"company": number,
				"kind": string,
				"labels": [
					string
				],
				"level": string,
				"method": string,
				"type": string
			}
		],
		"processedUtc": string,
		"timezone": string,
		"updated": {
		},
		"v": [
			number
		]
	}
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
404	28	The session is valid, but the CompanyPolicies is missing. If you receive this error, please contact technical support.
404	54	The session is valid, but the User (or Machine) is missing. If you receive this error, please contact technical support.

GET/self/assume?ghostId={string}

Light-weight command to return your current session state.

URL Parameters

Parameter	Type	Required	Description
ghostId	string	required	Session identifier

Response description

Property	Type	Description
company	uint64?	The User's Company.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
expiry	datetime	The timestamp of when this session expires.
ghostId	string	Your session identifier.
login	string	The User's login.
message	string	An English description of the error.
passwordExpired	boolean	When true, the User's password must be changed before action commands will be processed.
reqId	int32?	Identifier used by external system to correlate requests to responses.
serverTime	datetime	The UTC date/time of the server hosting the connection.
status	SessionStatus	Your current session state.

Response structure

{
	"company": number,
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"expiry": string,
	"ghostId": string,
	"login": string,
	"message": string,
	"passwordExpired": boolean,
	"reqId": number,
	"serverTime": string,
	"status": string
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	Your session status could not be determined. If you receive this error, please contact technical support.

POST/self/contact

Allows a User to update their own Contact. If your User has no associated Contact, you will receive a Contact not found error.

HTTP Request body description

Property	Type	Required	Description
addresses	Object.<string, string>	optional	Mailing addresses Use the object key like a name of the address. Example keys: Home, Work, Park, etc.
dates	Object.<string, datetime>	optional	Date information Use the object key like a name of the date. Example keys: Birthday, Started Date, Retired On, etc.
emails	Object.<string, email> maximum-length of values: 254	optional	Email addresses Use the object key like a name of the address. Example keys: Home, Work, Support, Old, etc.
name	string	optional	Name for yourself.
notes	string	optional	Notes for yourself.
options	Object.<string, string>	optional	Uncategorized information Use the object keys and values however you'd like.
otherNames	Object.<string, string> maximum-length of values: 254	optional	A collection of other names this person might go by. Use the object key like a name identifier. Example keys: Initials, Nickname, Maiden Name, etc.
phones	Object.<string, phone?>	optional	Phone numbers. Use the object key like a name of the phone number. Example keys: Mobile, Fax, Home, Office, etc.
pictures	Array.<uint64> for values see: Picture.id	optional	Pictures of yourself.
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.
roles	Array.<codified>	optional	A list of roles they play in the Company.
urls	Object.<string, url> maximum-length of values: 254	optional	Websites and other online resources Use the object key like a name of the address. Example keys: Downloads, Support, FTP, etc.

HTTP Request body structure

{
	"addresses": {
		string: string
	},
	"dates": {
		string: string
	},
	"emails": {
		string: string
	},
	"name": string,
	"notes": string,
	"options": {
		string: string
	},
	"otherNames": {
		string: string
	},
	"phones": {
		string: number
	},
	"pictures": [
		number
	],
	"reqId": number,
	"roles": [
		string
	],
	"urls": {
		string: string
	}
}

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a contact object, or it is invalid.
400	3	The contact object does not contain an id, or it is invalid.
400	3	No valid changes would be performed.
400	3	The v was not an array, or contained too few numbers.
400	3	One of the otherNames keys or values is invalid. Returns an ErrorDetailInput as the `errorDetails`.
400	3	One of the emails keys or values is invalid. Returns an ErrorDetailInput as the `errorDetails`.
400	3	One of the phones keys or values is invalid. Returns an ErrorDetailInput as the `errorDetails`.
400	3	One of the addresses keys or values is invalid. Returns an ErrorDetailInput as the `errorDetails`.
400	3	One of the urls keys or values is invalid. Returns an ErrorDetailInput as the `errorDetails`.
400	3	One of the dates keys or values is invalid. Returns an ErrorDetailInput as the `errorDetails`.
400	3	One of the options keys or values is invalid. Returns an ErrorDetailInput as the `errorDetails`.
400	3	One of the pictures values is invalid. Returns an ErrorDetailInput as the `errorDetails`.
400	6	The wrong version key(s) were given.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	31	Your User does not have a Contact defined.
404	54	Your User was not found. If the problem persists, please contact support.
404	69	One or more of the pictures identifiers given was not found.
401	85	Your User is disabled. If the problem persists, please contact support.

POST/self/login

Creates a new session and allows access to authorized services.

HTTP Request body description

Property	Type	Required	Description
password	string	always	User's password.
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.
userAgent	string	optional	Application name. This should match the allowed applications from user's company's SessionPolicy.applications.
username	string	always	User's email address.

HTTP Request body structure

{
	"password": string,
	"reqId": number,
	"userAgent": string,
	"username": string
}

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The username is not a valid email address.
400	3	The password is blank or not given.
401	11	The username and/or password are not correct.
403	12	The client application is not allowed based on the Company's policy.
403	13	The client IP address is not allowed based on the Company's policy.
401	14	The User's Company's policy does not allow for multiple sessions per User, and there is already another active session.
404	28	The User's Company cannot be found. If you encounter this error, please contact support.
503	73	There are too many concurrent sessions for this User.
401	85	The credentials are correct, but the User is not allowed to log in.

GET/self/login?username={string}&password={string}&userAgent=string

Creates a new session and allows access to authorized services.

URL Parameters

Parameter	Type	Required	Description
password	string	required	Your password (keep it secret, keep it safe)
userAgent	string	optional	Identification of the software used to log in
username	string	required	Your login (an email address)

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The username is not a valid email address.
400	3	The password is blank or not given.
401	11	The username and/or password are not correct.
403	12	The client application is not allowed based on the Company's policy.
403	13	The client IP address is not allowed based on the Company's policy.
401	14	The User's Company's policy does not allow for multiple sessions per User, and there is already another active session.
404	28	The User's Company cannot be found. If you encounter this error, please contact support.
503	73	There are too many concurrent sessions for this User.
401	85	The credentials are correct, but the User is not allowed to log in.

GET/self/logout

Ends your session.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
expiry	datetime	The timestamp from when you session expired.
ghostId	string	Your old, no longer valid, session identifier.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"expiry": string,
	"ghostId": string,
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.

POST/self/logout

Ends your session.

HTTP Request body description

Property	Type	Required	Description
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"reqId": number
}

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
expiry	datetime	The timestamp from when you session expired.
ghostId	string	Your old, no longer valid, session identifier.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"expiry": string,
	"ghostId": string,
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.

POST/self/password

Allows a session User to change their own password.

HTTP Request body description

Property	Type	Required	Description
current	string	always	Your current password, as verification that you are the proper account owner.
password	string	always	Your new password must conform to your company's password policy.
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"current": string,
	"password": string,
	"reqId": number
}

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
expires	datetime	Specific date/time of when the password will expire.
message	string	An English description of the error.
passwordPolicy	PasswordPolicy	Your Company's password policy.
passwordPolicy.expireMode	PasswordExpiryMode	Defines how passwords expire.
passwordPolicy.expireThreshold	byte	The threshold for expiry.
passwordPolicy.includeLetters	boolean	Do passwords require alphabetical characters.
passwordPolicy.includeNumbers	boolean	Do passwords require numeric characters.
passwordPolicy.includeSpecial	boolean	Do passwords require non-alphanumeric characters.
passwordPolicy.includeUpperLower	boolean	Do passwords require upper-case and lower-case letters.
passwordPolicy.minimumLength	byte	The minimum number of characters required.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"expires": string,
	"message": string,
	"passwordPolicy": {
		"expireMode": string,
		"expireThreshold": number,
		"includeLetters": boolean,
		"includeNumbers": boolean,
		"includeSpecial": boolean,
		"includeUpperLower": boolean,
		"minimumLength": number
	},
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The current password is blank or not given.
400	3	The new password is blank or not given.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
401	11	The current password is not correct.
401	15	The new password is not strong enough to comply with the PasswordPolicy requirements.
400	17	The current password cannot be the same as the new password.
404	28	Your CompanyPolicies is missing. If the problem persists, please contact support.
404	28	Your Company's PasswordPolicy is missing. If the problem persists, please contact support.
404	54	The session User was not found. If the problem persists, please contact support.
401	85	The session User is disabled. If the problem persists, please contact support.

POST/self/preferences

Allows a session User to change their own preferences.

HTTP Request body description

Property	Type	Required	Description
formats	Object.<string, string>	optional	Formatting help for dates, times, numbers.
language	string	optional	Preferred region/language for the UI and notifications. Valid formats use <ISO 639-1><dash><ISO 3166-2> such as "fr-CA" or "en-US".
measurements	Object.<string, SystemsOfUnits?>	optional	Preferred way of displaying ambiguous numbers in the context of measurements.
notify	Array.<UserNotifications>	optional	List of UserNotifications preferences. Please note that active times cannot overlap.
options	Object.<string, string>	optional	Additional options which do not fit in with the formats or measurements preferences. If a value of null is given, the option is removed. To keep the option, you can use a blank string. For convenience, if the value of an option is given as JSON (instead of a string), they are automatically serialized with no white-space.
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.
timezone	codified see: Timezone.code	optional	Your local Timezone used to calculate times.

HTTP Request body structure

{
	"formats": {
		string: string
	},
	"language": string,
	"measurements": {
		string: string
	},
	"notify": [
		{
			"email": string,
			"enabled": boolean,
			"end": string,
			"name": string,
			"offline": [
				string
			],
			"online": [
				string
			],
			"sms": number,
			"start": string,
			"weekdays": [
				boolean
			]
		}
	],
	"options": {
		string: string
	},
	"reqId": number,
	"timezone": string
}

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	No valid changes would be performed.
400	3	The given language was not a valid region.
400	3	One of the keys given in the formats dictionary was blank.
400	3	One of the keys given in the measurements dictionary was blank.
400	3	One of the keys given in the options dictionary was blank.
400	3	One of the given notify values was null, had a blank name property, or was not a valid object.
400	3	One of the measurements could not be parsed. Returns an ErrorDetailInput as the `errorDetails`.
400	3	One of the notify could not be parsed. Returns an ErrorDetailInput as the `errorDetails`.
400	3	One of the notify did not contain a name. Returns an ErrorDetailInput as the `errorDetails`.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	54	Your User was not found. If the problem persists, please contact support.
404	62	The given timezone could not be found. Returns an ErrorDetailInput as the `errorDetails`.
401	85	Your User is disabled. If the problem persists, please contact support.

POST/self/recover

Begins the password recovery process. If successful, will send an email to you with a code used to create a temporary password.

HTTP Request body description

Property	Type	Required	Description
key	string	optional	Optional key in the User's Contact.emails address list to use for recovery.
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.
username	string	always	User's email address.

HTTP Request body structure

{
	"key": string,
	"reqId": number,
	"username": string
}

Response description

Property	Type	Description
email	string	User's email address.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
name	string	User's nickname or Contact name.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"email": string,
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"name": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	There was a communication error. If the problem persists, please contact support. If you receive this error, please contact technical support.
400	3	The username is not a valid email address.
404	28	The User's Company or its branch could not be found.
404	31	When specifying the email address to key, and the user's contact is not found.
404	54	The User was not found.
401	85	The User is not allowed to log in.
409	130	When specifying the email address to key, and the user's contact does not have a value for that key.

GET/self/recover/{guid}?length=number

Completes the password recovery process. If successful, will create a new password for your user and mark it as expired so you must change your password after using it to login the first time.

URL Parameters

Parameter	Type	Required	Description
guid	string	required	Unique identifier sent to you from the beginning of the process
length	uint64?	optional	Optionally supplied randomized password length. If the provided length is smaller than the company PasswordPolicy dictates, then the company policy length is used.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
password	string	User's temporary password.
reqId	int32?	Identifier used by external system to correlate requests to responses.
username	string	User's email address.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"password": string,
	"reqId": number,
	"username": string
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	There was a communication error. If the problem persists, please contact support. If you receive this error, please contact technical support.
400	3	The guid is invalid or blank.
400	3	The requested temporary password length is too short.
404	54	The User was not found.
401	85	The User is not allowed to log in.

GET/self/recover?username={string}&key=string

Begins the password recovery process. If successful, will send an email to you with a code used to create a temporary password.

URL Parameters

Parameter	Type	Required	Description
key	string	optional	Optionally specified email address name from your Contact information
username	string	required	User login (an email address)

Response description

Property	Type	Description
email	string	User's email address.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
name	string	User's nickname or Contact name.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"email": string,
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"name": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	There was a communication error. If the problem persists, please contact support. If you receive this error, please contact technical support.
400	3	The username is not a valid email address.
404	28	The User's Company or its branch could not be found.
404	31	When specifying the email address to key, and the user's contact is not found.
404	54	The User was not found.
401	85	The User is not allowed to log in.
409	130	When specifying the email address to key, and the user's contact does not have a value for that key.

GET/self/sessions

Gets the list of your own sessions.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.
sessions	Array.<SessionFull>	The list of requested SessionFull.
user	RespLoginCompany	An object to contain the "login" of the User to which the array of SessionFulls belong.
user.company	uint64	Identifier of the Company to which the User belongs.
user.login	string	The User's login.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number,
	"sessions": [
		{
			"active": boolean,
			"company": number,
			"created": string,
			"expiry": string,
			"handle": string,
			"ipAddress": string,
			"lastActivity": string,
			"lastCommand": string,
			"login": string,
			"sockets": number,
			"status": string,
			"userAgent": string
		}
	],
	"user": {
		"company": number,
		"login": string
	}
}

Possible exceptions

HTTP Status	Error Code	Description
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.

Users and Groups

GET/companies/{companyId}/contacts?includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

Gets the list of Contacts for the specified Company.

URL Parameters

Parameter	Type	Required	Description
companyId	uint64	required	Unique identifier of the Company.
highest	uint64?	optional	When using , sets the largest valued id objects to retrieve.
includeArchive	boolean	optional	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	False by default, but when true, the command will also return deleted objects.
limit	uint16?	optional	When using , sets the maximum number of objects retrieved from the archive.
lowest	uint64?	optional	When using , sets the smallest valued id objects to retrieve.

Response description

Property	Type	Description
company	RespId	An object to contain the "id" of the Company to which the array of Contacts belong.
company.id	uint64?	Identifier given as input for the command.
contacts	Array.<Contact>	The list of requested Contacts.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"company": {
		"id": number
	},
	"contacts": [
		{
			"addresses": {
				string: string
			},
			"company": number,
			"dates": {
				string: string
			},
			"emails": {
				string: string
			},
			"id": number,
			"name": string,
			"notes": string,
			"options": {
				string: string
			},
			"otherNames": {
				string: string
			},
			"phones": {
				string: number
			},
			"pictures": [
				number
			],
			"processedUtc": string,
			"roles": [
				string
			],
			"updated": {
			},
			"urls": {
				string: string
			},
			"v": [
				number
			]
		}
	],
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
401	5	You do not have permission to view Contacts for this Company.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company was not found by its unique identifier.

GET/companies/{companyId}/machines?includeDeleted=boolean&includeArchive=boolean&limit=number&first=string&last=string

Gets the list of Machines for the specified Company.

URL Parameters

Parameter	Type	Required	Description
companyId	uint64	required	Unique identifier of the Company.
first	string	optional	When using , sets the first alphabetic SelfMachine.key when listing from the database.
includeArchive	boolean	optional	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	False by default, but when true, the command will also return deleted objects.
last	string	optional	When using , sets the last alphabetic SelfMachine.key when listing from the database.
limit	uint16?	optional	When using , sets the maximum number of objects retrieved from the archive.

Response description

Property	Type	Description
company	RespId	An object to contain the "id" of the Company to which the array of Machines belong.
company.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
machines	Array.<Machine>	The list requested of Machines.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"machines": [
		{
			"company": number,
			"enabled": boolean,
			"formats": {
				string: string
			},
			"groups": [
				number
			],
			"insecure": boolean,
			"ipRanges": [
				string
			],
			"key": string,
			"language": string,
			"measurements": {
				string: string
			},
			"nickname": string,
			"notAfter": string,
			"notBefore": string,
			"notes": string,
			"options": {
				string: string
			},
			"permissions": [
				{
					"company": number,
					"kind": string,
					"labels": [
						string
					],
					"level": string,
					"method": string,
					"type": string
				}
			],
			"processedUtc": string,
			"referrers": [
				string
			],
			"secret": string,
			"services": [
				string
			],
			"timezone": string,
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
401	5	You do not have permission to view this Company's Machines.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.

GET/companies/{companyId}/users?includeDeleted=boolean&includeArchive=boolean&limit=number&first=string&last=string

Gets the list of Users for the specified Company.

URL Parameters

Parameter	Type	Required	Description
companyId	uint64	required	Unique identifier of the Company.
first	string	optional	When using , sets the first alphabetic User.login when listing from the database.
includeArchive	boolean	optional	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	False by default, but when true, the command will also return deleted objects.
last	string	optional	When using , sets the last alphabetic User.login when listing from the database.
limit	uint16?	optional	When using , sets the maximum number of objects retrieved from the archive.

Response description

Property	Type	Description
company	RespId	An object to contain the "id" of the Company to which the array of Users belong.
company.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.
users	Array.<User>	The list of requested Users.

Response structure

{
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number,
	"users": [
		{
			"company": number,
			"contact": number,
			"enabled": boolean,
			"formats": {
				string: string
			},
			"groups": [
				number
			],
			"language": string,
			"login": string,
			"measurements": {
				string: string
			},
			"nickname": string,
			"notify": [
				{
					"email": string,
					"enabled": boolean,
					"end": string,
					"name": string,
					"offline": [
						string
					],
					"online": [
						string
					],
					"sms": number,
					"start": string,
					"weekdays": [
						boolean
					]
				}
			],
			"options": {
				string: string
			},
			"passwordExpired": boolean,
			"permissions": [
				{
					"company": number,
					"kind": string,
					"labels": [
						string
					],
					"level": string,
					"method": string,
					"type": string
				}
			],
			"processedUtc": string,
			"timezone": string,
			"updated": {
			},
			"v": [
				number
			]
		}
	]
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
401	5	You do not have permission to view this Company's Users.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.

GET/companies/{companyId}/users/advanceds?includeDeleted=boolean&includeArchive=boolean&limit=number&first=string&last=string

Gets the list of Users for the specified Company.

URL Parameters

Parameter	Type	Required	Description
companyId	uint64	required	Unique identifier of the Company.
first	string	optional	When using , sets the first alphabetic User.login when listing from the database.
includeArchive	boolean	optional	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	False by default, but when true, the command will also return deleted objects.
last	string	optional	When using , sets the last alphabetic User.login when listing from the database.
limit	uint16?	optional	When using , sets the maximum number of objects retrieved from the archive.

Response description

Property	Type	Description
company	RespId	An object to contain the "id" of the Company to which the array of Users belong.
company.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.
userAdvanceds	Array.<UserAdvanced>	The list of requested Users.

Response structure

{
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number,
	"userAdvanceds": [
		{
			"company": number,
			"groups": [
				number
			],
			"login": string,
			"permissions": [
				{
					"company": number,
					"kind": string,
					"labels": [
						string
					],
					"level": string,
					"method": string,
					"type": string
				}
			],
			"processedUtc": string,
			"updated": {
			},
			"v": [
				number
			]
		}
	]
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
401	5	You do not have permission to view this Company's Users.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.

GET/companies/{companyId}/users/generals?includeDeleted=boolean&includeArchive=boolean&limit=number&first=string&last=string

Gets the list of Users for the specified Company.

URL Parameters

Parameter	Type	Required	Description
companyId	uint64	required	Unique identifier of the Company.
first	string	optional	When using , sets the first alphabetic User.login when listing from the database.
includeArchive	boolean	optional	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	False by default, but when true, the command will also return deleted objects.
last	string	optional	When using , sets the last alphabetic User.login when listing from the database.
limit	uint16?	optional	When using , sets the maximum number of objects retrieved from the archive.

Response description

Property	Type	Description
company	RespId	An object to contain the "id" of the Company to which the array of Users belong.
company.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.
userGenerals	Array.<UserGeneral>	The list of requested Users.

Response structure

{
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number,
	"userGenerals": [
		{
			"company": number,
			"contact": number,
			"enabled": boolean,
			"formats": {
				string: string
			},
			"language": string,
			"login": string,
			"measurements": {
				string: string
			},
			"nickname": string,
			"notify": [
				{
					"email": string,
					"enabled": boolean,
					"end": string,
					"name": string,
					"offline": [
						string
					],
					"online": [
						string
					],
					"sms": number,
					"start": string,
					"weekdays": [
						boolean
					]
				}
			],
			"options": {
				string: string
			},
			"passwordExpired": boolean,
			"processedUtc": string,
			"timezone": string,
			"updated": {
			},
			"v": [
				number
			]
		}
	]
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
401	5	You do not have permission to view this Company's Users.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.

GET/companies/{companyId}/users/groups?includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

Gets the list of UserGroups for the specified Company.

URL Parameters

Parameter	Type	Required	Description
companyId	uint64	required	Unique identifier of the Company.
highest	uint64?	optional	When using , sets the largest valued id objects to retrieve.
includeArchive	boolean	optional	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	False by default, but when true, the command will also return deleted objects.
limit	uint16?	optional	When using , sets the maximum number of objects retrieved from the archive.
lowest	uint64?	optional	When using , sets the smallest valued id objects to retrieve.

Response description

Property	Type	Description
company	RespId	An object to contain the "id" of the Company to which the array of contacts belong.
company.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.
userGroups	Array.<UserGroup>	The requested list of UserGroups.

Response structure

{
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number,
	"userGroups": [
		{
			"company": number,
			"id": number,
			"name": string,
			"notes": string,
			"permissions": [
				{
					"company": number,
					"kind": string,
					"labels": [
						string
					],
					"level": string,
					"method": string,
					"type": string
				}
			],
			"processedUtc": string,
			"updated": {
			},
			"v": [
				number
			]
		}
	]
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
401	5	You do not have permission to view this Company's UserGroups.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.

GET/companies/{companyId}/users/sessions

Gets the list of SessionFull for the specified Company.

URL Parameters

Parameter	Type	Required	Description
companyId	uint64	required	Unique identifier of the Company.

Response description

Property	Type	Description
company	RespId	An object to contain the "id" of the Company to which the array of SessionFulls belong.
company.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.
sessions	Array.<SessionFull>	The list of requested SessionFull.

Response structure

{
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number,
	"sessions": [
		{
			"active": boolean,
			"company": number,
			"created": string,
			"expiry": string,
			"handle": string,
			"ipAddress": string,
			"lastActivity": string,
			"lastCommand": string,
			"login": string,
			"sockets": number,
			"status": string,
			"userAgent": string
		}
	]
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
401	5	You do not have permission to view SessionFulls for this Company.
401	5	You do not have permission to view Users for this Company.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company was not found by its unique identifier.

GET/contacts?includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

This request is an alias of /companies/{your-company-id}/contacts/.

URL Parameters

Parameter	Type	Required	Default	Description
highest	uint64	optional		When using , sets the maximum id when listing from the database.
includeArchive	boolean	optional	`false`	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	`false`	False by default, but when true the command will also return deleted objects.
limit	uint16	optional		When using , sets the maximum number of objects in this response.
lowest	uint64	optional		When using , sets the minimum id when listing from the database.
your-company-id	uint64	aliased	`{your-company-id}`	Your own Company's identifier.

PATCH/contacts

Creates a new or updates an existing Contact.

HTTP Request body description

Property	Type	Required	Description
contact	Object.<string, ?>	always	A simple object to contain the Contact parameters.
contact.addresses	Object.<string, string>	optional	Mailing addresses Use the object key like a name of the address. Example keys: Home, Work, Park, etc.
contact.company	uint64?	create	The Company to which this Contact belongs. After creation, this value is read-only.
contact.dates	Object.<string, datetime>	optional	Date information Use the object key like a name of the date. Example keys: Birthday, Started Date, Retired On, etc.
contact.emails	Object.<string, email> maximum-length of values: 254	optional	Email addresses Use the object key like a name of the address. Example keys: Home, Work, Support, Old, etc.
contact.id	uint64?	update	The unique identifier of the Contact you want to update.
contact.name	string maximum-length: 100	optional	Name for the Contact.
contact.notes	string	optional	Notes for the Contact.
contact.options	Object.<string, string>	optional	Uncategorized information Use the object keys and values however you'd like.
contact.otherNames	Object.<string, string> maximum-length of values: 254	optional	A collection of other names this person might go by. Use the object key like a name identifier. Example keys: Initials, Nickname, Maiden Name, etc.
contact.phones	Object.<string, phone?>	optional	Phone numbers. Use the object key like a name of the phone number. Example keys: Mobile, Fax, Home, Office, etc.
contact.pictures	Array.<uint64> for values see: Picture.id	optional	Pictures of this Contact.
contact.roles	Array.<codified>	optional	A list of roles they play in the Company.
contact.urls	Object.<string, url> maximum-length of values: 254	optional	Websites and other online resources Use the object key like a name of the address. Example keys: Downloads, Support, FTP, etc.
contact.v	Array.<int32>	optional
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"contact": {
		"addresses": {
			string: string
		},
		"company": number,
		"dates": {
			string: string
		},
		"emails": {
			string: string
		},
		"id": number,
		"name": string,
		"notes": string,
		"options": {
			string: string
		},
		"otherNames": {
			string: string
		},
		"phones": {
			string: number
		},
		"pictures": [
			number
		],
		"roles": [
			string
		],
		"urls": {
			string: string
		},
		"v": [
			number
		]
	},
	"reqId": number
}

Response description

Property	Type	Description
contact	RespIdCompany	An object which contains the "id" and "company" keys when there is no error.
contact.company	uint64	Identifier of the Company to which this object belongs.
contact.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"contact": {
		"company": number,
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a contact object, or it is invalid.
400	3	Not enough keys exist in the contact object.
400	3	During create: When creating a new Contact, a company was not given.
400	3	During create: When creating a new Contact, a name was not given, or it is invalid.
400	3	During update: When updating a Contact, the id was invalid.
400	3	During update: When updating a Contact, the name was given as blank.
400	3	During update: When updating a Contact, the v was not an array, or contained too few numbers.
400	3	One of the contact.otherNames keys or values is invalid. Returns an ErrorDetailInput as the `errorDetails`.
400	3	One of the contact.emails keys or values is invalid. Returns an ErrorDetailInput as the `errorDetails`.
400	3	One of the contact.phones keys or values is invalid. Returns an ErrorDetailInput as the `errorDetails`.
400	3	One of the contact.addresses keys or values is invalid. Returns an ErrorDetailInput as the `errorDetails`.
400	3	One of the contact.urls keys or values is invalid. Returns an ErrorDetailInput as the `errorDetails`.
400	3	One of the contact.dates keys or values is invalid. Returns an ErrorDetailInput as the `errorDetails`.
400	3	One of the contact.options keys or values is invalid. Returns an ErrorDetailInput as the `errorDetails`.
400	3	One of the contact.pictures values is invalid. Returns an ErrorDetailInput as the `errorDetails`.
401	5	You do not have permission to create a new Contact.
401	5	You do not have permission to update this Contact.
400	6	During update: When updating a Contact, an incorrect v value was given as input.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	31	During update: The Contact was not found by its unique identifier.
404	69	One of the contact.pictures given as input in the Pictures array was not found. Returns an ErrorDetailBadIds as the `errorDetails`.
409	130	During update: When updating a Contact, the company was provided as a different value.

DELETE/contacts

Deletes an existing Contact.

Response description

Property	Type	Description
contact	RespDeleted	An object which contains the Contact's id, owning Company id, and deleted status.
contact.company	uint64	Identifier of the Company to which this object belongs.
contact.deleted	boolean	Flag showing if the object is deleted.
contact.id	uint64?	Identifier given as input for the command.
contact.v	Array.<uint32>
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"contact": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a contact object, or it is invalid.
400	3	The contact object does not contain an id, or it is invalid.
401	5	You do not have permission to delete this Contact.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	31	The Contact was not found by its unique identifier.
409	121	This Contact is still being used by a Asset or User. Returns an ErrorDetailContactInUse as the `errorDetails`.

GET/contacts/{contactId}?includeDeleted=boolean

Gets details of the specified Contact.

URL Parameters

Parameter	Type	Required	Description
contactId	uint64	required	Unique identifier of the Contact.
includeDeleted	boolean	optional	False by default, but when true the command will also return deleted objects.

Response description

Property	Type	Description
contact	Contact	The requested Contact.
contact.addresses	Object.<string, string>	Mailing addresses. Use the object key like a name of the address. Example keys: Home, Work, Park, etc.
contact.company	uint64 see: Company.id	The company to which this contact belongs
contact.dates	Object.<string, datetime>	Date information. Use the object key like a name of the date. Example keys: Birthday, Started Date, Retired On, etc.
contact.emails	Object.<string, email> maximum-length of values: 254	Email addresses. Use the object key like a name of the address. Example keys: Home, Work, Support, Old, etc.
contact.id	uint64	Unique identifier of this contact.
contact.name	string maximum-length: 100	The person's name
contact.notes	string	Notes about this person.
contact.options	Object.<string, string>	Uncategorized information. Use the object keys and values however you'd like.
contact.otherNames	Object.<string, string> maximum-length of values: 254	A collection of other names this person might go by. Use the object key like a name identifier. Example keys: Initials, Nickname, Maiden Name, etc.
contact.phones	Object.<string, phone>	Phone numbers. Use the object key like a name of the phone number. Example keys: Mobile, Fax, Home, Office, etc.
contact.pictures	Array.<uint64> for values see: Picture.id	Pictures of this Contact.
contact.processedUtc	datetime	When the was change procesed.
contact.roles	Array.<string>	A list of roles they play in the Company.
contact.updated		by: login, from: monster
contact.urls	Object.<string, url> maximum-length of values: 254	Websites and other online resources. Use the object key like a name of the address. Example keys: Downloads, Support, FTP, etc.
contact.v	Array.<uint32>	Object version keys used to validate synchronization for all object properties.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"contact": {
		"addresses": {
			string: string
		},
		"company": number,
		"dates": {
			string: string
		},
		"emails": {
			string: string
		},
		"id": number,
		"name": string,
		"notes": string,
		"options": {
			string: string
		},
		"otherNames": {
			string: string
		},
		"phones": {
			string: number
		},
		"pictures": [
			number
		],
		"processedUtc": string,
		"roles": [
			string
		],
		"updated": {
		},
		"urls": {
			string: string
		},
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a contact object, or it is invalid.
400	3	The contact object does not contain an id, or it is invalid.
401	5	You do not have permission to view this Contact.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	31	The Contact was not found by its unique identifier.

POST/contacts/{contactId}

Creates a new or updates an existing Contact.

URL Parameters

Parameter	Type	Required	Description
contactId	uint64?	optional	Unique identifier of the Contact. This value is optional, and ignored by the command.

HTTP Request body description

Property	Type	Required	Description
contact	Object.<string, ?>	always	A simple object to contain the Contact parameters.
contact.addresses	Object.<string, string>	optional	Mailing addresses Use the object key like a name of the address. Example keys: Home, Work, Park, etc.
contact.company	uint64?	create	The Company to which this Contact belongs. After creation, this value is read-only.
contact.dates	Object.<string, datetime>	optional	Date information Use the object key like a name of the date. Example keys: Birthday, Started Date, Retired On, etc.
contact.emails	Object.<string, email> maximum-length of values: 254	optional	Email addresses Use the object key like a name of the address. Example keys: Home, Work, Support, Old, etc.
contact.id	uint64?	update	The unique identifier of the Contact you want to update.
contact.name	string maximum-length: 100	optional	Name for the Contact.
contact.notes	string	optional	Notes for the Contact.
contact.options	Object.<string, string>	optional	Uncategorized information Use the object keys and values however you'd like.
contact.otherNames	Object.<string, string> maximum-length of values: 254	optional	A collection of other names this person might go by. Use the object key like a name identifier. Example keys: Initials, Nickname, Maiden Name, etc.
contact.phones	Object.<string, phone?>	optional	Phone numbers. Use the object key like a name of the phone number. Example keys: Mobile, Fax, Home, Office, etc.
contact.pictures	Array.<uint64> for values see: Picture.id	optional	Pictures of this Contact.
contact.roles	Array.<codified>	optional	A list of roles they play in the Company.
contact.urls	Object.<string, url> maximum-length of values: 254	optional	Websites and other online resources Use the object key like a name of the address. Example keys: Downloads, Support, FTP, etc.
contact.v	Array.<int32>	optional
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"contact": {
		"addresses": {
			string: string
		},
		"company": number,
		"dates": {
			string: string
		},
		"emails": {
			string: string
		},
		"id": number,
		"name": string,
		"notes": string,
		"options": {
			string: string
		},
		"otherNames": {
			string: string
		},
		"phones": {
			string: number
		},
		"pictures": [
			number
		],
		"roles": [
			string
		],
		"urls": {
			string: string
		},
		"v": [
			number
		]
	},
	"reqId": number
}

Response description

Property	Type	Description
contact	RespIdCompany	An object which contains the "id" and "company" keys when there is no error.
contact.company	uint64	Identifier of the Company to which this object belongs.
contact.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"contact": {
		"company": number,
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a contact object, or it is invalid.
400	3	Not enough keys exist in the contact object.
400	3	During create: When creating a new Contact, a company was not given.
400	3	During create: When creating a new Contact, a name was not given, or it is invalid.
400	3	During update: When updating a Contact, the id was invalid.
400	3	During update: When updating a Contact, the name was given as blank.
400	3	During update: When updating a Contact, the v was not an array, or contained too few numbers.
400	3	One of the contact.otherNames keys or values is invalid. Returns an ErrorDetailInput as the `errorDetails`.
400	3	One of the contact.emails keys or values is invalid. Returns an ErrorDetailInput as the `errorDetails`.
400	3	One of the contact.phones keys or values is invalid. Returns an ErrorDetailInput as the `errorDetails`.
400	3	One of the contact.addresses keys or values is invalid. Returns an ErrorDetailInput as the `errorDetails`.
400	3	One of the contact.urls keys or values is invalid. Returns an ErrorDetailInput as the `errorDetails`.
400	3	One of the contact.dates keys or values is invalid. Returns an ErrorDetailInput as the `errorDetails`.
400	3	One of the contact.options keys or values is invalid. Returns an ErrorDetailInput as the `errorDetails`.
400	3	One of the contact.pictures values is invalid. Returns an ErrorDetailInput as the `errorDetails`.
401	5	You do not have permission to create a new Contact.
401	5	You do not have permission to update this Contact.
400	6	During update: When updating a Contact, an incorrect v value was given as input.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	31	During update: The Contact was not found by its unique identifier.
404	69	One of the contact.pictures given as input in the Pictures array was not found. Returns an ErrorDetailBadIds as the `errorDetails`.
409	130	During update: When updating a Contact, the company was provided as a different value.

DELETE/contacts/{contactId}

Deletes an existing Contact.

URL Parameters

Parameter	Type	Required	Description
contactId	uint64	required	Unique identifier of the Contact.

Response description

Property	Type	Description
contact	RespDeleted	An object which contains the Contact's id, owning Company id, and deleted status.
contact.company	uint64	Identifier of the Company to which this object belongs.
contact.deleted	boolean	Flag showing if the object is deleted.
contact.id	uint64?	Identifier given as input for the command.
contact.v	Array.<uint32>
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"contact": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a contact object, or it is invalid.
400	3	The contact object does not contain an id, or it is invalid.
401	5	You do not have permission to delete this Contact.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	31	The Contact was not found by its unique identifier.
409	121	This Contact is still being used by a Asset or User. Returns an ErrorDetailContactInUse as the `errorDetails`.

PATCH/contacts/{contactId}/restore

Restores the specified Contact.

URL Parameters

Parameter	Type	Required	Description
contactId	uint64	required	Unique identifier of the Contact.

HTTP Request body description

Property	Type	Required	Description
contact	ParamId	always	An object to contain the "id" of the Contact.
contact.id	uint64	always	Identifier given as input for the command.
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"contact": {
		"id": number
	},
	"reqId": number
}

Response description

Property	Type	Description
contact	RespDeleted	An object which contains the Contact's id, owning Company id, and deleted status.
contact.company	uint64	Identifier of the Company to which this object belongs.
contact.deleted	boolean	Flag showing if the object is deleted.
contact.id	uint64?	Identifier given as input for the command.
contact.v	Array.<uint32>
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"contact": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a contact object, or it is invalid.
400	3	The contact object does not contain an id, or it is invalid.
401	5	You do not have permission to restore this Contact.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	31	The Contact was not found by its unique identifier.
400	32	The Contact was found, but is not marked as deleted.

GET/machines?includeDeleted=boolean&includeArchive=boolean&limit=number&first=string&last=string

This request is an alias of /companies/{your-company-id}/machines.

URL Parameters

Parameter	Type	Required	Default	Description
first	string	optional		When using , sets the first alphabetic SelfMachine.key when listing from the database.
includeArchive	boolean	optional	`false`	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	`false`	False by default, but when true the command will also return deleted objects.
last	string	optional		When using , sets the last alphabetic SelfMachine.key when listing from the database.
limit	uint16	optional		When using , sets the maximum number of objects in this response.
your-company-id	uint64	aliased	`{your-company-id}`	Your own Company's identifier.

PATCH/machines

Creates a new or updates an existing Machine.

HTTP Request body description

Property	Type	Required	Description
machine	Object.<string, ?>	always	An object to contain the Machine parameters.
machine.company	uint64?	create	The company to which this Machine belongs. After creation, this value is read-only.
machine.enabled	boolean	optional	Indicates whether system access is disable.
machine.formats	Object.<string, string>	optional	The format strings defining the preferred way to display ambiguous values.
machine.groups	Array.<uint64> for values see: UserGroup.id	optional	A list of UserGroup to which this Machine belongs.
machine.insecure	boolean	optional	Indicates whether completely insecure/unrestricted system access is allowed.
machine.ipRanges	Array.<ipv4> maximum-length of values: 19	optional	Restrict Machine access to only the provided IPv4 ranges (using CIDR slash-notation).
machine.key	string	update	The unique identifier of the Machine you want to update.
machine.language	string maximum-length: 5 minimum-length: 2	optional	Preferred region/language for the UI and notifications. Valid formats use <ISO 639-1><dash><ISO 3166-2> such as "fr-CA" or "en-US".
machine.measurements	Object.<string, SystemsOfUnits?>	optional	Preferred way of displaying ambiguous numbers in the context of measurements.
machine.nickname	string maximum-length: 100	optional	Human friendly name for this Machine.
machine.notAfter	datetime	optional	An optional timestamp that restricts this Machine from being used after the given date.
machine.notBefore	datetime	optional	An optional timestamp that restricts this Machine from being used before the given date.
machine.notes	string maximum-length: 8000	optional	Notes about this Machine.
machine.options	Object.<string, string>	optional	Additional options which do not fit in with the formats or measurements preferences.
machine.permissions	Array.<ParamPermission>	optional	Individual permission rules which override the UserGroup rules.
machine.referrers	Array.<url> maximum-length of values: 254	optional	Optional list of your managed domains from which this Machine can be used.
machine.secret	boolean	optional	A flag to either remove, or generate a new SelfMachine.secret.
machine.services	Array.<url> maximum-length of values: 254	optional	List of Fleet Freedom service URIs that this Machine is permitted to access.
machine.timezone	codified see: Timezone.code	optional	The Machine's local timezone.
machine.v	Array.<int32>	optional
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"machine": {
		"company": number,
		"enabled": boolean,
		"formats": {
			string: string
		},
		"groups": [
			number
		],
		"insecure": boolean,
		"ipRanges": [
			string
		],
		"key": string,
		"language": string,
		"measurements": {
			string: string
		},
		"nickname": string,
		"notAfter": string,
		"notBefore": string,
		"notes": string,
		"options": {
			string: string
		},
		"permissions": [
			{
				"company": number,
				"kind": string,
				"labels": [
					string
				],
				"level": string,
				"method": string
			}
		],
		"referrers": [
			string
		],
		"secret": boolean,
		"services": [
			string
		],
		"timezone": string,
		"v": [
			number
		]
	},
	"reqId": number
}

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
machine	RespKeyCompany	An object which contains the "key" and "company" keys when there is no error.
machine.company	uint64	Identifier of the Company to which the Machine belongs.
machine.key	string	The Machine's key.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"machine": {
		"company": number,
		"key": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
500	2	Unable to generate unique key. If you receive this error, please contact technical support.
400	3	The request does not contain a machine object, or it is invalid.
400	3	No valid changes would be performed.
400	3	The given language value was not a valid culture.
400	3	One of the keys given in the machine.formats dictionary was blank.
400	3	One of the keys given in the machine.measurements dictionary was blank.
400	3	One of the keys given in the machine.options dictionary was blank.
400	3	During create: When creating a new Machine, a key was given. Keys are generated by the system during creation.
400	3	During create: When creating a new Machine, a company was not given.
400	3	One of the schemes in the given machine.services array was not allowed. Returns an ErrorDetailEnum as the `errorDetails`.
400	3	One of the schemes in the given machine.referrers array was not allowed. Returns an ErrorDetailEnum as the `errorDetails`.
400	3	The given machine.notBefore value could not be parsed into a date/time. Returns an ErrorDetailInput as the `errorDetails`.
400	3	The given machine.notAfter value could not be parsed into a date/time. Returns an ErrorDetailInput as the `errorDetails`.
400	3	One of the values given in the machine.measurements dictionary was invalid. Returns an ErrorDetailInput as the `errorDetails`.
400	3	One of the values given in the machine.groups array was invalid. Returns an ErrorDetailInput as the `errorDetails`.
400	3	One of the values given in the machine.permissions array was invalid. Returns an ErrorDetailInput as the `errorDetails`.
400	3	One of the values given in the machine.services array was invalid. Returns an ErrorDetailInput as the `errorDetails`.
400	3	One of the values given in the machine.referrers array was invalid. Returns an ErrorDetailInput as the `errorDetails`.
400	3	One of the values given in the machine.ipRanges array was invalid. Returns an ErrorDetailInput as the `errorDetails`.
400	3	One of the values given in the machine.ipRanges array was a loopback. Returns an ErrorDetailInput as the `errorDetails`.
400	3	During update: When updating a Machine, the given key was invalid. Returns an ErrorDetailInput as the `errorDetails`.
401	5	During create: You do not have sufficient permission to create a new Machine.
401	5	During update: You do not have sufficient permission to update Machines.
400	6	During update: When updating a Machine, an incorrect v value was given as input.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	30	One or more of the UserGroups given could not be found, or were from a different Company. Returns an ErrorDetailBadIds as the `errorDetails`.
404	62	The given Timezone value could not be found. Returns an ErrorDetailInput as the `errorDetails`.
401	71	The Machine you are creating or updating would have higher, or more, permissions than you do. Returns an ErrorDetailEscalation as the `errorDetails`.
404	127	During update: When updating a Machine and the Machine does not exists.
409	130	During update: When updating a Machine, the machine.company can not be changed.

DELETE/machines

Deletes an existing Machine.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
machine	RespKeyDeleted	An object which contains the Machine's key, owning Company id, and deleted status.
machine.company	uint64	Identifier of the Company to which the Machine belongs.
machine.deleted	boolean	Flag showing if the object is deleted.
machine.key	string	The Machine's key.
machine.v	Array.<uint32>
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"machine": {
		"company": number,
		"deleted": boolean,
		"key": string,
		"v": [
			number
		]
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a machine object, or it is invalid.
400	3	The machine object does not contain a key, or it is invalid.
401	5	You do not have permission to delete Machines.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	127	The requested Machine is not found.

GET/machines/{key}?includeDeleted=boolean

Gets details of the specified Machine.

URL Parameters

Parameter	Type	Required	Description
includeDeleted	boolean	optional	False by default, but when true the command will also return deleted objects.
key	string	required	Unique identifier of the Machine.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
machine	Machine	The requested Machine.
machine.company	uint64 see: Company.id	The company to which this user belongs.
machine.enabled	boolean	Indicates whether system access is disable.
machine.formats	Object.<codified, datetimetemplate> maximum-length of values: 20	The format strings defining the preferred way to display ambiguous values.
machine.groups	Array.<uint64> see: UserGroup.id	A list of groups to which this machine account belongs.
machine.insecure	boolean	When true, no access restrictions (SelfMachine.secret, SelfMachine.referrers, or SelfMachine.ipRanges) are enforced.
machine.ipRanges	Array.<ipv4> maximum-length of values: 19	Restrict service access to only the provided IP ranges. Currently we only support IPv4 ranges using CIDR slash-notation.
machine.key	string maximum-length: 50	The unique idenifier used to access the system.
machine.language	codified maximum-length: 5 minimum-length: 2	Preferred region/language for the UI and notifications. Valid formats use <ISO 639-1><dash><ISO 3166-2> such as "fr-CA" or "en-US".
machine.measurements	Object.<codified, SystemsOfUnits>	Preferred way of displaying ambiguous numbers in the context of measurements.
machine.nickname	string maximum-length: 100	Human friendly name for these credentials
machine.notAfter	datetime	An optional timestamp that restricts this machine account from being used after the given date.
machine.notBefore	datetime	An optional timestamp that restricts this machine account from being used before the given date.
machine.notes	string maximum-length: 8000	Notes about this machine.
machine.options	Object.<codified, string> maximum-length of values: 20	Additional options which do not fit in with the formats or measurements preferences.
machine.permissions	Array.<Permission>	Permission rules which override the group rules.
machine.processedUtc	datetime	When the was change procesed.
machine.referrers	Array.<url> maximum-length of values: 254	Optional list of your managed domains from which this machine account can be used.
machine.secret	string maximum-length: 1000	A token used to encode or validate requests.
machine.services	Array.<url> maximum-length of values: 254	List of system service URIs that this machine account is permitted to access.
machine.timezone	codified see: Timezone.code	The service account's local timezone.
machine.updated		by: login, from: monster
machine.v	Array.<uint32>	Object version keys used to validate synchronization for all object properties.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"machine": {
		"company": number,
		"enabled": boolean,
		"formats": {
			string: string
		},
		"groups": [
			number
		],
		"insecure": boolean,
		"ipRanges": [
			string
		],
		"key": string,
		"language": string,
		"measurements": {
			string: string
		},
		"nickname": string,
		"notAfter": string,
		"notBefore": string,
		"notes": string,
		"options": {
			string: string
		},
		"permissions": [
			{
				"company": number,
				"kind": string,
				"labels": [
					string
				],
				"level": string,
				"method": string,
				"type": string
			}
		],
		"processedUtc": string,
		"referrers": [
			string
		],
		"secret": string,
		"services": [
			string
		],
		"timezone": string,
		"updated": {
		},
		"v": [
			number
		]
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a machine object, or it is invalid.
400	3	The machine object does not contain a key, or it is invalid.
401	5	You do not have permission to view Machines.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	127	The requested Machine is not found.

POST/machines/{key}

Creates a new or updates an existing Machine.

URL Parameters

Parameter	Type	Required	Description
key	string	optional	Unique identifier of the Machine. This value is optional, and ignored by the command.

HTTP Request body description

Property	Type	Required	Description
machine	Object.<string, ?>	always	An object to contain the Machine parameters.
machine.company	uint64?	create	The company to which this Machine belongs. After creation, this value is read-only.
machine.enabled	boolean	optional	Indicates whether system access is disable.
machine.formats	Object.<string, string>	optional	The format strings defining the preferred way to display ambiguous values.
machine.groups	Array.<uint64> for values see: UserGroup.id	optional	A list of UserGroup to which this Machine belongs.
machine.insecure	boolean	optional	Indicates whether completely insecure/unrestricted system access is allowed.
machine.ipRanges	Array.<ipv4> maximum-length of values: 19	optional	Restrict Machine access to only the provided IPv4 ranges (using CIDR slash-notation).
machine.key	string	update	The unique identifier of the Machine you want to update.
machine.language	string maximum-length: 5 minimum-length: 2	optional	Preferred region/language for the UI and notifications. Valid formats use <ISO 639-1><dash><ISO 3166-2> such as "fr-CA" or "en-US".
machine.measurements	Object.<string, SystemsOfUnits?>	optional	Preferred way of displaying ambiguous numbers in the context of measurements.
machine.nickname	string maximum-length: 100	optional	Human friendly name for this Machine.
machine.notAfter	datetime	optional	An optional timestamp that restricts this Machine from being used after the given date.
machine.notBefore	datetime	optional	An optional timestamp that restricts this Machine from being used before the given date.
machine.notes	string maximum-length: 8000	optional	Notes about this Machine.
machine.options	Object.<string, string>	optional	Additional options which do not fit in with the formats or measurements preferences.
machine.permissions	Array.<ParamPermission>	optional	Individual permission rules which override the UserGroup rules.
machine.referrers	Array.<url> maximum-length of values: 254	optional	Optional list of your managed domains from which this Machine can be used.
machine.secret	boolean	optional	A flag to either remove, or generate a new SelfMachine.secret.
machine.services	Array.<url> maximum-length of values: 254	optional	List of Fleet Freedom service URIs that this Machine is permitted to access.
machine.timezone	codified see: Timezone.code	optional	The Machine's local timezone.
machine.v	Array.<int32>	optional
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"machine": {
		"company": number,
		"enabled": boolean,
		"formats": {
			string: string
		},
		"groups": [
			number
		],
		"insecure": boolean,
		"ipRanges": [
			string
		],
		"key": string,
		"language": string,
		"measurements": {
			string: string
		},
		"nickname": string,
		"notAfter": string,
		"notBefore": string,
		"notes": string,
		"options": {
			string: string
		},
		"permissions": [
			{
				"company": number,
				"kind": string,
				"labels": [
					string
				],
				"level": string,
				"method": string
			}
		],
		"referrers": [
			string
		],
		"secret": boolean,
		"services": [
			string
		],
		"timezone": string,
		"v": [
			number
		]
	},
	"reqId": number
}

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
machine	RespKeyCompany	An object which contains the "key" and "company" keys when there is no error.
machine.company	uint64	Identifier of the Company to which the Machine belongs.
machine.key	string	The Machine's key.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"machine": {
		"company": number,
		"key": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
500	2	Unable to generate unique key. If you receive this error, please contact technical support.
400	3	The request does not contain a machine object, or it is invalid.
400	3	No valid changes would be performed.
400	3	The given language value was not a valid culture.
400	3	One of the keys given in the machine.formats dictionary was blank.
400	3	One of the keys given in the machine.measurements dictionary was blank.
400	3	One of the keys given in the machine.options dictionary was blank.
400	3	During create: When creating a new Machine, a key was given. Keys are generated by the system during creation.
400	3	During create: When creating a new Machine, a company was not given.
400	3	One of the schemes in the given machine.services array was not allowed. Returns an ErrorDetailEnum as the `errorDetails`.
400	3	One of the schemes in the given machine.referrers array was not allowed. Returns an ErrorDetailEnum as the `errorDetails`.
400	3	The given machine.notBefore value could not be parsed into a date/time. Returns an ErrorDetailInput as the `errorDetails`.
400	3	The given machine.notAfter value could not be parsed into a date/time. Returns an ErrorDetailInput as the `errorDetails`.
400	3	One of the values given in the machine.measurements dictionary was invalid. Returns an ErrorDetailInput as the `errorDetails`.
400	3	One of the values given in the machine.groups array was invalid. Returns an ErrorDetailInput as the `errorDetails`.
400	3	One of the values given in the machine.permissions array was invalid. Returns an ErrorDetailInput as the `errorDetails`.
400	3	One of the values given in the machine.services array was invalid. Returns an ErrorDetailInput as the `errorDetails`.
400	3	One of the values given in the machine.referrers array was invalid. Returns an ErrorDetailInput as the `errorDetails`.
400	3	One of the values given in the machine.ipRanges array was invalid. Returns an ErrorDetailInput as the `errorDetails`.
400	3	One of the values given in the machine.ipRanges array was a loopback. Returns an ErrorDetailInput as the `errorDetails`.
400	3	During update: When updating a Machine, the given key was invalid. Returns an ErrorDetailInput as the `errorDetails`.
401	5	During create: You do not have sufficient permission to create a new Machine.
401	5	During update: You do not have sufficient permission to update Machines.
400	6	During update: When updating a Machine, an incorrect v value was given as input.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	30	One or more of the UserGroups given could not be found, or were from a different Company. Returns an ErrorDetailBadIds as the `errorDetails`.
404	62	The given Timezone value could not be found. Returns an ErrorDetailInput as the `errorDetails`.
401	71	The Machine you are creating or updating would have higher, or more, permissions than you do. Returns an ErrorDetailEscalation as the `errorDetails`.
404	127	During update: When updating a Machine and the Machine does not exists.
409	130	During update: When updating a Machine, the machine.company can not be changed.

DELETE/machines/{key}

Deletes an existing Machine.

URL Parameters

Parameter	Type	Required	Description
key	string	required	Unique identifier of the Machine.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
machine	RespKeyDeleted	An object which contains the Machine's key, owning Company id, and deleted status.
machine.company	uint64	Identifier of the Company to which the Machine belongs.
machine.deleted	boolean	Flag showing if the object is deleted.
machine.key	string	The Machine's key.
machine.v	Array.<uint32>
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"machine": {
		"company": number,
		"deleted": boolean,
		"key": string,
		"v": [
			number
		]
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a machine object, or it is invalid.
400	3	The machine object does not contain a key, or it is invalid.
401	5	You do not have permission to delete Machines.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	127	The requested Machine is not found.

PATCH/machines/{key}/restore

Restores the specified Machine if it's been deleted.

URL Parameters

Parameter	Type	Required	Description
key	string	required	Unique identifier of the Machine.

HTTP Request body description

Property	Type	Required	Description
machine	ParamKey	always	An object to contain the "key" of the Machine.
machine.key	string	always	The Machine's login.
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"machine": {
		"key": string
	},
	"reqId": number
}

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
machine	RespKeyDeleted	An object which contains the Machine's key, owning Company id, and deleted status.
machine.company	uint64	Identifier of the Company to which the Machine belongs.
machine.deleted	boolean	Flag showing if the object is deleted.
machine.key	string	The Machine's key.
machine.v	Array.<uint32>
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"machine": {
		"company": number,
		"deleted": boolean,
		"key": string,
		"v": [
			number
		]
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a machine object, or it is invalid.
400	3	The machine object does not contain a key, or it is invalid.
401	5	You do not have permission to restore deleted Machines.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	127	The requested Machine is not found.
400	128	The requested Machine was found, but is not marked as deleted.

GET/machines?groupId={uint64}&includeDeleted=boolean&includeArchive=boolean&limit=number&first=string&last=string

Gets the list of Machines for the specified Company.

URL Parameters

Parameter	Type	Required	Description
first	string	optional	When using , sets the first alphabetic SelfMachine.key when listing from the database.
groupId	uint64	required	Unique identifier of the UserGroup.
includeArchive	boolean	optional	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	False by default, but when true, the command will also return deleted objects.
last	string	optional	When using , sets the last alphabetic SelfMachine.key when listing from the database.
limit	uint16?	optional	When using , sets the maximum number of objects retrieved from the archive.

Response description

Property	Type	Description
company	RespId	An object to contain the "id" of the Company to which the array of Machines belong.
company.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
machines	Array.<Machine>	The list requested of Machines.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"machines": [
		{
			"company": number,
			"enabled": boolean,
			"formats": {
				string: string
			},
			"groups": [
				number
			],
			"insecure": boolean,
			"ipRanges": [
				string
			],
			"key": string,
			"language": string,
			"measurements": {
				string: string
			},
			"nickname": string,
			"notAfter": string,
			"notBefore": string,
			"notes": string,
			"options": {
				string: string
			},
			"permissions": [
				{
					"company": number,
					"kind": string,
					"labels": [
						string
					],
					"level": string,
					"method": string,
					"type": string
				}
			],
			"processedUtc": string,
			"referrers": [
				string
			],
			"secret": string,
			"services": [
				string
			],
			"timezone": string,
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
401	5	You do not have permission to view this Company's Machines.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.

GET/users?includeDeleted=boolean&includeArchive=boolean&limit=number&first=string&last=string

This request is an alias of /companies/{your-company-id}/users/.

URL Parameters

Parameter	Type	Required	Default	Description
first	string	optional		When using , sets the first alphabetic User.login when listing from the database.
includeArchive	boolean	optional	`false`	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	`false`	False by default, but when true the command will also return deleted objects.
last	string	optional		When using , sets the last alphabetic User.login when listing from the database.
limit	uint16	optional		When using , sets the maximum number of objects in this response.
your-company-id	uint64	aliased	`{your-company-id}`	Your own Company's identifier.

PATCH/users

Creates a new or updates an existing User.

HTTP Request body description

Property	Type	Required	Description
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.
user	Object.<string, ?>	always
user.company	uint64?	create	The company to which this User belongs. After creation, this value is read-only.
user.contact	uint64? see: Contact.id	optional	Contact information for this User.
user.enabled	boolean	optional	Indicates whether system access is disable.
user.formats	Object.<codified, string>	optional	The format strings defining the preferred way to display ambiguous values.
user.groups	Array.<uint64> for values see: UserGroup.id	optional	A list of UserGroups to which this User is a member.
user.language	string maximum-length: 5 minimum-length: 2	optional	Preferred region/language for the UI and notifications. Valid formats use <ISO 639-1><dash><ISO 3166-2> such as "fr-CA" or "en-US".
user.login	email	always	The unique identifier of the User you want to update.
user.measurements	Object.<codified, SystemsOfUnits?>	optional	Preferred way of displaying ambiguous numbers in the context of measurements.
user.nickname	string maximum-length: 100	optional	Human friendly name for these credentials
user.notify	Array.<UserNotifications>	optional	Definition of how and when to send alerts to the User.
user.options	Object.<codified, string>	optional	Additional options which do not fit in with the formats or measurements preferences.
user.password	string	create	This User's password.
user.passwordExpired	boolean	optional	Indicated whether the credentials have expired according to the company's policy.
user.permissions	Array.<ParamPermission> maximum-count of values: 254	optional	Individual permission rules which override the UserGroup rules.
user.timezone	codified see: Timezone.code	optional	The User's local timezone.
user.v	Array.<int32>	optional

HTTP Request body structure

{
	"reqId": number,
	"user": {
		"company": number,
		"contact": number,
		"enabled": boolean,
		"formats": {
			string: string
		},
		"groups": [
			number
		],
		"language": string,
		"login": string,
		"measurements": {
			string: string
		},
		"nickname": string,
		"notify": [
			{
				"email": string,
				"enabled": boolean,
				"end": string,
				"name": string,
				"offline": [
					string
				],
				"online": [
					string
				],
				"sms": number,
				"start": string,
				"weekdays": [
					boolean
				]
			}
		],
		"options": {
			string: string
		},
		"password": string,
		"passwordExpired": boolean,
		"permissions": [
			{
				"company": number,
				"kind": string,
				"labels": [
					string
				],
				"level": string,
				"method": string
			}
		],
		"timezone": string,
		"v": [
			number
		]
	}
}

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.
user	RespLoginCompany
user.company	uint64	Identifier of the Company to which the User belongs.
user.login	string	The User's login.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number,
	"user": {
		"company": number,
		"login": string
	}
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a user object, or it is invalid.
400	3	No valid changes would be performed.
400	3	The user object did not contain a login, or was not a valid email address.
400	3	The user object contains a contact which is not valid.
400	3	The user object contains a blank password.
400	3	The given language was not a valid region.
400	3	One of the keys given in the user.formats dictionary was blank.
400	3	One of the keys given in the user.measurements dictionary was blank.
400	3	One of the keys given in the user.options dictionary was blank.
400	3	One of the given user.notify values was null, had a blank name property, or was not a valid object.
400	3	The contact given is from a different company than the User.
400	3	During create: When creating a new User, a company was not given.
400	3	During create: When creating a new User, a password was not given.
400	3	During update: When updating a User, the company can not be changed.
400	3	One of the user.measurements could not be parsed. Returns an ErrorDetailInput as the `errorDetails`.
400	3	One of the user.notify preferences could not be parsed. Returns an ErrorDetailInput as the `errorDetails`.
400	3	One of the user.notify preferences did not contain a name. Returns an ErrorDetailInput as the `errorDetails`.
400	3	One of the user.groups was not given as a number. Returns an ErrorDetailInput as the `errorDetails`.
400	3	One of the user.permissions was invalid. Returns an ErrorDetailInput as the `errorDetails`.
401	5	During create: You do not have sufficient permission to create a new User.
401	5	During update: You do not have sufficient permission to update Users.
401	5	During update: You do not have sufficient permission to update User permissions.
401	5	During update: You do not have sufficient permission to view contacts.
400	6	During update: When updating a User, an incorrect v value was given as input.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
401	15	The user.password given for the User was not strong enough.
403	16	You cannot execute this command because your password has expired.
404	28	The User's company's password policy could not be found. If you receive this error, please contact technical support.
404	30	One or more of the UserGroups given could not be found, or were from a different company. Returns an ErrorDetailBadIds as the `errorDetails`.
404	31	The Contact given could not be found.
404	54	During update: When updating a User and the User does not exists.
400	55	During create: When creating a new User and the User already exists.
403	57	You cannot disable your own User.
404	62	The given Timezone could not be found. Returns an ErrorDetailInput as the `errorDetails`.
401	71	The User you are creating or updating would have higher, or more, permissions than you do. Returns an ErrorDetailEscalation as the `errorDetails`.
409	130	The specified user.contact was found, but was not in the same Company as the given User.
409	130	During update: When updating an User, the user.company can not be changed.

DELETE/users

Deletes an existing User.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.
user	RespLoginDeleted	An object which contains the User's login, owning Company id, and deleted status.
user.company	uint64	Identifier of the Company to which the User belongs.
user.deleted	boolean	Flag showing if the object is deleted.
user.login	string	The User's login.
user.v	Array.<uint32>

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number,
	"user": {
		"company": number,
		"deleted": boolean,
		"login": string,
		"v": [
			number
		]
	}
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a user object, or it is invalid.
400	3	The user object does not contain a login, or it is an invalid email address.
401	5	You do not have permission to delete Users.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	54	The requested User is not found.
403	57	You cannot delete your own User.

GET/users/{login}?includeDeleted=boolean

Gets details of the specified User.

URL Parameters

Parameter	Type	Required	Description
includeDeleted	boolean	optional	False by default, but when true the command will also return deleted objects.
login	email	required	Unique identifier of the User.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.
user	User	The requested User.
user.company	uint64 see: Company.id	The company to which this user belongs.
user.contact	uint64? see: Contact.id	Contact information for this user.
user.enabled	boolean	Indicates whether system access is disabled.
user.formats	Object.<codified, datetimetemplate> maximum-length of values: 20	The format strings defining the preferred way to display ambiguous values.
user.groups	Array.<uint64> see: UserGroup.id	A list of groups to which this user belongs.
user.language	codified maximum-length: 5 minimum-length: 2	Preferred region/language for the UI and notifications. Valid formats use <ISO 639-1><dash><ISO 3166-2> such as "fr-CA" or "en-US".
user.login	email maximum-length: 254 minimum-length: 6	Unique identifier of this user.
user.measurements	Object.<codified, SystemsOfUnits>	Preferred way of displaying ambiguous numbers in the context of measurements.
user.nickname	string maximum-length: 100	Human friendly name for these credentials
user.notify	Array.<UserNotifications> maximum-count: 7	Definition of how and when to send alerts to the user.
user.options	Object.<codified, string> maximum-length of values: 20	Additional options which do not fit in with the formats or measurements preferences.
user.passwordExpired	boolean	Indicated whether the credentials have expired according to the company's policy.
user.permissions	Array.<Permission>	Individual permission rules which override the group rules.
user.processedUtc	datetime	When the was change procesed.
user.timezone	codified see: Timezone.code	The user's local timezone.
user.updated		by: login, from: monster
user.v	Array.<int32> fixed count: 2	Object version keys used to validate synchronization for all object properties.
user.v[0]	int32	The first element is for the general properties
user.v[1]	int32	The second element is for the advanced properties

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number,
	"user": {
		"company": number,
		"contact": number,
		"enabled": boolean,
		"formats": {
			string: string
		},
		"groups": [
			number
		],
		"language": string,
		"login": string,
		"measurements": {
			string: string
		},
		"nickname": string,
		"notify": [
			{
				"email": string,
				"enabled": boolean,
				"end": string,
				"name": string,
				"offline": [
					string
				],
				"online": [
					string
				],
				"sms": number,
				"start": string,
				"weekdays": [
					boolean
				]
			}
		],
		"options": {
			string: string
		},
		"passwordExpired": boolean,
		"permissions": [
			{
				"company": number,
				"kind": string,
				"labels": [
					string
				],
				"level": string,
				"method": string,
				"type": string
			}
		],
		"processedUtc": string,
		"timezone": string,
		"updated": {
		},
		"v": [
			number
		]
	}
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a user object, or it is invalid.
400	3	The user object does not contain a login, or it is an invalid email address.
401	5	You do not have permission to view Users.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	54	The requested User is not found.

POST/users/{login}

Creates a new or updates an existing User.

URL Parameters

Parameter	Type	Required	Description
login	email	optional	Unique identifier of the User. This value is optional, and ignored by the command.

HTTP Request body description

Property	Type	Required	Description
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.
user	Object.<string, ?>	always
user.company	uint64?	create	The company to which this User belongs. After creation, this value is read-only.
user.contact	uint64? see: Contact.id	optional	Contact information for this User.
user.enabled	boolean	optional	Indicates whether system access is disable.
user.formats	Object.<codified, string>	optional	The format strings defining the preferred way to display ambiguous values.
user.groups	Array.<uint64> for values see: UserGroup.id	optional	A list of UserGroups to which this User is a member.
user.language	string maximum-length: 5 minimum-length: 2	optional	Preferred region/language for the UI and notifications. Valid formats use <ISO 639-1><dash><ISO 3166-2> such as "fr-CA" or "en-US".
user.login	email	always	The unique identifier of the User you want to update.
user.measurements	Object.<codified, SystemsOfUnits?>	optional	Preferred way of displaying ambiguous numbers in the context of measurements.
user.nickname	string maximum-length: 100	optional	Human friendly name for these credentials
user.notify	Array.<UserNotifications>	optional	Definition of how and when to send alerts to the User.
user.options	Object.<codified, string>	optional	Additional options which do not fit in with the formats or measurements preferences.
user.password	string	create	This User's password.
user.passwordExpired	boolean	optional	Indicated whether the credentials have expired according to the company's policy.
user.permissions	Array.<ParamPermission> maximum-count of values: 254	optional	Individual permission rules which override the UserGroup rules.
user.timezone	codified see: Timezone.code	optional	The User's local timezone.
user.v	Array.<int32>	optional

HTTP Request body structure

{
	"reqId": number,
	"user": {
		"company": number,
		"contact": number,
		"enabled": boolean,
		"formats": {
			string: string
		},
		"groups": [
			number
		],
		"language": string,
		"login": string,
		"measurements": {
			string: string
		},
		"nickname": string,
		"notify": [
			{
				"email": string,
				"enabled": boolean,
				"end": string,
				"name": string,
				"offline": [
					string
				],
				"online": [
					string
				],
				"sms": number,
				"start": string,
				"weekdays": [
					boolean
				]
			}
		],
		"options": {
			string: string
		},
		"password": string,
		"passwordExpired": boolean,
		"permissions": [
			{
				"company": number,
				"kind": string,
				"labels": [
					string
				],
				"level": string,
				"method": string
			}
		],
		"timezone": string,
		"v": [
			number
		]
	}
}

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.
user	RespLoginCompany
user.company	uint64	Identifier of the Company to which the User belongs.
user.login	string	The User's login.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number,
	"user": {
		"company": number,
		"login": string
	}
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a user object, or it is invalid.
400	3	No valid changes would be performed.
400	3	The user object did not contain a login, or was not a valid email address.
400	3	The user object contains a contact which is not valid.
400	3	The user object contains a blank password.
400	3	The given language was not a valid region.
400	3	One of the keys given in the user.formats dictionary was blank.
400	3	One of the keys given in the user.measurements dictionary was blank.
400	3	One of the keys given in the user.options dictionary was blank.
400	3	One of the given user.notify values was null, had a blank name property, or was not a valid object.
400	3	The contact given is from a different company than the User.
400	3	During create: When creating a new User, a company was not given.
400	3	During create: When creating a new User, a password was not given.
400	3	During update: When updating a User, the company can not be changed.
400	3	One of the user.measurements could not be parsed. Returns an ErrorDetailInput as the `errorDetails`.
400	3	One of the user.notify preferences could not be parsed. Returns an ErrorDetailInput as the `errorDetails`.
400	3	One of the user.notify preferences did not contain a name. Returns an ErrorDetailInput as the `errorDetails`.
400	3	One of the user.groups was not given as a number. Returns an ErrorDetailInput as the `errorDetails`.
400	3	One of the user.permissions was invalid. Returns an ErrorDetailInput as the `errorDetails`.
401	5	During create: You do not have sufficient permission to create a new User.
401	5	During update: You do not have sufficient permission to update Users.
401	5	During update: You do not have sufficient permission to update User permissions.
401	5	During update: You do not have sufficient permission to view contacts.
400	6	During update: When updating a User, an incorrect v value was given as input.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
401	15	The user.password given for the User was not strong enough.
403	16	You cannot execute this command because your password has expired.
404	28	The User's company's password policy could not be found. If you receive this error, please contact technical support.
404	30	One or more of the UserGroups given could not be found, or were from a different company. Returns an ErrorDetailBadIds as the `errorDetails`.
404	31	The Contact given could not be found.
404	54	During update: When updating a User and the User does not exists.
400	55	During create: When creating a new User and the User already exists.
403	57	You cannot disable your own User.
404	62	The given Timezone could not be found. Returns an ErrorDetailInput as the `errorDetails`.
401	71	The User you are creating or updating would have higher, or more, permissions than you do. Returns an ErrorDetailEscalation as the `errorDetails`.
409	130	The specified user.contact was found, but was not in the same Company as the given User.
409	130	During update: When updating an User, the user.company can not be changed.

DELETE/users/{login}

Deletes an existing User.

URL Parameters

Parameter	Type	Required	Description
login	email	required	Unique identifier of the User.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.
user	RespLoginDeleted	An object which contains the User's login, owning Company id, and deleted status.
user.company	uint64	Identifier of the Company to which the User belongs.
user.deleted	boolean	Flag showing if the object is deleted.
user.login	string	The User's login.
user.v	Array.<uint32>

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number,
	"user": {
		"company": number,
		"deleted": boolean,
		"login": string,
		"v": [
			number
		]
	}
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a user object, or it is invalid.
400	3	The user object does not contain a login, or it is an invalid email address.
401	5	You do not have permission to delete Users.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	54	The requested User is not found.
403	57	You cannot delete your own User.

GET/users/{login}/advanceds?includeDeleted=boolean

Gets details of the specified User.

URL Parameters

Parameter	Type	Required	Description
includeDeleted	boolean	optional	False by default, but when true the command will also return deleted objects.
login	email	required	Unique identifier of the User.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.
userAdvanced	UserAdvanced	The requested User.
userAdvanced.company	uint64 see: Company.id	The company to which this user belongs.
userAdvanced.groups	Array.<uint64> see: UserGroup.id	A list of groups to which this user belongs.
userAdvanced.login	email see: User.login maximum-length: 254 minimum-length: 6	The unique public email address used to access the system.
userAdvanced.permissions	Array.<Permission>	Individual permission rules which override the group rules.
userAdvanced.processedUtc	datetime	When the was change procesed.
userAdvanced.updated		by: login, from: monster
userAdvanced.v	Array.<uint32>	Object version keys used to validate synchronization for all object properties.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number,
	"userAdvanced": {
		"company": number,
		"groups": [
			number
		],
		"login": string,
		"permissions": [
			{
				"company": number,
				"kind": string,
				"labels": [
					string
				],
				"level": string,
				"method": string,
				"type": string
			}
		],
		"processedUtc": string,
		"updated": {
		},
		"v": [
			number
		]
	}
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a user object, or it is invalid.
400	3	The user object does not contain an id, or it is invalid.
401	5	You do not have permission to view this User's advanced details.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	20	The User was not found by its unique identifier.

GET/users/{login}/generals?includeDeleted=boolean

Gets details of the specified User.

URL Parameters

Parameter	Type	Required	Description
includeDeleted	boolean	optional	False by default, but when true the command will also return deleted objects.
login	email	required	Unique identifier of the User.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.
userGeneral	UserGeneral	The requested User.
userGeneral.company	uint64 see: Company.id	The company to which this user belongs.
userGeneral.contact	uint64? see: Contact.id	Contact information for this user.
userGeneral.enabled	boolean	Indicates whether system access is disabled.
userGeneral.formats	Object.<codified, datetimetemplate> maximum-length of values: 20	The format strings defining the preferred way to display ambiguous values.
userGeneral.language	codified maximum-length: 5 minimum-length: 2	Preferred region/language for the UI and notifications. Valid formats use <ISO 639-1><dash><ISO 3166-2> such as "fr-CA" or "en-US".
userGeneral.login	email see: User.login maximum-length: 254 minimum-length: 6	The unique public email address used to access the system.
userGeneral.measurements	Object.<codified, SystemsOfUnits>	Preferred way of displaying ambiguous numbers in the context of measurements.
userGeneral.nickname	string maximum-length: 100	Human friendly name for these credentials
userGeneral.notify	Array.<UserNotifications> maximum-count: 7	Definition of how and when to send alerts to the user.
userGeneral.options	Object.<codified, string> maximum-length of values: 20	Additional options which do not fit in with the formats or measurements preferences.
userGeneral.passwordExpired	boolean	Indicated whether the credentials have expired according to the company's policy.
userGeneral.processedUtc	datetime	When the was change procesed.
userGeneral.timezone	codified see: Timezone.code	The user's local timezone.
userGeneral.updated		by: login, from: monster
userGeneral.v	Array.<uint32>	Object version keys used to validate synchronization for all object properties.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number,
	"userGeneral": {
		"company": number,
		"contact": number,
		"enabled": boolean,
		"formats": {
			string: string
		},
		"language": string,
		"login": string,
		"measurements": {
			string: string
		},
		"nickname": string,
		"notify": [
			{
				"email": string,
				"enabled": boolean,
				"end": string,
				"name": string,
				"offline": [
					string
				],
				"online": [
					string
				],
				"sms": number,
				"start": string,
				"weekdays": [
					boolean
				]
			}
		],
		"options": {
			string: string
		},
		"passwordExpired": boolean,
		"processedUtc": string,
		"timezone": string,
		"updated": {
		},
		"v": [
			number
		]
	}
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a user object, or it is invalid.
400	3	The user object does not contain an id, or it is invalid.
401	5	You do not have permission to view this User's simple details.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	20	The User was not found by its unique identifier.

PATCH/users/{login}/restore

Restores the specified User if it's been deleted.

URL Parameters

Parameter	Type	Required	Description
login	email	required	Unique identifier of the User.

HTTP Request body description

Property	Type	Required	Description
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.
user	ParamLogin	always	An object to contain the "login" of the User.
user.login	email	always	The User's login.

HTTP Request body structure

{
	"reqId": number,
	"user": {
		"login": string
	}
}

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.
user	RespLoginDeleted	An object which contains the User's login, owning Company id, and deleted status.
user.company	uint64	Identifier of the Company to which the User belongs.
user.deleted	boolean	Flag showing if the object is deleted.
user.login	string	The User's login.
user.v	Array.<uint32>

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number,
	"user": {
		"company": number,
		"deleted": boolean,
		"login": string,
		"v": [
			number
		]
	}
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a user object, or it is invalid.
400	3	The user object does not contain a login, or it is an invalid email address.
401	5	You do not have permission to restore Users.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	54	The requested User is not found.
400	55	The requested User not found, but is not marked as deleted.

GET/users/{login}/sessions

Gets the list of SessionFull for the specified Company.

URL Parameters

Parameter	Type	Required	Description
login	email	required	Unique identifier of the User.

Response description

Property	Type	Description
company	RespId	An object to contain the "id" of the Company to which the array of SessionFulls belong.
company.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.
sessions	Array.<SessionFull>	The list of requested SessionFull.

Response structure

{
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number,
	"sessions": [
		{
			"active": boolean,
			"company": number,
			"created": string,
			"expiry": string,
			"handle": string,
			"ipAddress": string,
			"lastActivity": string,
			"lastCommand": string,
			"login": string,
			"sockets": number,
			"status": string,
			"userAgent": string
		}
	]
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
401	5	You do not have permission to view SessionFulls for this Company.
401	5	You do not have permission to view Users for this Company.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company was not found by its unique identifier.

GET/users/advanceds?includeDeleted=boolean&includeArchive=boolean&limit=number&first=string&last=string

This request is an alias of /companies/{your-company-id}/users/.

URL Parameters

Parameter	Type	Required	Default	Description
first	string	optional		When using , sets the first alphabetic User.login when listing from the database.
includeArchive	boolean	optional	`false`	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	`false`	False by default, but when true the command will also return deleted objects.
last	string	optional		When using , sets the last alphabetic User.login when listing from the database.
limit	uint16	optional		When using , sets the maximum number of objects in this response.
your-company-id	uint64	aliased	`{your-company-id}`	Your own Company's identifier.

GET/users/generals?includeDeleted=boolean&includeArchive=boolean&limit=number&first=string&last=string

This request is an alias of /companies/{your-company-id}/users/.

URL Parameters

Parameter	Type	Required	Default	Description
first	string	optional		When using , sets the first alphabetic User.login when listing from the database.
includeArchive	boolean	optional	`false`	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	`false`	False by default, but when true the command will also return deleted objects.
last	string	optional		When using , sets the last alphabetic User.login when listing from the database.
limit	uint16	optional		When using , sets the maximum number of objects in this response.
your-company-id	uint64	aliased	`{your-company-id}`	Your own Company's identifier.

GET/users/groups?includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

This request is an alias of /companies/{your-company-id}/users/groups/.

URL Parameters

Parameter	Type	Required	Default	Description
highest	uint64	optional		When using , sets the maximum id when listing from the database.
includeArchive	boolean	optional	`false`	Same as by default, when true the command will also return archived objects.
includeDeleted	boolean	optional	`false`	False by default, but when true the command will also return deleted objects.
limit	uint16	optional		When using , sets the maximum number of objects in this response.
lowest	uint64	optional		When using , sets the minimum id when listing from the database.
your-company-id	uint64	aliased	`{your-company-id}`	Your own Company's identifier.

PATCH/users/groups

Creates a new or updates an existing UserGroup.

HTTP Request body description

Property	Type	Required	Description
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.
userGroup	Object.<string, ?>	always	A simple object to contain the UserGroup parameters.
userGroup.company	uint64?	create	The company to which this UserGroup belongs. After creation, this value is read-only.
userGroup.id	uint64?	update	The unique identifier of the UserGroup you want to update.
userGroup.name	string maximum-length: 100	create	Name for the UserGroup.
userGroup.notes	string	optional	Notes for the UserGroup.
userGroup.permissions	Array.<ParamPermission> maximum-count of values: 254	optional	List of permissions assigned to members of this UserGroup.
userGroup.v	Array.<int32>	optional

HTTP Request body structure

{
	"reqId": number,
	"userGroup": {
		"company": number,
		"id": number,
		"name": string,
		"notes": string,
		"permissions": [
			{
				"company": number,
				"kind": string,
				"labels": [
					string
				],
				"level": string,
				"method": string
			}
		],
		"v": [
			number
		]
	}
}

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.
userGroup	RespIdCompany	An object which contains the "id" and "company".
userGroup.company	uint64	Identifier of the Company to which this object belongs.
userGroup.id	uint64?	Identifier given as input for the command.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number,
	"userGroup": {
		"company": number,
		"id": number
	}
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a userGroup object, or it is invalid.
400	3	Not enough keys exist in the userGroup object.
400	3	During create: When creating a new UserGroup, a company was not given.
400	3	During create: When creating a new UserGroup, a name was not given, or it is invalid.
400	3	During create: When creating a new UserGroup, no Permissions were given.
400	3	During update: When updating a UserGroup, the id was invalid.
400	3	During update: When updating a UserGroup, the userGroup object contained too few keys.
400	3	During update: When updating a UserGroup, all Permissions were removed.
401	5	During create: You do not have permission to create a new UserGroup.
401	5	During update: You do not have permission to update UserGroups.
400	6	During update: When updating a UserGroup, an incorrect v value was given as input.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	30	During update: The UserGroup was not found by its unique identifier.
401	71	Resulting permissions would grant a higher level of access than session User's own access level.
409	130	During update: When updating a UserGroup, the userGroup.company can not be changed.

DELETE/users/groups

Deletes an existing UserGroup.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.
userGroup	RespDeleted	An object which contains the "id" and "company" keys when there is no error.
userGroup.company	uint64	Identifier of the Company to which this object belongs.
userGroup.deleted	boolean	Flag showing if the object is deleted.
userGroup.id	uint64?	Identifier given as input for the command.
userGroup.v	Array.<uint32>

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number,
	"userGroup": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	}
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a userGroup object, or it is invalid.
400	3	The requested userGroup id was invalid.
401	5	You do not have permission to delete UserGroups.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	30	The UserGroup was not found by its unique identifier.
409	65	The UserGroup is currently in use. Please remove any Users who are a member of the UserGroup, then try again.

GET/users/groups/{groupId}?includeDeleted=boolean

Gets an existing UserGroup.

URL Parameters

Parameter	Type	Required	Description
groupId	uint64	required	Unique identifier of the UserGroup.
includeDeleted	boolean	optional	False by default, but when true the command will also return deleted objects.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.
userGroup	UserGroup	The requested UserGroup.
userGroup.company	uint64 see: Company.id	The company to which this group belongs.
userGroup.id	uint64	Unique identifier of this group.
userGroup.name	string maximum-length: 100	A name given to this group.
userGroup.notes	string	Notes about this group, and to whom this group should be applied.
userGroup.permissions	Array.<Permission>	Permissions for this group.
userGroup.processedUtc	datetime	When the was change procesed.
userGroup.updated		by: login, from: monster
userGroup.v	Array.<uint32>	Object version keys used to validate synchronization for all object properties.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number,
	"userGroup": {
		"company": number,
		"id": number,
		"name": string,
		"notes": string,
		"permissions": [
			{
				"company": number,
				"kind": string,
				"labels": [
					string
				],
				"level": string,
				"method": string,
				"type": string
			}
		],
		"processedUtc": string,
		"updated": {
		},
		"v": [
			number
		]
	}
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a userGroup object, or it is invalid.
400	3	The requested userGroup id was invalid.
401	5	You do not have permission to view UserGroups.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	30	The UserGroup was not found by its unique identifier.

POST/users/groups/{groupId}

Creates a new or updates an existing UserGroup.

URL Parameters

Parameter	Type	Required	Description
groupId	uint64?	optional	Unique identifier of the UserGroup. This value is optional, and ignored by the command.

HTTP Request body description

Property	Type	Required	Description
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.
userGroup	Object.<string, ?>	always	A simple object to contain the UserGroup parameters.
userGroup.company	uint64?	create	The company to which this UserGroup belongs. After creation, this value is read-only.
userGroup.id	uint64?	update	The unique identifier of the UserGroup you want to update.
userGroup.name	string maximum-length: 100	create	Name for the UserGroup.
userGroup.notes	string	optional	Notes for the UserGroup.
userGroup.permissions	Array.<ParamPermission> maximum-count of values: 254	optional	List of permissions assigned to members of this UserGroup.
userGroup.v	Array.<int32>	optional

HTTP Request body structure

{
	"reqId": number,
	"userGroup": {
		"company": number,
		"id": number,
		"name": string,
		"notes": string,
		"permissions": [
			{
				"company": number,
				"kind": string,
				"labels": [
					string
				],
				"level": string,
				"method": string
			}
		],
		"v": [
			number
		]
	}
}

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.
userGroup	RespIdCompany	An object which contains the "id" and "company".
userGroup.company	uint64	Identifier of the Company to which this object belongs.
userGroup.id	uint64?	Identifier given as input for the command.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number,
	"userGroup": {
		"company": number,
		"id": number
	}
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a userGroup object, or it is invalid.
400	3	Not enough keys exist in the userGroup object.
400	3	During create: When creating a new UserGroup, a company was not given.
400	3	During create: When creating a new UserGroup, a name was not given, or it is invalid.
400	3	During create: When creating a new UserGroup, no Permissions were given.
400	3	During update: When updating a UserGroup, the id was invalid.
400	3	During update: When updating a UserGroup, the userGroup object contained too few keys.
400	3	During update: When updating a UserGroup, all Permissions were removed.
401	5	During create: You do not have permission to create a new UserGroup.
401	5	During update: You do not have permission to update UserGroups.
400	6	During update: When updating a UserGroup, an incorrect v value was given as input.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	30	During update: The UserGroup was not found by its unique identifier.
401	71	Resulting permissions would grant a higher level of access than session User's own access level.
409	130	During update: When updating a UserGroup, the userGroup.company can not be changed.

DELETE/users/groups/{groupId}

Deletes an existing UserGroup.

URL Parameters

Parameter	Type	Required	Description
groupId	uint64	required	Unique identifier of the UserGroup.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.
userGroup	RespDeleted	An object which contains the "id" and "company" keys when there is no error.
userGroup.company	uint64	Identifier of the Company to which this object belongs.
userGroup.deleted	boolean	Flag showing if the object is deleted.
userGroup.id	uint64?	Identifier given as input for the command.
userGroup.v	Array.<uint32>

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number,
	"userGroup": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	}
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a userGroup object, or it is invalid.
400	3	The requested userGroup id was invalid.
401	5	You do not have permission to delete UserGroups.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	30	The UserGroup was not found by its unique identifier.
409	65	The UserGroup is currently in use. Please remove any Users who are a member of the UserGroup, then try again.

PATCH/users/groups/{groupId}/restore

Restores a previously deleted UserGroup.

URL Parameters

Parameter	Type	Required	Description
groupId	uint64	required	Unique identifier of the UserGroup.

HTTP Request body description

Property	Type	Required	Description
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.
userGroup	ParamId	always	An object to contain the "id" of the UserGroup.
userGroup.id	uint64	always	Identifier given as input for the command.

HTTP Request body structure

{
	"reqId": number,
	"userGroup": {
		"id": number
	}
}

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.
userGroup	RespDeleted	An object which contains the "id" and "company" keys when there is no error.
userGroup.company	uint64	Identifier of the Company to which this object belongs.
userGroup.deleted	boolean	Flag showing if the object is deleted.
userGroup.id	uint64?	Identifier given as input for the command.
userGroup.v	Array.<uint32>

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number,
	"userGroup": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	}
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a userGroup object, or it is invalid.
400	3	The requested userGroup id was invalid.
401	5	You do not have permission to delete UserGroups.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	30	The UserGroup was not found by its unique identifier.
400	66	The UserGroup was found, but is not marked as deleted.

GET/users/sessions

This request is an alias of /companies/{your-company-id}/sessions/.

URL Parameters

Parameter	Type	Required	Default	Description
your-company-id	uint64	aliased	`{your-company-id}`	Your own Company's identifier.

DELETE/users/sessions

Terminates a SessionFull and forces the User to log back in.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.
session	Session	An object which contains the SessionFull's handle, related User login, and owning Company id.
session.company	uint64? see: Company.id	Identifier of the Company to which this object belongs
session.expiry	datetime	A timestamp for when the Session will expire.
session.handle	string	A "handle" identifying a resource.
session.login	string see: User.login	The User to which the Session belongs.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number,
	"session": {
		"company": number,
		"expiry": string,
		"handle": string,
		"login": string
	}
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a session object, or it is invalid.
400	3	The session object does not contain a handle, or it is invalid.
401	5	You do not have permission to kill this SessionFull.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	19	The SessionFull was not found by its handle, or it is expired.

GET/users/sessions?handle={string}

Gets details of the specified SessionFull.

URL Parameters

Parameter	Type	Required	Description
handle	string	optional	Unique identifier of the SessionFull.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.
session	SessionFull	The requested SessionFull.
session.active	boolean	Indicator that this SessionFull is using at least one WebSocket connection.
session.company	uint64? see: Company.id	Identifier of the Company to which this object belongs
session.created	datetime	The timestamp from the moment this SessionFull was created.
session.expiry	datetime	A timestamp for when the Session will expire.
session.handle	string	A "handle" identifying a resource.
session.ipAddress	ipv4	The (most recent) IP address that used this SessionFull to connect.
session.lastActivity	datetime	A timestamp from the last command or call to the system.
session.lastCommand	string	The name or path of the last command executed.
session.login	string see: User.login	The User to which the Session belongs.
session.sockets	int32	The number of current-active WebSocket connections.
session.status	SessionStatus	This SessionFull's current state.
session.userAgent	string	The (most recent) software being used by this SessionFull.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number,
	"session": {
		"active": boolean,
		"company": number,
		"created": string,
		"expiry": string,
		"handle": string,
		"ipAddress": string,
		"lastActivity": string,
		"lastCommand": string,
		"login": string,
		"sockets": number,
		"status": string,
		"userAgent": string
	}
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a session object, or it is invalid.
400	3	The session object does not contain a handle, or it is invalid.
401	5	You do not have permission to view this session.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	19	The session was not found by its handle, or it is expired.

DELETE/users/sessions?handle={string}

Terminates a SessionFull and forces the User to log back in.

URL Parameters

Parameter	Type	Required	Description
handle	string	optional	Unique identifier of the SessionFull.

Response description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.
session	Session	An object which contains the SessionFull's handle, related User login, and owning Company id.
session.company	uint64? see: Company.id	Identifier of the Company to which this object belongs
session.expiry	datetime	A timestamp for when the Session will expire.
session.handle	string	A "handle" identifying a resource.
session.login	string see: User.login	The User to which the Session belongs.

Response structure

{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number,
	"session": {
		"company": number,
		"expiry": string,
		"handle": string,
		"login": string
	}
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a session object, or it is invalid.
400	3	The session object does not contain a handle, or it is invalid.
401	5	You do not have permission to kill this SessionFull.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	19	The SessionFull was not found by its handle, or it is expired.

White-labelling

GET/companies/{companyId}/reseller?includeDeleted=boolean

Gets details of the specified CompanyReseller.

URL Parameters

Parameter	Type	Required	Description
companyId	uint64	required	Unique identifier of the Company.
includeDeleted	boolean	optional	False by default, but when true the command will also return deleted objects.

Response description

Property	Type	Description
companyReseller	CompanyReseller	The requested CompanyReseller.
companyReseller.contactInfo	Object.<string, uint64> see: Contact.id maximum-count of keys: 100 for values see: Contact.id	A list of Contacts for company specific things like Technical Support, Billing, etc...
companyReseller.domain	string maximum-length: 100	The URN and path to the instance of v4. It does not contain the protocol because all instances are required to be HTTPS.
companyReseller.favourite	string maximum-length: 200	The name of the icon file used for browser bookmarks.
companyReseller.gamut	Object.<string, ColourStyle> maximum-length of keys: 25	Colours used as templates for status tags, labels, and places.
companyReseller.graphics	Object.<string, codified> maximum-length of keys: 25 maximum-length of values: 30	A list of symbol names and their corresponding FontAwesome icon names.
companyReseller.icon	string maximum-length: 200	The name of the image uploaded as the logo (used for collapsed/mobile view).
companyReseller.id	uint64 see: Company.id	Unique identifier of the Company.
companyReseller.languages	Array.<codified> maximum-length of values: 5	A list of supported languages for your customers.
companyReseller.logo	string maximum-length: 200	The name of the image uploaded as the logo (used for regular view).
companyReseller.notifyEmail	NotificationServerEmail	The server used for notification and conversational email messages sent and received by the system.
companyReseller.notifyEmail.incomingAddress	string	The domain or IP address of the incoming email server.
companyReseller.notifyEmail.incomingLogin	string	The username used to login to the incoming email server.
companyReseller.notifyEmail.incomingMessageNumber	uint32	IMAP message sequence number so only recent messages are retrieved.
companyReseller.notifyEmail.incomingPort	uint16	The port number of the incoming email server.
companyReseller.notifyEmail.incomingSecure	boolean	Is the incoming email server using a secure SSL/TLS connection (it should).
companyReseller.notifyEmail.incomingType	string	The type of incoming protocol to use (IMAP or POP3).
companyReseller.notifyEmail.outgoingAddress	string	The domain or IP address of the outgoing email server.
companyReseller.notifyEmail.outgoingLogin	string	The username used to login to the outgoing email server.
companyReseller.notifyEmail.outgoingPort	uint16	The port number of the outgoing email server.
companyReseller.notifyEmail.outgoingReplyTo	email	An optional field which can be set as the "sent from" and/or "reply-to" address.
companyReseller.notifyEmail.outgoingSecure	boolean	Is the outgoing email server using a secure SSL/TLS connection (it should).
companyReseller.notifyEmail.outgoingType	string	The type of outgoing protocol to use (only SMTP).
companyReseller.notifySms	NotificationServerSms	Definition for load-balanced outbound SMS numbers for the reseller.
companyReseller.notifySms.notifyLimit	uint16	A per-number/per-day limit on the amount of Notifications sent.
companyReseller.notifySms.phoneNumbers	Object.<string, Array.<phone>> fixed length of keys: 2	All phone numbers listed by the country (using two-digit ISO 3166-1 alpha-2 country codes) they each serve.
companyReseller.parent	uint64 see: Company.id	The unique identifier of this company's parent organization.
companyReseller.processedUtc	datetime	When the was change procesed.
companyReseller.recoverBody	string	The body of the email sent to a user requesting a password reset.
companyReseller.recoverIsHtml	boolean
companyReseller.recoverSubject	string	The subject of the email sent to a user requesting a password reset.
companyReseller.serviceName	string maximum-length: 150	The name of the branded service being provided to the seller's customers.
companyReseller.termsPreamble	string	A preamble to the general terms and conditions offered by Fleet Freedom.
companyReseller.termsUpdated	datetime	The date and time when the terms were updated. This will promt users who are logging-in to re-agree to the new terms
companyReseller.updated		by: login, from: monster
companyReseller.v	Array.<uint32>	Object version keys used to validate synchronization for all object properties.
companyReseller.website	Object.<string, colour> maximum-length of keys: 25 maximum-length of values: 22	Themed colours used in the web-based UI.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"companyReseller": {
		"contactInfo": {
			string: number
		},
		"domain": string,
		"favourite": string,
		"gamut": {
			string: {
				"fill": string,
				"stroke": string
			}
		},
		"graphics": {
			string: string
		},
		"icon": string,
		"id": number,
		"languages": [
			string
		],
		"logo": string,
		"notifyEmail": {
			"incomingAddress": string,
			"incomingLogin": string,
			"incomingMessageNumber": number,
			"incomingPort": number,
			"incomingSecure": boolean,
			"incomingType": string,
			"outgoingAddress": string,
			"outgoingLogin": string,
			"outgoingPort": number,
			"outgoingReplyTo": string,
			"outgoingSecure": boolean,
			"outgoingType": string
		},
		"notifySms": {
			"notifyLimit": number,
			"phoneNumbers": {
				string: [
					number
				]
			}
		},
		"parent": number,
		"processedUtc": string,
		"recoverBody": string,
		"recoverIsHtml": boolean,
		"recoverSubject": string,
		"serviceName": string,
		"termsPreamble": string,
		"termsUpdated": string,
		"updated": {
		},
		"v": [
			number
		],
		"website": {
			string: string
		}
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
401	5	You do not have permission to view this Company.
401	5	You do not have permission to view this CompanyReseller.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company was not found by its unique identifier.
404	28	The CompanyReseller was not found by its unique identifier.

POST/companies/{companyId}/reseller

Adds or updates the CompanyReseller to a Company.

URL Parameters

Parameter	Type	Required	Description
companyId	uint64	required	Unique identifier of the Company. This value is optional, and ignored by the command.

HTTP Request body description

Property	Type	Required	Description
companyReseller	Object.<string, ?>	always	A simple object to contain the CompanyReseller parameters.
companyReseller.contactInfo	Object.<string, uint64?> maximum-count of keys: 100 for values see: Contact.id	optional	A list of Contacts for company specific things like Technical Support, Billing, etc...
companyReseller.domain	string maximum-length: 100	create	The URN and path to the instance of v4. It does not contain the protocol because all instances are required to be HTTPS.
companyReseller.favourite	string maximum-length: 200	optional	The name of the icon file used for browser bookmarks.
companyReseller.gamut	Object.<string, ColourStyle> maximum-length of keys: 25	create	Colours used as templates for status tags, labels, and places.
companyReseller.graphics	Object.<string, codified> maximum-length of keys: 25 maximum-length of values: 30	create	A list of symbol names and their corresponding FontAwesome icon names.
companyReseller.icon	string maximum-length: 200	create	The name of the image uploaded as the logo (used for collapsed/mobile view).
companyReseller.id	uint64	always	The unique identifier of the company you want to update.
companyReseller.languages	Array.<codified> maximum-length of values: 5	optional	A list of supported languages for your customers.
companyReseller.logo	string maximum-length: 200	create	The name of the image uploaded as the logo (used for regular view).
companyReseller.notifyEmail	Object.<string, ?>	create	Settings for sending and receiving email notifcations and asset messages.
companyReseller.notifyEmail.incomingAddress	string	optional	The domain or IP address of the incoming email server.
companyReseller.notifyEmail.incomingLogin	string	optional	The username used to login to the incoming email server.
companyReseller.notifyEmail.incomingMessageNumber	uint32?	optional	IMAP message sequence number so only recent messages are retrieved.
companyReseller.notifyEmail.incomingPassword	string	optional	The password used to login to the incoming email server.
companyReseller.notifyEmail.incomingPort	uint16?	optional	The port number of the incoming email server.
companyReseller.notifyEmail.incomingSecure	boolean	optional	Is the incoming email server using a secure SSL/TLS connection (it should).
companyReseller.notifyEmail.incomingType	string	optional	The type of incoming protocol to use (IMAP or POP3).
companyReseller.notifyEmail.outgoingAddress	string	optional	The domain or IP address of the outgoing email server.
companyReseller.notifyEmail.outgoingLogin	string	optional	The username used to login to the outgoing email server.
companyReseller.notifyEmail.outgoingPassword	string	optional	The password used to login to the outgoing email server.
companyReseller.notifyEmail.outgoingPort	uint16?	optional	The port number of the outgoing email server.
companyReseller.notifyEmail.outgoingReplyTo	email	optional	An optional field which can be set as the "sent from" and/or "reply-to" address.
companyReseller.notifyEmail.outgoingSecure	boolean	optional	Is the outgoing email server using a secure SSL/TLS connection (it should).
companyReseller.notifySms	Object.<string, ?>	create	Settings for sending and receiving SMS notifcations and asset messages.
companyReseller.notifySms.notifyLimit	uint16?	optional	A per-number/per-day limit on the amount of Notifications sent.
companyReseller.notifySms.phoneNumbers	Object.<string, Array.<phone>> fixed length of keys: 2	optional	All phone numbers listed by the country (using two-digit ISO 3166-1 alpha-2 country codes) they each serve.
companyReseller.recoverBody	string	create	The body of the email sent to a user requesting a password reset.
companyReseller.recoverIsHtml	boolean	optional
companyReseller.recoverSubject	string	optional	The subject of the email sent to a user requesting a password reset.
companyReseller.serviceName	string maximum-length: 150	create	The name of the branded service being provided to the seller's customers.
companyReseller.termsPreamble	string	optional	A small body of text added as a preamble for the Trak-iT Wireless Inc. terms of service.
companyReseller.termsUpdated	datetime	optional	A timestamp from when the preamble was changed.
companyReseller.v	Array.<int32>	optional
companyReseller.website	Object.<string, colour> maximum-length of keys: 25 maximum-length of values: 22	create	Themed colours used in the web-based UI.
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"companyReseller": {
		"contactInfo": {
			string: number
		},
		"domain": string,
		"favourite": string,
		"gamut": {
			string: {
				"fill": string,
				"stroke": string
			}
		},
		"graphics": {
			string: string
		},
		"icon": string,
		"id": number,
		"languages": [
			string
		],
		"logo": string,
		"notifyEmail": {
			"incomingAddress": string,
			"incomingLogin": string,
			"incomingMessageNumber": number,
			"incomingPassword": string,
			"incomingPort": number,
			"incomingSecure": boolean,
			"incomingType": string,
			"outgoingAddress": string,
			"outgoingLogin": string,
			"outgoingPassword": string,
			"outgoingPort": number,
			"outgoingReplyTo": string,
			"outgoingSecure": boolean
		},
		"notifySms": {
			"notifyLimit": number,
			"phoneNumbers": {
				string: [
					number
				]
			}
		},
		"recoverBody": string,
		"recoverIsHtml": boolean,
		"recoverSubject": string,
		"serviceName": string,
		"termsPreamble": string,
		"termsUpdated": string,
		"v": [
			number
		],
		"website": {
			string: string
		}
	},
	"reqId": number
}

Response description

Property	Type	Description
companyReseller	RespIdParent	An object which contains the "id" and "company" keys.
companyReseller.id	uint64?	Identifier given as input for the command.
companyReseller.parent	uint64?	Identifier of the parent to which this company belongs
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"companyReseller": {
		"id": number,
		"parent": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a companyReseller object, or it is invalid.
400	3	No valid changes would be performed.
400	3	The value for companyReseller.notifyEmail.incomingType was invalid. It can only be `IMAP` or `POP3`.
400	3	The value for companyReseller.notifyEmail.outgoingReplyTo was not valid email address.
400	3	One of the keys in the companyReseller.notifySms.phoneNumbers object is blank.
400	3	One of the values in the companyReseller.notifySms.phoneNumbers object is not valid.
400	3	During create: When adding a CompanyReseller, the companyReseller.id was not given.
400	3	During create: When adding a CompanyReseller, the companyReseller.serviceName was not given or was blank.
400	3	During create: When adding a CompanyReseller, the companyReseller.logo was not given.
400	3	During create: When adding a CompanyReseller, the companyReseller.icon was not given.
400	3	During create: When adding a CompanyReseller, the companyReseller.domain was not given.
400	3	During create: When adding a CompanyReseller, the companyReseller.website was not given or was invalid.
400	3	During create: When adding a CompanyReseller, the companyReseller.graphics was not given or was invalid.
400	3	During create: When adding a CompanyReseller, the companyReseller.gamut was not given or was invalid.
400	3	During create: When adding a CompanyReseller, the companyReseller.recoverBody was not given or was blank.
400	3	During update: When updating the CompanyReseller, the v was not an array, or contained too few numbers.
400	3	During update: When updating the CompanyReseller, the companyReseller.serviceName was given as blank or white-space.
400	3	During update: When updating the CompanyReseller, the companyReseller.logo was given as blank or white-space.
400	3	During update: When updating the CompanyReseller, the companyReseller.icon was given as blank or white-space.
400	3	During update: When updating the CompanyReseller, the companyReseller.domain was given as blank or white-space.
401	5	You do not have permission to add a CompanyReseller.
401	5	You do not have permission to update the CompanyReseller.
400	6	During update: When updating a CompanyReseller, an incorrect v value was given as input.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company was not found by its unique identifier.
404	106	During update: The CompanyReseller was not found by its unique identifier.
409	130	The resulting CompanyReseller.recoverSubject and CompanyReseller.recoverBody do not contain the required `%GUID%`.
409	130	During update: When updating the CompanyReseller, the resulting NotificationServerEmail would be invalid.
409	130	During update: When updating the CompanyReseller, the resulting NotificationServerSms would be invalid.

DELETE/companies/{companyId}/reseller

Deletes an existing CompanyReseller.

URL Parameters

Parameter	Type	Required	Description
companyId	uint64	required	Unique identifier of the Company.

Response description

Property	Type	Description
companyReseller	RespParentDeleted	An object which contains the company's unique identifier and deleted status.
companyReseller.deleted	boolean	Flag showing if the object is deleted.
companyReseller.id	uint64?	Identifier given as input for the command.
companyReseller.parent	uint64	Identifier of the parent to which the Company is a child.
companyReseller.v	Array.<uint32>
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"companyReseller": {
		"deleted": boolean,
		"id": number,
		"parent": number,
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a companyReseller object, or it is invalid.
400	3	The companyReseller object does not contain an id, or it is invalid.
401	5	You do not have permission to view this Company.
401	5	You do not have permission to delete this CompanyReseller.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company was not found by its unique identifier.
404	106	The CompanyReseller was not found by its unique identifier.

PATCH/companies/{companyId}/reseller/restore

Restores the specified CompanyReseller.

URL Parameters

Parameter	Type	Required	Description
companyId	uint64	required	Unique identifier of the Company.

HTTP Request body description

Property	Type	Required	Default	Description
company	ParamId	always		An object to contain the "id" key.
company.id	uint64	always		Identifier given as input for the command.
includeDeleted	boolean	optional	`false`	When true, the command will also return a deleted Company.
reqId	int32?	optional		Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"company": {
		"id": number
	},
	"includeDeleted": boolean,
	"reqId": number
}

Response description

Property	Type	Description
companyReseller	RespParentDeleted	An object which contains the company's unique identifier and deleted status.
companyReseller.deleted	boolean	Flag showing if the object is deleted.
companyReseller.id	uint64?	Identifier given as input for the command.
companyReseller.parent	uint64	Identifier of the parent to which the Company is a child.
companyReseller.v	Array.<uint32>
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"companyReseller": {
		"deleted": boolean,
		"id": number,
		"parent": number,
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
401	5	You do not have permission to view this Company.
401	5	You do not have permission to restore this CompanyReseller.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company was not found by its unique identifier.
404	106	The CompanyReseller was not found by its unique identifier.
400	107	The CompanyReseller was found, but is not marked as deleted.

GET/companies/reseller?includeDeleted=boolean

This request is an alias of /companies/{your-company-id}/reseller.

URL Parameters

Parameter	Type	Required	Default	Description
includeDeleted	boolean	optional	`false`	False by default, but when true the command will also return deleted objects.
your-company-id	uint64	aliased	`{your-company-id}`	Your own Company's identifier.

PATCH/companies/reseller

Adds or updates the CompanyReseller to a Company.

HTTP Request body description

Property	Type	Required	Description
companyReseller	Object.<string, ?>	always	A simple object to contain the CompanyReseller parameters.
companyReseller.contactInfo	Object.<string, uint64?> maximum-count of keys: 100 for values see: Contact.id	optional	A list of Contacts for company specific things like Technical Support, Billing, etc...
companyReseller.domain	string maximum-length: 100	create	The URN and path to the instance of v4. It does not contain the protocol because all instances are required to be HTTPS.
companyReseller.favourite	string maximum-length: 200	optional	The name of the icon file used for browser bookmarks.
companyReseller.gamut	Object.<string, ColourStyle> maximum-length of keys: 25	create	Colours used as templates for status tags, labels, and places.
companyReseller.graphics	Object.<string, codified> maximum-length of keys: 25 maximum-length of values: 30	create	A list of symbol names and their corresponding FontAwesome icon names.
companyReseller.icon	string maximum-length: 200	create	The name of the image uploaded as the logo (used for collapsed/mobile view).
companyReseller.id	uint64	always	The unique identifier of the company you want to update.
companyReseller.languages	Array.<codified> maximum-length of values: 5	optional	A list of supported languages for your customers.
companyReseller.logo	string maximum-length: 200	create	The name of the image uploaded as the logo (used for regular view).
companyReseller.notifyEmail	Object.<string, ?>	create	Settings for sending and receiving email notifcations and asset messages.
companyReseller.notifyEmail.incomingAddress	string	optional	The domain or IP address of the incoming email server.
companyReseller.notifyEmail.incomingLogin	string	optional	The username used to login to the incoming email server.
companyReseller.notifyEmail.incomingMessageNumber	uint32?	optional	IMAP message sequence number so only recent messages are retrieved.
companyReseller.notifyEmail.incomingPassword	string	optional	The password used to login to the incoming email server.
companyReseller.notifyEmail.incomingPort	uint16?	optional	The port number of the incoming email server.
companyReseller.notifyEmail.incomingSecure	boolean	optional	Is the incoming email server using a secure SSL/TLS connection (it should).
companyReseller.notifyEmail.incomingType	string	optional	The type of incoming protocol to use (IMAP or POP3).
companyReseller.notifyEmail.outgoingAddress	string	optional	The domain or IP address of the outgoing email server.
companyReseller.notifyEmail.outgoingLogin	string	optional	The username used to login to the outgoing email server.
companyReseller.notifyEmail.outgoingPassword	string	optional	The password used to login to the outgoing email server.
companyReseller.notifyEmail.outgoingPort	uint16?	optional	The port number of the outgoing email server.
companyReseller.notifyEmail.outgoingReplyTo	email	optional	An optional field which can be set as the "sent from" and/or "reply-to" address.
companyReseller.notifyEmail.outgoingSecure	boolean	optional	Is the outgoing email server using a secure SSL/TLS connection (it should).
companyReseller.notifySms	Object.<string, ?>	create	Settings for sending and receiving SMS notifcations and asset messages.
companyReseller.notifySms.notifyLimit	uint16?	optional	A per-number/per-day limit on the amount of Notifications sent.
companyReseller.notifySms.phoneNumbers	Object.<string, Array.<phone>> fixed length of keys: 2	optional	All phone numbers listed by the country (using two-digit ISO 3166-1 alpha-2 country codes) they each serve.
companyReseller.recoverBody	string	create	The body of the email sent to a user requesting a password reset.
companyReseller.recoverIsHtml	boolean	optional
companyReseller.recoverSubject	string	optional	The subject of the email sent to a user requesting a password reset.
companyReseller.serviceName	string maximum-length: 150	create	The name of the branded service being provided to the seller's customers.
companyReseller.termsPreamble	string	optional	A small body of text added as a preamble for the Trak-iT Wireless Inc. terms of service.
companyReseller.termsUpdated	datetime	optional	A timestamp from when the preamble was changed.
companyReseller.v	Array.<int32>	optional
companyReseller.website	Object.<string, colour> maximum-length of keys: 25 maximum-length of values: 22	create	Themed colours used in the web-based UI.
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"companyReseller": {
		"contactInfo": {
			string: number
		},
		"domain": string,
		"favourite": string,
		"gamut": {
			string: {
				"fill": string,
				"stroke": string
			}
		},
		"graphics": {
			string: string
		},
		"icon": string,
		"id": number,
		"languages": [
			string
		],
		"logo": string,
		"notifyEmail": {
			"incomingAddress": string,
			"incomingLogin": string,
			"incomingMessageNumber": number,
			"incomingPassword": string,
			"incomingPort": number,
			"incomingSecure": boolean,
			"incomingType": string,
			"outgoingAddress": string,
			"outgoingLogin": string,
			"outgoingPassword": string,
			"outgoingPort": number,
			"outgoingReplyTo": string,
			"outgoingSecure": boolean
		},
		"notifySms": {
			"notifyLimit": number,
			"phoneNumbers": {
				string: [
					number
				]
			}
		},
		"recoverBody": string,
		"recoverIsHtml": boolean,
		"recoverSubject": string,
		"serviceName": string,
		"termsPreamble": string,
		"termsUpdated": string,
		"v": [
			number
		],
		"website": {
			string: string
		}
	},
	"reqId": number
}

Response description

Property	Type	Description
companyReseller	RespIdParent	An object which contains the "id" and "company" keys.
companyReseller.id	uint64?	Identifier given as input for the command.
companyReseller.parent	uint64?	Identifier of the parent to which this company belongs
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"companyReseller": {
		"id": number,
		"parent": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a companyReseller object, or it is invalid.
400	3	No valid changes would be performed.
400	3	The value for companyReseller.notifyEmail.incomingType was invalid. It can only be `IMAP` or `POP3`.
400	3	The value for companyReseller.notifyEmail.outgoingReplyTo was not valid email address.
400	3	One of the keys in the companyReseller.notifySms.phoneNumbers object is blank.
400	3	One of the values in the companyReseller.notifySms.phoneNumbers object is not valid.
400	3	During create: When adding a CompanyReseller, the companyReseller.id was not given.
400	3	During create: When adding a CompanyReseller, the companyReseller.serviceName was not given or was blank.
400	3	During create: When adding a CompanyReseller, the companyReseller.logo was not given.
400	3	During create: When adding a CompanyReseller, the companyReseller.icon was not given.
400	3	During create: When adding a CompanyReseller, the companyReseller.domain was not given.
400	3	During create: When adding a CompanyReseller, the companyReseller.website was not given or was invalid.
400	3	During create: When adding a CompanyReseller, the companyReseller.graphics was not given or was invalid.
400	3	During create: When adding a CompanyReseller, the companyReseller.gamut was not given or was invalid.
400	3	During create: When adding a CompanyReseller, the companyReseller.recoverBody was not given or was blank.
400	3	During update: When updating the CompanyReseller, the v was not an array, or contained too few numbers.
400	3	During update: When updating the CompanyReseller, the companyReseller.serviceName was given as blank or white-space.
400	3	During update: When updating the CompanyReseller, the companyReseller.logo was given as blank or white-space.
400	3	During update: When updating the CompanyReseller, the companyReseller.icon was given as blank or white-space.
400	3	During update: When updating the CompanyReseller, the companyReseller.domain was given as blank or white-space.
401	5	You do not have permission to add a CompanyReseller.
401	5	You do not have permission to update the CompanyReseller.
400	6	During update: When updating a CompanyReseller, an incorrect v value was given as input.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company was not found by its unique identifier.
404	106	During update: The CompanyReseller was not found by its unique identifier.
409	130	The resulting CompanyReseller.recoverSubject and CompanyReseller.recoverBody do not contain the required `%GUID%`.
409	130	During update: When updating the CompanyReseller, the resulting NotificationServerEmail would be invalid.
409	130	During update: When updating the CompanyReseller, the resulting NotificationServerSms would be invalid.

DELETE/companies/reseller

Deletes an existing CompanyReseller.

Response description

Property	Type	Description
companyReseller	RespParentDeleted	An object which contains the company's unique identifier and deleted status.
companyReseller.deleted	boolean	Flag showing if the object is deleted.
companyReseller.id	uint64?	Identifier given as input for the command.
companyReseller.parent	uint64	Identifier of the parent to which the Company is a child.
companyReseller.v	Array.<uint32>
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"companyReseller": {
		"deleted": boolean,
		"id": number,
		"parent": number,
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a companyReseller object, or it is invalid.
400	3	The companyReseller object does not contain an id, or it is invalid.
401	5	You do not have permission to view this Company.
401	5	You do not have permission to delete this CompanyReseller.
401	7	You cannot execute this command because your session has expired.
401	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	28	The Company was not found by its unique identifier.
404	106	The CompanyReseller was not found by its unique identifier.