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