REST Reference

Download JSDoc Helper
©2023 Trak-iT Wireless Inc.
Updated Tuesday April 25, 2023 03:45PM
Version 4.13.12
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.
502	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.
502	8	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
includeMessages	boolean	optional	`false`	False by default, but can be overridden.
includeTasks	boolean	optional	`false`	False by default, but can be overridden.
your-company-id	uint64	aliased	`{your-company-id}`	Your own Company's identifier.

PATCH/assets

Creates a new, or updates an existing Asset.

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.
502	8	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.
502	8	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		When true, the command will also return deleted objects.
includeMessages	boolean	optional	`false`	When true, the command will also return AssetMessages for the asset.
includeTasks	boolean	optional	`false`	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.tasks Deprecated	Array.<DispatchTask>	The current list of tasks assigned to this asset.
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.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.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,
			"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,
					"reference": string,
					"references": {
						string: string
					},
					"signatory": string,
					"signature": boolean,
					"status": string,
					"v": [
						number
					]
				}
			],
			"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,
				"readBy": string,
				"status": string,
				"subject": string,
				"to": string,
				"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
			}
		},
		"providers": [
			string
		],
		"reference": string,
		"references": {
			string: string
		},
		"relationships": [
			number
		],
		"tags": [
			string
		],
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a 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.
502	8	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.
502	8	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.
502	8	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.

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.
502	8	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.

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.
502	8	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.

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.
502	8	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`..

PATCH/assets/revive

Revives (disables suspension on) an existing Asset.

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.
502	8	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.

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.
502	8	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
labels	string	optional		Labels to match the DispatchJob.
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		The largest valued id objects to retrieve.
includeArchive	boolean	optional		When true, the command will also return archived objects.
includeDeleted	boolean	optional		When true, the command will also return deleted objects.
includeMessages	boolean	optional	`false`	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`	When true, the command will also return the DispatchTasks for the asset.
limit	uint16?	optional		Maximum number of objects in this response.
lowest	uint64?	optional		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,
				"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,
						"reference": string,
						"references": {
							string: string
						},
						"signatory": string,
						"signature": boolean,
						"status": string,
						"v": [
							number
						]
					}
				],
				"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,
					"readBy": string,
					"status": string,
					"subject": string,
					"to": string,
					"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
				}
			},
			"providers": [
				string
			],
			"reference": string,
			"references": {
				string: string
			},
			"relationships": [
				number
			],
			"tags": [
				string
			],
			"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.
502	8	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		The largest valued id objects to retrieve.
includeArchive	boolean	optional		When true, the command will also return archived objects.
includeDeleted	boolean	optional		When true, the command will also return deleted objects.
includeMessages	boolean	optional	`false`	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`	When true, the command will also return the DispatchTasks for the asset.
limit	uint16?	optional		Maximum number of objects in this response.
lowest	uint64?	optional		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,
				"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,
						"reference": string,
						"references": {
							string: string
						},
						"signatory": string,
						"signature": boolean,
						"status": string,
						"v": [
							number
						]
					}
				],
				"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,
					"readBy": string,
					"status": string,
					"subject": string,
					"to": string,
					"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
				}
			},
			"providers": [
				string
			],
			"reference": string,
			"references": {
				string: string
			},
			"relationships": [
				number
			],
			"tags": [
				string
			],
			"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.
502	8	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		The largest valued id objects to retrieve.
includeArchive	boolean	optional		When true, the command will also return archived objects.
includeDeleted	boolean	optional		When true, the command will also return deleted objects.
includeMessages	boolean	optional	`false`	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`	When true, the command will also return the DispatchTasks for the asset.
labels	string	required		Labels to match the DispatchJob.
limit	uint16?	optional		Maximum number of objects in this response.
lowest	uint64?	optional		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,
				"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,
						"reference": string,
						"references": {
							string: string
						},
						"signatory": string,
						"signature": boolean,
						"status": string,
						"v": [
							number
						]
					}
				],
				"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,
					"readBy": string,
					"status": string,
					"subject": string,
					"to": string,
					"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
				}
			},
			"providers": [
				string
			],
			"reference": string,
			"references": {
				string: string
			},
			"relationships": [
				number
			],
			"tags": [
				string
			],
			"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.
502	8	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

Gets the list of Assets for the specified Company only if the Asset.reference field is a match.

URL Parameters

Parameter	Type	Required	Default	Description
companyId	uint64	required		Unique identifier of the Company.
highest	uint64?	optional		The largest valued id objects to retrieve.
includeArchive	boolean	optional		When true, the command will also return archived objects.
includeDeleted	boolean	optional		When true, the command will also return deleted objects.
includeMessages	boolean	optional	`false`	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`	When true, the command will also return the DispatchTasks for the asset.
limit	uint16?	optional		Maximum number of objects in this response.
lowest	uint64?	optional		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.
reference	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,
				"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,
						"reference": string,
						"references": {
							string: string
						},
						"signatory": string,
						"signature": boolean,
						"status": string,
						"v": [
							number
						]
					}
				],
				"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,
					"readBy": string,
					"status": string,
					"subject": string,
					"to": string,
					"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
				}
			},
			"providers": [
				string
			],
			"reference": string,
			"references": {
				string: string
			},
			"relationships": [
				number
			],
			"tags": [
				string
			],
			"v": [
				number
			]
		}
	],
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reference": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
400	3	The reference is blank or null.
401	5	You do not have permission to view any Assets for this Company.
401	7	You cannot execute this command because your session has expired.
502	8	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
your-company-id	uint64	aliased	`{your-company-id}`	Your own Company's identifier.

PATCH/behaviours

Creates a new or updates an existing Behaviour.

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.
502	8	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.
502	8	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	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.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.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,
		"script": number,
		"targets": string,
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a 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.
502	8	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.
502	8	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.
502	8	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	The largest valued id objects to retrieve.
includeArchive	boolean	optional	When true, the command will also return archived objects.
includeDeleted	boolean	optional	When true, the command will also return deleted objects.
limit	uint16?	optional	Maximum number of objects in this response.
lowest	uint64?	optional	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,
			"script": 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 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.
502	8	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?includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

Gets the list of BehaviourLogs for the specified Behaviour.

URL Parameters

Parameter	Type	Required	Description
behaviourId	uint64	required	Unique identifier of the Behaviour.
highest	uint64?	optional	The largest valued id objects to retrieve.
includeArchive	boolean	optional	When true, the command will also return archived objects.
includeDeleted	boolean	optional	When true, the command will also return deleted objects.
limit	uint16?	optional	Maximum number of objects in this response.
lowest	uint64?	optional	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.
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.
502	8	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.

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.
502	8	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	The largest valued id objects to retrieve.
includeArchive	boolean	optional	When true, the command will also return archived objects.
includeDeleted	boolean	optional	When true, the command will also return deleted objects.
limit	uint16?	optional	Maximum number of objects in this response.
lowest	uint64?	optional	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,
			"script": 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 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.
502	8	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}&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	The largest valued id objects to retrieve.
includeArchive	boolean	optional	When true, the command will also return archived objects.
includeDeleted	boolean	optional	When true, the command will also return deleted objects.
limit	uint16?	optional	Maximum number of objects in this response.
lowest	uint64?	optional	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.
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.
502	8	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
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.

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.
502	8	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.
502	8	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	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.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.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
			}
		},
		"source": string,
		"stroke": string,
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a 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.
502	8	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.
502	8	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.
502	8	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	The largest valued id objects to retrieve.
includeArchive	boolean	optional	When true, the command will also return archived objects.
includeDeleted	boolean	optional	When true, the command will also return deleted objects.
limit	uint16?	optional	Maximum number of objects in this response.
lowest	uint64?	optional	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,
			"script": number,
			"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.
502	8	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?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	The largest valued id objects to retrieve.
includeArchive	boolean	optional	When true, the command will also return archived objects.
includeDeleted	boolean	optional	When true, the command will also return deleted objects.
limit	uint16?	optional	Maximum number of objects in this response.
lowest	uint64?	optional	The smallest valued id objects to retrieve.
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.
502	8	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.

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.
502	8	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	The largest valued id objects to retrieve.
includeArchive	boolean	optional	When true, the command will also return archived objects.
includeDeleted	boolean	optional	When true, the command will also return deleted objects.
limit	uint16?	optional	Maximum number of objects in this response.
lowest	uint64?	optional	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,
			"script": number,
			"targets": string,
			"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.
502	8	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	The largest valued id objects to retrieve.
includeArchive	boolean	optional	When true, the command will also return archived objects.
includeDeleted	boolean	optional	When true, the command will also return deleted objects.
limit	uint16?	optional	Maximum number of objects in this response.
lowest	uint64?	optional	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,
			"script": number,
			"targets": string,
			"v": [
				number
			]
		}
	],
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request 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.
502	8	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		The largest valued id objects to retrieve.
includeArchive	boolean	optional		When true, the command will also return archived objects.
includeDeleted	boolean	optional		When true, the command will also return deleted objects.
limit	uint16?	optional		Maximum number of objects in this response.
lowest	uint64?	optional		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
				}
			},
			"source": string,
			"stroke": string,
			"v": [
				number
			]
		}
	],
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request 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.
502	8	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.

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.
502	8	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.
502	8	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	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.target	uint64 see: Company.id	Unique identifier of the Company to which this rule pertains.
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,
		"target": number,
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a 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.
502	8	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.
502	8	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.
502	8	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	The largest valued id objects to retrieve.
includeArchive	boolean	optional	When true, the command will also return archived objects.
includeDeleted	boolean	optional	When true, the command will also return deleted objects.
limit	uint16?	optional	Maximum number of objects in this response.
lowest	uint64?	optional	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,
			"profile": number,
			"reference": string,
			"sku": string,
			"start": string,
			"suspended": boolean,
			"targets": string,
			"v": [
				number
			]
		}
	],
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a 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.
502	8	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	A timestamp for the earliest objects (by dts) to retrieve.
before	datetime	optional	A timestamp for the latest objects (by dts) to retrieve.
includeArchive	boolean	optional	When true, the command will also return archived objects.
includeDeleted	boolean	optional	When true, the command will also return deleted objects.
limit	uint16?	optional	Maximum number of objects in this response.
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,
			"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,
			"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.
502	8	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.

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.
502	8	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	The largest valued id objects to retrieve.
includeArchive	boolean	optional	When true, the command will also return archived objects.
includeDeleted	boolean	optional	When true, the command will also return deleted objects.
limit	uint16?	optional	Maximum number of objects in this response.
lowest	uint64?	optional	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,
			"profile": number,
			"reference": string,
			"service": string,
			"sku": string,
			"start": string,
			"suspended": boolean,
			"targets": string,
			"v": [
				number
			]
		}
	],
	"message": string,
	"reqId": number
}

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a 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.
502	8	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.

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.
502	8	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.
502	8	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	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.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.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,
		"profile": number,
		"reference": string,
		"sku": string,
		"start": string,
		"suspended": boolean,
		"targets": string,
		"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.
502	8	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.
502	8	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.
502	8	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.

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.
502	8	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
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.
502	8	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	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.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.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,
		"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,
		"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.
502	8	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.
502	8	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.

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.
502	8	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.

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.
502	8	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.
502	8	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	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.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.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,
		"profile": number,
		"reference": string,
		"service": string,
		"sku": string,
		"start": string,
		"suspended": boolean,
		"targets": string,
		"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.
502	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	113	The BillableHostingRule was not found by its unique identifier.

POST/billing/profiles/rules/{ruleId}

Creates new or updates an existing BillableHostingRule.

URL Parameters

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

HTTP Request body description

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

HTTP Request body structure

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

Response description

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

Response structure

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

Possible exceptions

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

DELETE/billing/profiles/rules/{ruleId}

Deletes an existing BillableHostingRule.

URL Parameters

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

Response description

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

Response structure

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

Possible exceptions

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

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

Restores the specified BillableHostingRule to its previous version.

URL Parameters

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

Response description

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

Response structure

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

Possible exceptions

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

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

Gets the list of BillingProfiles for the specified Company.

URL Parameters

Parameter	Type	Required	Description
companyId	uint64	required	Unique identifier of the Company.
highest	uint64?	optional	The largest valued id objects to retrieve.
includeArchive	boolean	optional	When true, the command will also return archived objects.
includeDeleted	boolean	optional	When true, the command will also return deleted objects.
limit	uint16?	optional	Maximum number of objects in this response.
lowest	uint64?	optional	The smallest valued id objects to retrieve.

Response description

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

Response structure

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

Possible exceptions

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

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

Gets the list of BillingReports for the specified Company.

URL Parameters

Parameter	Type	Required	Description
after	datetime	optional	A timestamp for the earliest objects (by dts) to retrieve.
before	datetime	optional	A timestamp for the latest objects (by dts) to retrieve.
companyId	uint64	required	Unique identifier of the Company.
includeArchive	boolean	optional	When true, the command will also return archived objects.
includeDeleted	boolean	optional	When true, the command will also return deleted objects.
limit	uint16?	optional	Maximum number of objects in this response.

Response description

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

Response structure

{
	"billingReports": [
		{
			"billee": number,
			"breakdown": [
				{
					"licenses": [
						{
							"billableDays": number,
							"cost": number,
							"created": string,
							"deleted": string,
							"firmware": string,
							"kind": string,
							"name": string,
							"notes": string,
							"phoneNumber": number,
							"provider": string,
							"total": number
						}
					],
					"services": [
						{
							"asset": number,
							"billableDays": number,
							"cost": number,
							"created": string,
							"deleted": string,
							"kind": string,
							"labels": [
								string
							],
							"name": string,
							"notes": string,
							"phoneNumbers": [
								number
							],
							"providers": [
								string
							],
							"restored": string,
							"revived": string,
							"suspended": string,
							"suspendedCost": number,
							"suspendedDays": number,
							"total": number,
							"updatedDts": string
						}
					],
					"target": number
				}
			],
			"company": number,
			"currency": string,
			"endDate": string,
			"error": string,
			"id": number,
			"name": string,
			"notes": string,
			"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,
			"v": [
				number
			]
		}
	],
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

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

Companies

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

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

URL Parameters

Parameter	Type	Required	Default	Description
includeParent	boolean	optional	`true`	Defaults to true for this alias.
tree	boolean	optional	`false`	Defaults to false for this alias.
your-company-id	uint64	aliased	`{your-company-id}`	Your own Company's identifier.

PATCH/companies

Creates a new or updates an existing Company.

Response description

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

Response structure

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

Possible exceptions

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

DELETE/companies

Deletes an existing Company.

Response description

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

Response structure

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

Possible exceptions

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

GET/companies/{companyId}?includeDeleted=boolean

Gets details of the specified Company.

URL Parameters

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

Response description

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

Response structure

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

Possible exceptions

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

POST/companies/{companyId}

Creates a new or updates an existing Company.

URL Parameters

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

HTTP Request body description

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

HTTP Request body structure

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

Response description

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

Response structure

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

Possible exceptions

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

DELETE/companies/{companyId}

Deletes an existing Company.

URL Parameters

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

Response description

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

Response structure

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

Possible exceptions

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

PATCH/companies/{companyId}/restore

Restores the specified Company.

URL Parameters

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

Response description

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

Response structure

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

Possible exceptions

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

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

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

URL Parameters

Parameter	Type	Required	Default	Description
companyId	uint64	required		Unique identifier of the Company.
highest	uint64?	optional		The largest valued id objects to retrieve.
includeArchive	boolean	optional		When true, the command will also return archived objects.
includeDeleted	boolean	optional		When true, the command will also return deleted objects.
includeParent	boolean	optional	`false`
limit	uint16?	optional		Maximum number of objects in this response.
lowest	uint64?	optional		The smallest valued id objects to retrieve.
tree	boolean	optional	`true`	When set to true, the parent Company is included in the results.

Response description

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

Response structure

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

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
401	5	You do not have permission to view this Company or child companies.
401	7	You cannot execute this command because your session has expired.
502	8	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}/tree?{keys=values}?tree=boolean&includeParent=boolean&includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number&{keys=values}

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

URL Parameters

Parameter	Type	Required	Default	Description
companyId	uint64	required		Unique identifier of the Company.
highest	uint64?	optional		The largest valued id objects to retrieve.
includeArchive	boolean	optional		When true, the command will also return archived objects.
includeDeleted	boolean	optional		When true, the command will also return deleted objects.
includeParent	boolean	optional	`false`
limit	uint16?	optional		Maximum number of objects in this response.
lowest	uint64?	optional		The smallest valued id objects to retrieve.
tree	boolean	optional	`true`	When set to true, the parent Company is included in the results.

Response description

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

Response structure

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

Possible exceptions

HTTP Status	Error Code	Description
400	3	The request does not contain a company object, or it is invalid.
400	3	The company object does not contain an id, or it is invalid.
400	3	The references is not an object, or it is invalid.
401	5	You do not have permission to view this Company or child companies.
401	7	You cannot execute this command because your session has expired.
502	8	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/tree?tree=boolean&includeParent=boolean&includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number

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

URL Parameters

Parameter	Type	Required	Default	Description
includeParent	boolean	optional	`true`	Defaults to true for this alias.
tree	boolean	optional	`true`	Defaults to true for this alias.
your-company-id	uint64	aliased	`{your-company-id}`	Your own Company's identifier.

Contacts

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

Gets the list of Contacts for the specified Company.

URL Parameters

Parameter	Type	Required	Description
companyId	uint64	required	Unique identifier of the Company.
highest	uint64?	optional	The largest valued id objects to retrieve.
includeArchive	boolean	optional	When true, the command will also return archived objects.
includeDeleted	boolean	optional	When true, the command will also return deleted objects.
limit	uint16?	optional	Maximum number of objects in this response.
lowest	uint64?	optional	The smallest valued id objects to retrieve.

Response description

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

Response structure

{
	"company": {
		"id": number
	},
	"contacts": [
		{
			"addresses": {
				string: string
			},
			"company": number,
			"dates": {
				string: string
			},
			"emails": {
				string: string
			},
			"id": number,
			"name": string,
			"notes": string,
			"options": {
				string: string
			},
			"otherNames": {
				string: string
			},
			"phones": {
				string: number
			},
			"pictures": [
				number
			],
			"roles": [
				string
			],
			"urls": {
				string: string
			},
			"v": [
				number
			]
		}
	],
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

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

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

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

URL Parameters

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

PATCH/contacts

Creates a new or updates an existing Contact.

Response description

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

Response structure

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

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a contact object, or it is invalid.
400	3	Not enough keys exist in the contact object.
400	3	During create: When creating a new Contact, a company was not given.
400	3	During create: When creating a new Contact, a name was not given, or it is invalid.
400	3	During update: When updating a Contact, the id was invalid.
400	3	During update: When updating a Contact, the name was given as blank.
400	3	During update: When updating a Contact, the v was not an array, or contained too few numbers.
400	3	One of the contact.otherNames keys or values is invalid. Returns an ErrorDetailInput as the `errorDetails`..
400	3	One of the contact.emails keys or values is invalid. Returns an ErrorDetailInput as the `errorDetails`..
400	3	One of the contact.phones keys or values is invalid. Returns an ErrorDetailInput as the `errorDetails`..
400	3	One of the contact.addresses keys or values is invalid. Returns an ErrorDetailInput as the `errorDetails`..
400	3	One of the contact.urls keys or values is invalid. Returns an ErrorDetailInput as the `errorDetails`..
400	3	One of the contact.dates keys or values is invalid. Returns an ErrorDetailInput as the `errorDetails`..
400	3	One of the contact.options keys or values is invalid. Returns an ErrorDetailInput as the `errorDetails`..
400	3	One of the contact.pictures values is invalid. Returns an ErrorDetailInput as the `errorDetails`..
401	5	You do not have permission to create a new Contact.
401	5	You do not have permission to update this Contact.
400	6	During update: When updating a Contact, an incorrect v value was given as input.
401	7	You cannot execute this command because your session has expired.
502	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	31	During update: The Contact was not found by its unique identifier.
404	69	One of the contact.pictures given as input in the Pictures array was not found. Returns an ErrorDetailBadIds as the `errorDetails`..
409	130	During update: When updating a Contact, the company was provided as a different value.

DELETE/contacts

Deletes an existing Contact.

Response description

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

Response structure

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

Possible exceptions

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

GET/contacts/{contactId}?includeDeleted=boolean

Gets details of the specified Contact.

URL Parameters

Parameter	Type	Required	Description
contactId	uint64	required	Unique identifier of the Contact.
includeDeleted	boolean	optional	When true, the command will also return deleted objects.

Response description

Property	Type	Description
contact	Contact	The requested Contact.
contact.addresses	Object.<string, string>	Mailing addresses. Use the object key like a name of the address. Example keys: Home, Work, Park, etc.
contact.company	uint64 see: Company.id	The company to which this contact belongs
contact.dates	Object.<string, datetime>	Date information. Use the object key like a name of the date. Example keys: Birthday, Started Date, Retired On, etc.
contact.emails	Object.<string, email> maximum-length of values: 254	Email addresses. Use the object key like a name of the address. Example keys: Home, Work, Support, Old, etc.
contact.id	uint64	Unique identifier of this contact.
contact.name	string maximum-length: 100	The person's name
contact.notes	string	Notes about this person.
contact.options	Object.<string, string>	Uncategorized information. Use the object keys and values however you'd like.
contact.otherNames	Object.<string, string> maximum-length of values: 254	A collection of other names this person might go by. Use the object key like a name identifier. Example keys: Initials, Nickname, Maiden Name, etc.
contact.phones	Object.<string, phone>	Phone numbers. Use the object key like a name of the phone number. Example keys: Mobile, Fax, Home, Office, etc.
contact.pictures	Array.<uint64> for values see: Picture.id	Pictures of this Contact.
contact.roles	Array.<string>	A list of roles they play in the Company.
contact.urls	Object.<string, url> maximum-length of values: 254	Websites and other online resources. Use the object key like a name of the address. Example keys: Downloads, Support, FTP, etc.
contact.v	Array.<uint32>	Object version keys used to validate synchronization for all object properties.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response structure

{
	"contact": {
		"addresses": {
			string: string
		},
		"company": number,
		"dates": {
			string: string
		},
		"emails": {
			string: string
		},
		"id": number,
		"name": string,
		"notes": string,
		"options": {
			string: string
		},
		"otherNames": {
			string: string
		},
		"phones": {
			string: number
		},
		"pictures": [
			number
		],
		"roles": [
			string
		],
		"urls": {
			string: string
		},
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

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

POST/contacts/{contactId}

Creates a new or updates an existing Contact.

URL Parameters

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

HTTP Request body description

Property	Type	Required	Description
contact	Object.<string, ?>	always	A simple object to contain the Contact parameters.
contact.addresses	Object.<string, string>	optional	Mailing addresses Use the object key like a name of the address. Example keys: Home, Work, Park, etc.
contact.company	uint64?	create	The Company to which this Contact belongs. After creation, this value is read-only.
contact.dates	Object.<string, datetime>	optional	Date information Use the object key like a name of the date. Example keys: Birthday, Started Date, Retired On, etc.
contact.emails	Object.<string, email> maximum-length of values: 254	optional	Email addresses Use the object key like a name of the address. Example keys: Home, Work, Support, Old, etc.
contact.id	uint64?	update	The unique identifier of the Contact you want to update.
contact.name	string maximum-length: 100	optional	Name for the Contact.
contact.notes	string	optional	Notes for the Contact.
contact.options	Object.<string, string>	optional	Uncategorized information Use the object keys and values however you'd like.
contact.otherNames	Object.<string, string> maximum-length of values: 254	optional	A collection of other names this person might go by. Use the object key like a name identifier. Example keys: Initials, Nickname, Maiden Name, etc.
contact.phones	Object.<string, phone?>	optional	Phone numbers. Use the object key like a name of the phone number. Example keys: Mobile, Fax, Home, Office, etc.
contact.pictures	Array.<uint64> for values see: Picture.id	optional	Pictures of this Contact.
contact.roles	Array.<codified>	optional	A list of roles they play in the Company.
contact.urls	Object.<string, url> maximum-length of values: 254	optional	Websites and other online resources Use the object key like a name of the address. Example keys: Downloads, Support, FTP, etc.
contact.v	Array.<int32>	optional
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

HTTP Request body structure

{
	"contact": {
		"addresses": {
			string: string
		},
		"company": number,
		"dates": {
			string: string
		},
		"emails": {
			string: string
		},
		"id": number,
		"name": string,
		"notes": string,
		"options": {
			string: string
		},
		"otherNames": {
			string: string
		},
		"phones": {
			string: number
		},
		"pictures": [
			number
		],
		"roles": [
			string
		],
		"urls": {
			string: string
		},
		"v": [
			number
		]
	},
	"reqId": number
}

Response description

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

Response structure

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

Possible exceptions

HTTP Status	Error Code	Description
500	2	A communication error occurred. If you receive this error, please contact technical support.
400	3	The request does not contain a contact object, or it is invalid.
400	3	Not enough keys exist in the contact object.
400	3	During create: When creating a new Contact, a company was not given.
400	3	During create: When creating a new Contact, a name was not given, or it is invalid.
400	3	During update: When updating a Contact, the id was invalid.
400	3	During update: When updating a Contact, the name was given as blank.
400	3	During update: When updating a Contact, the v was not an array, or contained too few numbers.
400	3	One of the contact.otherNames keys or values is invalid. Returns an ErrorDetailInput as the `errorDetails`..
400	3	One of the contact.emails keys or values is invalid. Returns an ErrorDetailInput as the `errorDetails`..
400	3	One of the contact.phones keys or values is invalid. Returns an ErrorDetailInput as the `errorDetails`..
400	3	One of the contact.addresses keys or values is invalid. Returns an ErrorDetailInput as the `errorDetails`..
400	3	One of the contact.urls keys or values is invalid. Returns an ErrorDetailInput as the `errorDetails`..
400	3	One of the contact.dates keys or values is invalid. Returns an ErrorDetailInput as the `errorDetails`..
400	3	One of the contact.options keys or values is invalid. Returns an ErrorDetailInput as the `errorDetails`..
400	3	One of the contact.pictures values is invalid. Returns an ErrorDetailInput as the `errorDetails`..
401	5	You do not have permission to create a new Contact.
401	5	You do not have permission to update this Contact.
400	6	During update: When updating a Contact, an incorrect v value was given as input.
401	7	You cannot execute this command because your session has expired.
502	8	You cannot execute this command because you are not logged in.
403	16	You cannot execute this command because your password has expired.
404	31	During update: The Contact was not found by its unique identifier.
404	69	One of the contact.pictures given as input in the Pictures array was not found. Returns an ErrorDetailBadIds as the `errorDetails`..
409	130	During update: When updating a Contact, the company was provided as a different value.

DELETE/contacts/{contactId}

Deletes an existing Contact.

URL Parameters

Parameter	Type	Required	Description
contactId	uint64	required	Unique identifier of the Contact.

Response description

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

Response structure

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

Possible exceptions

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

PATCH/contacts/{contactId}/restore

Restores the specified Contact.

URL Parameters

Parameter	Type	Required	Description
contactId	uint64	required	Unique identifier of the Contact.

Response description

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

Response structure

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

Possible exceptions

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

Dispatch

POST/assets/{assetId}/dispatch

Updates an existing AssetDispatch.

URL Parameters

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

HTTP Request body description

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

HTTP Request body structure

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

Response description

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

Response structure

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

Possible exceptions

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