Call our help line: 1 866-787-2548

REST Reference

Behaviours

Billing

Dispatch

File Hosting

Providers and Configurations

Reports

Users and Groups

API Definitions

GET/timezones

Gets a list of Timezones.
Response description
PropertyTypeDescription
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
timezonesArray.<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 StatusError CodeDescription
5002System Timezone list could not be retrieved.
If you receive this error, please contact technical support.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.

GET/timezones/{code}

Gets details of the specified Timezone.
URL Parameters
ParameterTypeRequiredDescription
codestringrequiredUnique identifier of the Timezone.
Response description
PropertyTypeDescription
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
timezoneTimezoneThe requested Timezone.
timezone.codecodifiedUnique timezone code
timezone.dstbooleanIndicates whether this timezone abides by daylight savings
timezone.namestringCommon timezone name
timezone.offsetint16Minutes 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 StatusError CodeDescription
4003The request does not contain a timezone object, or it is invalid.
4003The timezone object does not contain a code, or it is invalid.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
40462The Timezone was not found by its codified identifier.

Assets

GET/assets?includeMessages=boolean&includeTasks=boolean

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
ParameterTypeRequiredDefaultDescription
includeMessagesbooleanoptionalfalseFalse by default, but can be overridden.
includeTasksbooleanoptionalfalseFalse by default, but can be overridden.
your-company-iduint64aliased{your-company-id}Your own Company's identifier.

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

Gets details of the specified Asset.
URL Parameters
ParameterTypeRequiredDefaultDescription
assetIduint64requiredUnique identifier of the Asset.
includeMessagesbooleanoptionalfalseWhen true, the command will also return AssetMessages for the asset.
includeTasksbooleanoptionalfalseWhen true, the command will also return the AssetDispatch for the asset.
Response description
PropertyTypeDescription
assetAssetThe requested Asset.
asset.attributesObject.<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.companyuint64The company to which this asset belongs.
asset.dispatchAssetDispatchCurrent jobs dispatched and driving directions.
asset.dispatch.companyuint64The company to which this asset belongs.
asset.dispatch.directionsArray.<DispatchDirection>Driving directions and route path details.
asset.dispatch.iduint64Unique identifier of this asset.
asset.dispatch.jobsArray.<uint64>The current list of DispatchJobs assigned to the asset.
asset.dispatch.lastDispatcheddatetimeTimestamp 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.vArray.<uint32>Object version keys used to validate synchronization for all object properties.
asset.iconuint64
see: Icon.id
The icon that represents this asset on the map and in lists.
asset.iduint64Unique identifier of this asset.
asset.kindAssetTypeType of asset.
asset.labelsArray.<codified>
for values see: LabelStyle.code
Codified label names.
asset.messagesArray.<AssetMessage>A list of messages sent to or from this asset.
asset.messagingAddressstring
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.namestring
maximum-length: 100
This thing's name.
asset.notesstringNotes about it.
asset.odometerdoubleThe cumulative distance travelled in kilometres.
asset.picturesArray.<uint64>
for values see: Picture.id
A list of photos of this thing.
asset.placesObject.<uint64, AssetPlaceStatus>
for keys see: Place.id
The current state of this asset's interaction with known Places.
asset.positionPositionThe things GPS coordinates including speed, bearing, and street information.
asset.position.accuracyuint32?Threshold in meters for the accuracy of a position
asset.position.addressstringThe road segment description
asset.position.altitudedouble?Distance in meters from the sea level
asset.position.bearinguint16?Direction of travel
asset.position.dtsdatetimeThe Date/Time of the GPS reading
asset.position.latdouble?Latitude
asset.position.lngdouble?Longitude
asset.position.originstringProvider Identifier
asset.position.speeddouble?Speed
asset.position.speedLimitdouble?The posted speed limit for the road segment
asset.position.streetAddressStreetAddressA better description of the current road-segment
asset.position.streetAddress.citystringCity name.
asset.position.streetAddress.countrystring
fixed length: 2
Country code. Codes should be a value from ISO 3166-1 alpha-2.
asset.position.streetAddress.isTollbooleanIndicates that there is a toll for the current road segment.
asset.position.streetAddress.numberstringHouse number.
asset.position.streetAddress.postalstringPostal or zip code.
asset.position.streetAddress.provincestring
fixed length: 2
Province or state code. Codes should be a value from ISO 3166-2.
asset.position.streetAddress.regionstringRegion name.
asset.position.streetAddress.streetstringFull street name.
asset.providersArray.<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.referencesObject.<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.relationshipsArray.<uint64>
for values see: Asset.id
A list of assets related to this one; like a Person for a Vehicle (driver).
asset.tagsArray.<codified>
for values see: LabelStyle.code
The codified status tag names.
asset.vArray.<int32>
fixed count: 3
Object version keys used to validate synchronization for all object properties.
asset.v[0]int32The first element is for the AssetGeneral properties.
asset.v[1]int32The second element is for the AssetAdvanced properties.
asset.v[2]int32The third element is for the Asset.dispatch properties.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?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 StatusError CodeDescription
4003The request does not contain a asset object, or it is invalid.
4003The asset object does not contain an id, or it is invalid.
4015You do not have permission to view this Asset.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
40420The Asset was not found by its unique identifier.

POST/assets/{assetId}

Creates a new, or updates an existing Asset.
URL Parameters
ParameterTypeRequiredDescription
assetIduint64?optionalUnique identifier of the Asset. This value is optional, and ignored by the command.
HTTP Request body description
PropertyTypeRequiredDescription
assetObject.<string, ?>alwaysA simple object to contain the Asset parameters.
asset.attributesObject.<string, AssetAttribute>optionalAllows 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.colourcolour
maximum-length: 22
optionalThe pretty-pretty colour of this Vehicle or Trailer. Only applicable if asset.kind is AssetType.vehicle or AssetType.trailer.
asset.companyuint64?createThe identifier of the Company to which this Asset belongs. After creation, this value is read-only.
asset.contactuint64?create (for person)The contact card details for this Asset. Only applicable if asset.kind is AssetType.person.
asset.engineHoursdouble?optionalThe number of hours the engine has been running for this Vehicle. Only applicable if asset.kind is AssetType.vehicle.
asset.iconuint64?
see: Icon.id
createThe identifier of the Icon used to represent this Asset in the UI.
asset.iduint64?updateThe unique identifier of the Asset you want to update.
asset.kindAssetType?createThe kind of Asset being created. After creation, this value is read-only.
asset.labelsArray.<codified>
for values see: LabelStyle.code
optionalA list of codified label names to categorize/organize this Asset.
asset.makestringoptionalThe manufacturer of this Vehicle or Trailer. Only applicable if asset.kind is AssetType.vehicle or AssetType.trailer.
asset.messagingAddressstringoptionalThe 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.modelstringoptionalThe model of this Vehicle or Trailer. Only applicable if asset.kind is AssetType.vehicle or AssetType.trailer.
asset.namestring
maximum-length: 100
createName for the Asset.
asset.notesstringoptionalNotes for the Asset.
asset.odometerdouble?optionalThe distance travelled by this Asset. Can be a GPS odometer, OBD-II odometer, or other depending on scripts.
asset.picturesArray.<uint64>
for values see: Picture.id
optionalThe identifiers of Pictures of this Asset.
asset.platestringoptionalThe license plate of this Vehicle or Trailer. Only applicable if asset.kind is AssetType.vehicle or AssetType.trailer.
asset.referencesObject.<string, string>optionalName/value collections of custom fields used to refer to external systems. If the value is null, the references are removed from the Asset.
asset.relationshipsArray.<uint64>
for values see: Asset.id
optionalA list of related asset identifiers like a driver for a Vehicle, or Trailer for a truck.
asset.serialstringoptionalThe manufacturer's identification number of this Trailer. Only applicable if asset.kind is AssetType.vehicle.
asset.tagsArray.<string>optionalReplaces the Asset's status tags with the given list of codified tags.
asset.vArray.<int32>optional
asset.vinstringoptionalThe Vehicle Identification Number of this Vehicle. Only applicable if asset.kind is AssetType.trailer.
asset.yearuint16?optionalThe year this Vehicle or Trailer was built. Only applicable if asset.kind is AssetType.vehicle or AssetType.trailer.
reqIdint32?optionalIdentifier 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
PropertyTypeDescription
assetRespIdCompanyAn object which contains the "id" and "company" keys.
asset.companyuint64Identifier of the Company to which this object belongs.
asset.iduint64?Identifier given as input for the command.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?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 StatusError CodeDescription
5002A communication error occurred.
If you receive this error, please contact technical support.
4003The request does not contain a asset object, or it is invalid.
4003No valid changes would be performed.
4003During create: When creating a new Asset, a name was not given.
4003During create: When creating a new Asset, a company was not given.
4003During create: When creating a new Asset, an icon was not given.
4003During create (for person): When creating a new Person, a contact was not given.
4003During update: When updating an Asset, the name was given as null or blank.
4003During update: When updating an Asset, the v was not an array, or contained too few numbers.
4003During create: The kind value is not a known AssetType.
Returns an ErrorDetailEnum as the errorDetails..
4003One of the asset.attributes names is invalid.
Returns an ErrorDetailInput as the errorDetails..
4003One of the asset.attributes values is not null or an object.
Returns an ErrorDetailInput as the errorDetails..
4003The asset.attributes object is given, but empty.
Returns an ErrorDetailInput as the errorDetails..
4003The asset.messagingAddress contains values that cannot be parsed as a phone number or email address.
Returns an ErrorDetailInput as the errorDetails..
4003One of the asset.pictures given in the array cannot be parsed, or is a value less than zero.
Returns an ErrorDetailInput as the errorDetails..
4003The asset.references were not provided as null or an object.
Returns an ErrorDetailInput as the errorDetails..
4003One of the asset.relationships given in the array cannot be parsed, or is a value less than zero.
Returns an ErrorDetailInput as the errorDetails..
4003During create: When creating a new Asset, too many asset.references were given as input.
Returns an ErrorDetailMinMax as the errorDetails..
4015You do not have permission to create a new Asset.
4015You do not have permission to update this Asset.
4006During update: When updating an Asset, an incorrect v value was given as input.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
40420During update: When updating, the Asset was not found by its unique identifier.
40422One of the Assets given as input in the asset.relationships array was not found.
Returns an ErrorDetailBadIds as the errorDetails..
40431The asset.contact given as input was not found.
40433The asset.icon given as input was not found.
40469One of the asset.pictures given as input in the pictures array was not found.
Returns an ErrorDetailBadIds as the errorDetails..
40171During update: Changing the labels on this Asset in the requested way would grant you elevated access to it.
Returns an ErrorDetailEscalation as the errorDetails..
40396During update: When updating, the Asset is suspended. Before making changes to an Asset, it must be reactivated.
409130During update: When updating an Asset, the asset.company can not be changed.
409130During update: When updating an Asset, the asset.kind can not be changed.
409130During update: When updating an Asset, the resulting number of asset.references would be too high.

DELETE/assets/{assetId}

Deletes an existing Asset.
URL Parameters
ParameterTypeRequiredDescription
assetIduint64requiredUnique identifier of the Asset.
Response description
PropertyTypeDescription
assetRespDeletedAn object which contains the Asset's id, owning Company id, and deleted status.
asset.companyuint64Identifier of the Company to which this object belongs.
asset.deletedbooleanFlag showing if the object is deleted.
asset.iduint64?Identifier given as input for the command.
asset.vArray.<uint32>
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?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 StatusError CodeDescription
5002A communication error occurred.
If you receive this error, please contact technical support.
4003The request does not contain a asset object, or it is invalid.
4003The asset object does not contain an id, or it is invalid.
4015You do not have permission to delete this Asset.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
40420The Asset was not found by its unique identifier.

PATCH/assets/{assetId}/restore

Restores the specified Asset.
URL Parameters
ParameterTypeRequiredDescription
assetIduint64requiredUnique identifier of the Asset.
Response description
PropertyTypeDescription
assetRespDeletedAn object which contains the Asset's id, owning Company id, and deleted status.
asset.companyuint64Identifier of the Company to which this object belongs.
asset.deletedbooleanFlag showing if the object is deleted.
asset.iduint64?Identifier given as input for the command.
asset.vArray.<uint32>
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?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 StatusError CodeDescription
5002A communication error occurred.
If you receive this error, please contact technical support.
4003The request does not contain a asset object, or it is invalid.
4003The asset object does not contain an id, or it is invalid.
4015You do not have permission to restore this Asset.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
40420The Asset was not found by its unique identifier.
40021The Asset was found, but is not marked as deleted.

PATCH/assets/{assetId}/revive

Revives (disables suspension on) an existing Asset.
URL Parameters
ParameterTypeRequiredDescription
assetIduint64requiredUnique identifier of the Asset.
Response description
PropertyTypeDescription
assetRespSuspendedAn object which contains the Asset's unique identifier and suspended status.
asset.companyuint64Identifier of the Company to which this object belongs.
asset.iduint64?Identifier given as input for the command.
asset.suspendedbooleanFlag showing if the object is suspended.
asset.vArray.<uint32>
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?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 StatusError CodeDescription
5002A communication error occurred.
If you receive this error, please contact technical support.
4003The request does not contain a asset object, or it is invalid.
4003The asset object does not contain an id, or it is invalid.
4015You do not have permission to revive this Asset.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
40420The Asset was not found by its unique identifier.
40397The Asset was found, but is not marked as suspended.

PATCH/assets/{assetId}/suspend

Suspends an existing Asset.
URL Parameters
ParameterTypeRequiredDescription
assetIduint64requiredUnique identifier of the Asset.
Response description
PropertyTypeDescription
assetRespSuspendedAn object which contains the Asset's unique identifier and suspended status.
asset.companyuint64Identifier of the Company to which this object belongs.
asset.iduint64?Identifier given as input for the command.
asset.suspendedbooleanFlag showing if the object is suspended.
asset.vArray.<uint32>
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?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 StatusError CodeDescription
5002A communication error occurred.
If you receive this error, please contact technical support.
4003The request does not contain a asset object, or it is invalid.
4003The asset object does not contain an id, or it is invalid.
4015You do not have permission to suspended this Asset.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
40420The Asset was not found by its unique identifier.
40396The Asset was not found, but it is already marked as suspended.
40397The Asset was previously revived within the minimum period.
Returns an ErrorDetailLocked as the errorDetails..

GET/assets?labels={string}&includeMessages=boolean&includeTasks=boolean

This request is an alias of /companies/{your-company-id}/assets?labels={labels}.
URL Parameters
ParameterTypeRequiredDefaultDescription
labelsstringoptionalLabels to match the DispatchJob.
your-company-iduint64aliased{your-company-id}Your own Company's identifier.

GET/companies/{companyId}/assets?includeMessages=boolean&includeTasks=boolean

Gets the list of Assets for the specified Company.
URL Parameters
ParameterTypeRequiredDefaultDescription
companyIduint64requiredUnique identifier of the Company.
includeMessagesbooleanoptionalfalseWhen true, the command will also return AssetMessages for the asset.
includeTasksbooleanoptionalfalseWhen true, the command will also return the DispatchTasks for the asset.
Response description
PropertyTypeDescription
assetsArray.<Asset>The list of requested Assets.
companyRespIdAn object to contain the "id" of the Company to which the array of Assets belong.
company.iduint64?Identifier given as input for the command.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?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 StatusError CodeDescription
4003The request does not contain a company object, or it is invalid.
4003The company object does not contain an id, or it is invalid.
4015You do not have permission to view any Assets for this Company.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
40428The Company was not found by its unique identifier.

GET/companies/{companyId}/assets?{keys=values}?includeMessages=boolean&includeTasks=boolean&{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
ParameterTypeRequiredDefaultDescription
companyIduint64requiredUnique identifier of the Company.
includeMessagesbooleanoptionalfalseWhen true, the command will also return AssetMessages for the asset.
includeTasksbooleanoptionalfalseWhen true, the command will also return the DispatchTasks for the asset.
Response description
PropertyTypeDescription
assetsArray.<Asset>The list of requested Assets.
companyRespIdAn object to contain the "id" of the Company to which the array of Assets belong.
company.iduint64?Identifier given as input for the command.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
referencesObject.<string, string>The reference string given as input.
reqIdint32?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 StatusError CodeDescription
4003The request does not contain a company object, or it is invalid.
4003The company object does not contain an id, or it is invalid.
4003The references is not an object, or it is invalid.
4015You do not have permission to view any Assets for this Company.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
40428The Company was not found by its unique identifier.

GET/companies/{companyId}/assets?labels={string}&includeMessages=boolean&includeTasks=boolean

Gets the list of Assets for the specified Company only if the Asset.labels matches all of the given labels.
URL Parameters
ParameterTypeRequiredDefaultDescription
companyIduint64requiredUnique identifier of the Company.
includeMessagesbooleanoptionalfalseWhen true, the command will also return AssetMessages for the asset.
includeTasksbooleanoptionalfalseWhen true, the command will also return the AssetDispatch for the asset.
labelsstringrequiredLabels to match the DispatchJob.
Response description
PropertyTypeDescription
assetsArray.<Asset>The list of requested Assets.
companyRespIdAn object to contain the "id" of the Company to which the array of Assets belong.
company.iduint64?Identifier given as input for the command.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
labelsArray.<string>The labels given as input.
messagestringAn English description of the error.
reqIdint32?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 StatusError CodeDescription
4003The request does not contain a company object, or it is invalid.
4003The company object does not contain an id, or it is invalid.
4003The labels is not an array.
4015You do not have permission to view any Assets for this Company.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
40428The Company was not found by its unique identifier.

GET/companies/{companyId}/assets?reference={string}&includeMessages=boolean&includeTasks=boolean

Gets the list of Assets for the specified Company only if the Asset.reference field is a match.
URL Parameters
ParameterTypeRequiredDefaultDescription
companyIduint64requiredUnique identifier of the Company.
includeMessagesbooleanoptionalfalseWhen true, the command will also return AssetMessages for the asset.
includeTasksbooleanoptionalfalseWhen true, the command will also return the AssetDispatch for the asset.
referencestringrequiredValue to search in the asset.reference["Reference"] field
Response description
PropertyTypeDescription
assetsArray.<Asset>The list of requested Assets.
companyRespIdAn object to contain the "id" of the Company to which the array of Assets belong.
company.iduint64?Identifier given as input for the command.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
referencestringThe reference string given as input.
reqIdint32?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 StatusError CodeDescription
4003The request does not contain a company object, or it is invalid.
4003The company object does not contain an id, or it is invalid.
4003The reference is blank or null.
4015You do not have permission to view any Assets for this Company.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
40428The Company was not found by its unique identifier.

Behaviours

GET/behaviours

This request is an alias of /companies/{your-company-id}/behaviours/.
URL Parameters
ParameterTypeRequiredDefaultDescription
your-company-iduint64aliased{your-company-id}Your own Company's identifier.

GET/behaviours/{behaviourId}

Gets details of the specified Behaviour.
URL Parameters
ParameterTypeRequiredDescription
behaviourIduint64requiredUnique identifier of the Behaviour.
Response description
PropertyTypeDescription
behaviourBehaviourThe requested Behaviour.
behaviour.companyuint64The company to which this behaviour belongs.
behaviour.filtersexpressionA search pattern used to filter the providers which can implement this behaviour.
behaviour.iduint64Unique identifier of this behaviour.
behaviour.namestring
maximum-length: 100
The name of this behaviour.
behaviour.notesstringNotes.
behaviour.parametersObject.<string, BehaviourParameter>The list of defined variable name/value pairs for the script requires.
behaviour.prioritybyteThe priority flag allows you to define an execution order for all behaviours for a provider.
behaviour.scriptuint64The script which this behaviour implements.
behaviour.targetsexpressionThe search pattern used to target the assets which will embed this behaviour in their execution context.
behaviour.vArray.<uint32>Object version keys used to validate synchronization for all object properties.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?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 StatusError CodeDescription
4003The request does not contain a behaviour object, or it is invalid.
4003The behaviour object does not contain an id, or it is invalid.
4015You do not have permission to view this Behaviour.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
40426The Behaviour was not found by its unique identifier.

POST/behaviours/{behaviourId}

Creates a new or updates an existing Behaviour.
URL Parameters
ParameterTypeRequiredDescription
behaviourIduint64?optionalUnique identifier of the Behaviour. This value is optional, and ignored by the command.
HTTP Request body description
PropertyTypeRequiredDescription
behaviourObject.<string, ?>alwaysA simple object to contain the Behaviour parameters.
behaviour.companyuint64?create
behaviour.filtersexpressionoptionalA search pattern used to select the assets which will embed this Behaviour in their execution context.
behaviour.iduint64?updateThe unique identifier of the Behaviour you want to update.
behaviour.namestring
maximum-length: 100
createName for the Behaviour.
behaviour.notesstringoptionalNotes for the Behaviour.
behaviour.parametersObject.<string, BehaviourParameter>optionalThe values needed to implement the script. Each key in this object is the name of a required script argument.
behaviour.prioritybyte?optionalThe order in which this Behaviour is executed.
behaviour.scriptuint64?createIdentifier of the BehaviourScript to which this Behaviour belongs. After creation, this value is read-only.
behaviour.targetsexpressionoptionalA search pattern used to select the providers which can implement this Behaviour.
behaviour.vArray.<int32>optional
reqIdint32?optionalIdentifier 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
PropertyTypeDescription
behaviourRespIdScriptAn object which contains the "id", "company", and "script" keys when there is no error.
behaviour.companyuint64Identifier of the Company to which this object belongs.
behaviour.iduint64?Identifier given as input for the command.
behaviour.scriptuint64Identifier of the script to which this object belongs.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?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 StatusError CodeDescription
5002A communication error occurred.
If you receive this error, please contact technical support.
4003The request does not contain a behaviour object, or it is invalid.
4003Not enough keys exist in the behaviour object.
4003During create: When creating a new Behaviour, a name was not given, or it is invalid.
4003During create: When creating a new Behaviour, a script was not given.
4003During create: When creating a new Behaviour, a company was not given.
4003During update: When updating a Behaviour, the id was invalid.
4003During update: When updating a Behaviour, the name was given as blank.
4003During update: When updating a Behaviour, the v was not an array, or contained too few numbers.
4003The 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..
4003One of the behaviour.parameters was invalid.
Returns an ErrorDetailInput as the errorDetails..
4003One of the behaviour.parameters keys was blank or white-space.
Returns an ErrorDetailInput as the errorDetails..
4015You do not have permission to create a new Behaviour.
4015You do not have permission to update this Behaviour.
4006During update: When updating a Behaviour, an incorrect v value was given as input.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
40423During update: The BehaviourScript was not found by its unique identifier.
40426During update: The Behaviour was not found by its unique identifier.
409130There is one or more missing or invalid parameters required by the BehaviourScript.
Returns an ErrorDetailBadKeys as the errorDetails..
409130During update: When updating a Behaviour, the behaviour.script can not be changed.
Returns an ErrorDetailBadKeys as the errorDetails..
409130During 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
ParameterTypeRequiredDescription
behaviourIduint64requiredUnique identifier of the Behaviour.
Response description
PropertyTypeDescription
behaviourRespDeletedAn object which contains the Behaviour's id, owning Company id, and deleted status.
behaviour.companyuint64Identifier of the Company to which this object belongs.
behaviour.deletedbooleanFlag showing if the object is deleted.
behaviour.iduint64?Identifier given as input for the command.
behaviour.vArray.<uint32>
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?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 StatusError CodeDescription
5002A communication error occurred.
If you receive this error, please contact technical support.
4003The request does not contain a behaviour object, or it is invalid.
4003The behaviour object does not contain an id, or it is invalid.
4015You do not have permission to delete this Behaviour.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
40426The Behaviour was not found by its unique identifier.

GET/behaviours/{behaviourId}/logs

Gets the list of BehaviourLog for the specified Behaviour.
URL Parameters
ParameterTypeRequiredDescription
behaviourIduint64requiredUnique identifier of the Behaviour.
Response description
PropertyTypeDescription
behaviourRespIdScriptAn object to contain the "id" of the Behaviour to which the array of BehaviourLogs belong.
behaviour.companyuint64Identifier of the Company to which this object belongs.
behaviour.iduint64?Identifier given as input for the command.
behaviour.scriptuint64Identifier of the script to which this object belongs.
behaviourLogsArray.<BehaviourLog>The list of requested BehaviourLogs.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?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 StatusError CodeDescription
5002A communication error occurred.
If you receive this error, please contact technical support.
4003The request does not contain a behaviour object, or it is invalid.
4003The behaviour object does not contain an id, or it is invalid.
4015You do not have permission to view BehaviourLogs for this Behaviour.
4015You do not have permission to view Behaviours for this Company.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
40426The Behaviour was not found by its unique identifier.

DELETE/behaviours/{behaviourId}/logs

Gets the list of BehaviourLogs for the specified Behaviour.
URL Parameters
ParameterTypeRequiredDescription
behaviourIduint64requiredUnique identifier of the Behaviour.
Response description
PropertyTypeDescription
behaviourRespIdScriptAn object to contain the "id" of the Behaviour to which the array of BehaviourLogs belong.
behaviour.companyuint64Identifier of the Company to which this object belongs.
behaviour.iduint64?Identifier given as input for the command.
behaviour.scriptuint64Identifier of the script to which this object belongs.
countint32The total number of behaviour logs cleared.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?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 StatusError CodeDescription
5002A communication error occurred.
If you receive this error, please contact technical support.
4003The request does not contain a behaviour object, or it is invalid.
4003The behaviour object does not contain an id, or it is invalid.
4015You do not have permission to view BehaviourLogs for this Behaviour.
4015You do not have permission to clear Behaviours for this Company.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
40426The Behaviour was not found by its unique identifier.

PATCH/behaviours/{behaviourId}/restore

Restores a deleted Behaviour.
URL Parameters
ParameterTypeRequiredDescription
behaviourIduint64requiredUnique identifier of the Behaviour.
Response description
PropertyTypeDescription
behaviourRespDeletedAn object which contains the Behaviour's id, owning Company id, and deleted status.
behaviour.companyuint64Identifier of the Company to which this object belongs.
behaviour.deletedbooleanFlag showing if the object is deleted.
behaviour.iduint64?Identifier given as input for the command.
behaviour.vArray.<uint32>
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?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 StatusError CodeDescription
5002A communication error occurred.
If you receive this error, please contact technical support.
4003The request does not contain a behaviour object, or it is invalid.
4003The behaviour object does not contain an id, or it is invalid.
4015You do not have permission to restore this Behaviour.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
40426The Behaviour was not found by its unique identifier.
40027The Behaviour was found, but is not marked as deleted.

GET/behaviours/logs?asset={uint64}

Gets the list of BehaviourLogs for the specified Asset.
URL Parameters
ParameterTypeRequiredDescription
assetuint64requiredUnique identifier of the Asset.
Response description
PropertyTypeDescription
assetRespIdCompanyAn object to contain the "id" of the Asset to which the array of BehaviourLogs relates.
asset.companyuint64Identifier of the Company to which this object belongs.
asset.iduint64?Identifier given as input for the command.
behaviourLogsArray.<BehaviourLog>The list of requested BehaviourLogs.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?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 StatusError CodeDescription
5002A communication error occurred.
If you receive this error, please contact technical support.
4003The request does not contain a asset object, or it is invalid.
4003The asset object does not contain an id, or it is invalid.
4015You do not have permission to view this Asset.
4015You do not have permission to view BehaviourLogs for this Asset's Company.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
40420The Asset was not found by its unique identifier.

DELETE/behaviours/logs?asset={uint64}

Gets the list of BehaviourLogs for the specified Asset.
URL Parameters
ParameterTypeRequiredDescription
assetuint64requiredUnique identifier of the Asset.
Response description
PropertyTypeDescription
assetRespIdCompanyAn object to contain the "id" of the Asset to which the array of BehaviourLogs relates.
asset.companyuint64Identifier of the Company to which this object belongs.
asset.iduint64?Identifier given as input for the command.
countint32The total number of behaviour logs cleared.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?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 StatusError CodeDescription
5002A communication error occurred.
If you receive this error, please contact technical support.
4003The request does not contain a asset object, or it is invalid.
4003The asset object does not contain an id, or it is invalid.
4015You do not have permission to view this Asset.
4015You do not have permission to clear Behaviours for this Asset.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
40420The Asset was not found by its unique identifier.

GET/behaviours/scripts?tree=boolean

This request is an alias of /companies/{your-company-id}/behaviours/scripts?tree=true.
URL Parameters
ParameterTypeRequiredDefaultDescription
treebooleanoptionaltrueDefaults to true for this alias.
your-company-iduint64aliased{your-company-id}Your own Company's identifier.

GET/behaviours/scripts/{scriptId}

Gets details of the specified BehaviourScript.
URL Parameters
ParameterTypeRequiredDescription
scriptIduint64requiredUnique identifier of the BehaviourScript.
Response description
PropertyTypeDescription
behaviourScriptBehaviourScriptThe requested BehaviourScript.
behaviourScript.companyuint64The company to which this script belongs.
behaviourScript.compilesbooleanFlag set by the compiler if this code compiles
behaviourScript.fillcolour
maximum-length: 22
The background colour given to this script for easy visual identification.
behaviourScript.filtersexpressionA list of targeting expressions. These expressions are defaults for derived Behaviours.
behaviourScript.globalbooleanIndicates whether this script is available to child companies.
behaviourScript.graphiccodified
maximum-length: 22
The codified graphic name given to this script for easy visual identification.
behaviourScript.iduint64Unique identifier of this script.
behaviourScript.namestring
maximum-length: 100
The nickname given to this script.
behaviourScript.notesstringUsage notes and instructions for users on how best to setup this script.
behaviourScript.parametersObject.<string, BehaviourParameter>Listed parameters for the Behaviour function.
behaviourScript.sourcestring
maximum-length: 8060
The source code.
behaviourScript.strokecolour
maximum-length: 22
The text/graphic colour given to this script for easy visual identification.
behaviourScript.vArray.<uint32>Object version keys used to validate synchronization for all object properties.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?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 StatusError CodeDescription
4003The request does not contain a behaviourScript object, or it is invalid.
4003The behaviourScript object does not contain an id, or it is invalid.
4015You do not have permission to view this BehaviourScript.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
40423The BehaviourScript was not found by its unique identifier.

POST/behaviours/scripts/{scriptId}

Creates a new or updates an existing BehaviourScript.
URL Parameters
ParameterTypeRequiredDescription
scriptIduint64?optionalUnique identifier of the BehaviourScript. This value is optional, and ignored by the command.
HTTP Request body description
PropertyTypeRequiredDescription
behaviourScriptObject.<string, ?>alwaysA simple object to contain the BehaviourScript parameters.
behaviourScript.companyuint64?createIdentifier of the Company to which this BehaviourScript belongs. After creation, this value is read-only.
behaviourScript.fillstringoptionalBackground and fill colour in the UI.
behaviourScript.filtersexpressionoptionalA search pattern used to select the providers.
behaviourScript.globalbooleanoptionalWhen set to true, this Company as well as all child companies will be able to implement this BehaviourScript for that companies assets.
behaviourScript.graphicstringoptionalThe name of the symbol shown in the UI.
behaviourScript.iduint64?updateThe unique identifier of the BehaviourScript you want to update.
behaviourScript.namestring
maximum-length: 100
createName for the BehaviourScript.
behaviourScript.notesstringoptionalNotes for the BehaviourScript.
behaviourScript.parametersObject.<string, BehaviourParameter>optionalThe defined arguments for this BehaviourScript. Each key in the object is the name of an argument.
behaviourScript.sourcestringcreateSource code of the BehaviourScript.
behaviourScript.strokestringoptionalText and outline colour in the UI.
behaviourScript.vArray.<int32>optional
reqIdint32?optionalIdentifier 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
PropertyTypeDescription
behaviourScriptRespIdCompanyAn object which contains the "id" and "company" keys when there is no error.
behaviourScript.companyuint64Identifier of the Company to which this object belongs.
behaviourScript.iduint64?Identifier given as input for the command.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?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 StatusError CodeDescription
5002A communication error occurred.
If you receive this error, please contact technical support.
4003The request does not contain a behaviourScript object, or it is invalid.
4003Not enough keys exist in the behaviourScript object.
4003During create: When creating a new BehaviourScript, a name was not given, or it is invalid.
4003During create: When creating a new BehaviourScript, a company was not given.
4003During create: When creating a new BehaviourScript, the source was not given, or it is blank.
4003During update: When updating a BehaviourScript, the id was invalid.
4003During update: When updating a BehaviourScript, the name was given as blank.
4003During update: When updating a BehaviourScript, the v was not an array, or contained too few numbers.
4003One of the behaviourScript.parameters default values' was not valid.
Returns an ErrorDetailBadKeys as the errorDetails..
4003One of the behaviourScript.parameters was invalid.
Returns an ErrorDetailInput as the errorDetails..
4003One of the behaviourScript.parameters keys was blank or white-space.
Returns an ErrorDetailInput as the errorDetails..
4015You do not have permission to create a new BehaviourScript.
4015You do not have permission to update this BehaviourScript.
4006During update: When updating a BehaviourScript, an incorrect v value was given as input.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
40423During update: The BehaviourScript was not found by its unique identifier.
40925During 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..
409130During update: When updating a BehaviourScript, the behaviourScript.company can not be changed.

DELETE/behaviours/scripts/{scriptId}

Deletes an existing BehaviourScript.
URL Parameters
ParameterTypeRequiredDescription
scriptIduint64requiredUnique identifier of the BehaviourScript.
Response description
PropertyTypeDescription
behaviourScriptRespDeletedAn object which contains the BehaviourScript's id, owning Company id, and deleted status.
behaviourScript.companyuint64Identifier of the Company to which this object belongs.
behaviourScript.deletedbooleanFlag showing if the object is deleted.
behaviourScript.iduint64?Identifier given as input for the command.
behaviourScript.vArray.<uint32>
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?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 StatusError CodeDescription
5002A communication error occurred.
If you receive this error, please contact technical support.
4003The request does not contain a behaviourScript object, or it is invalid.
4003The behaviourScript object does not contain an id, or it is invalid.
4015You do not have permission to delete this BehaviourScript.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
40423The BehaviourScript was not found by its unique identifier.
40925This BehaviourScript is still being used by one of more Behaviours.
Returns an ErrorDetailCount as the errorDetails..

GET/behaviours/scripts/{scriptId}/logs

Gets the list of BehaviourLogs for the specified BehaviourScript.
URL Parameters
ParameterTypeRequiredDescription
scriptIduint64requiredUnique identifier of the BehaviourScript.
Response description
PropertyTypeDescription
behaviourLogsArray.<BehaviourLog>The list of requested BehaviourLogs.
behaviourScriptRespIdCompanyAn object to contain the "id" of the BehaviourScript to which the array of BehaviourLogs belong.
behaviourScript.companyuint64Identifier of the Company to which this object belongs.
behaviourScript.iduint64?Identifier given as input for the command.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?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 StatusError CodeDescription
5002A communication error occurred.
If you receive this error, please contact technical support.
4003The request does not contain a behaviourScript object, or it is invalid.
4003The behaviourScript object does not contain an id, or it is invalid.
4015You do not have permission to view BehaviourLogs for the BehaviourScript's Company.
4015You do not have permission to view BehaviourScripts for this Company.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
40423The BehaviourScript was not found by its unique identifier.

DELETE/behaviours/scripts/{scriptId}/logs

Gets the list of BehaviourLogs for the specified BehaviourScript.
URL Parameters
ParameterTypeRequiredDescription
scriptIduint64requiredUnique identifier of the BehaviourScript.
Response description
PropertyTypeDescription
behaviourScriptRespIdCompanyAn object to contain the "id" of the BehaviourScript to which the array of BehaviourLogs belong.
behaviourScript.companyuint64Identifier of the Company to which this object belongs.
behaviourScript.iduint64?Identifier given as input for the command.
countint32The total number of behaviour logs cleared.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?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 StatusError CodeDescription
5002A communication error occurred.
If you receive this error, please contact technical support.
4003The request does not contain a behaviourScript object, or it is invalid.
4003The behaviourScript object does not contain an id, or it is invalid.
4015You do not have permission to view BehaviourLogs for the BehaviourScript's Company.
4015You do not have permission to clear behaviours for this BehaviourScript.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
40423The BehaviourScript was not found by its unique identifier.

PATCH/behaviours/scripts/{scriptId}/restore

Restores the specified BehaviourScript.
URL Parameters
ParameterTypeRequiredDescription
scriptIduint64requiredUnique identifier of the BehaviourScript.
Response description
PropertyTypeDescription
behaviourScriptRespDeletedAn object which contains the BehaviourScript's id, owning Company id, and deleted status.
behaviourScript.companyuint64Identifier of the Company to which this object belongs.
behaviourScript.deletedbooleanFlag showing if the object is deleted.
behaviourScript.iduint64?Identifier given as input for the command.
behaviourScript.vArray.<uint32>
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?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 StatusError CodeDescription
5002A communication error occurred.
If you receive this error, please contact technical support.
4003The request does not contain a behaviourScript object, or it is invalid.
4003The behaviourScript object does not contain an id, or it is invalid.
4015You do not have permission to restore this BehaviourScript.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
40423The BehaviourScript was not found by its unique identifier.
40024The BehaviourScript was found, but is not marked as deleted.

GET/companies/{companyId}/behaviours

Gets the list of Behaviours for the specified Company.
URL Parameters
ParameterTypeRequiredDescription
companyIduint64requiredUnique identifier of the Company.
Response description
PropertyTypeDescription
behavioursArray.<Behaviour>The list of reqested Behaviours.
companyRespIdAn object to contain the "id" of the Company to which the array of Behaviours belong.
company.iduint64?Identifier given as input for the command.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?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 StatusError CodeDescription
5002A communication error occurred.
If you receive this error, please contact technical support.
4003The request does not contain a company object, or it is invalid.
4003The company object does not contain an id, or it is invalid.
4015You do not have permission to view this Company.
4015You do not have permission to view Behaviours for this Company.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
40428The Company was not found by its unique identifier.

GET/companies/{companyId}/behaviours/scripts?tree=boolean

Gets the list of BehaviourScripts for the specified Company.
URL Parameters
ParameterTypeRequiredDefaultDescription
companyIduint64requiredUnique identifier of the Company
treebooleanoptionaltrueWhen 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
PropertyTypeDescription
behaviourScriptsArray.<BehaviourScript>The list of requested BehaviourScripts.
companyRespIdAn object to contain the "id" of the Company to which the array of BehaviourScripts belong.
company.iduint64?Identifier given as input for the command.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?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 StatusError CodeDescription
5002A communication error occurred.
If you receive this error, please contact technical support.
4003The request does not contain a company object, or it is invalid.
4003The company object does not contain an id, or it is invalid.
4015You do not have permission to view BehaviourScripts for this Company.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
40428The Company was not found by its unique identifier.

Billing

GET/billing/profiles

This request is an alias of /companies/{your-company-id}/billing/profiles.
URL Parameters
ParameterTypeRequiredDefaultDescription
your-company-iduint64aliased{your-company-id}Your own Company's identifier.

GET/billing/profiles/{profileId}

Gets details of the specified BillingProfile.
URL Parameters
ParameterTypeRequiredDescription
profileIduint64requiredUnique identifier of the BillingProfile.
Response description
PropertyTypeDescription
billingProfileBillingProfileThe requested BillingProfile.
billingProfile.billeeuint64Unique identifier of the Company receiving the bill. Most of the time, this value is the same as the target.
billingProfile.companyuint64Unique identifier of the Company that owns this profile and is sending the bill.
billingProfile.currencyBillingCurrencykind of money
billingProfile.cycleBillingCycleRepeating cycle used for generating bills
billingProfile.cycleEnddatetimeWhen should the cycle end (customer cancelled)
billingProfile.cyclePostDatedbooleanPro-rated, or post-dated.
billingProfile.cycleStartdatetimeWhen is the first day of the billing cycle
billingProfile.googleServicesEnabledbooleanAre the Google services available to be proxied by the service?
billingProfile.iduint64Unique identifier of this billing profile
billingProfile.messagesArray.<BillableSmsProfile>SMS messaging tiers
billingProfile.namestring
maximum-length: 254
The name for this profile
billingProfile.notesstring
maximum-length: 1000
Notes about the billing profile for the billee or target.
billingProfile.targetuint64Unique identifier of the Company to which this rule pertains.
billingProfile.vArray.<uint32>Object version keys used to validate synchronization for all object properties.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?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 StatusError CodeDescription
4003The request does not contain a billingProfile object, or it is invalid.
4003The requested billingProfile id was invalid.
4015You do not have permission to view this Company's BillingProfiles.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
404111The BillingProfile was not found by its unique identifier.

POST/billing/profiles/{profileId}

Creates new or updates an existing BillingProfile.
URL Parameters
ParameterTypeRequiredDescription
profileIduint64?optionalUnique identifier of the BillingProfile. This value is optional, and ignored by the command.
HTTP Request body description
PropertyTypeRequiredDescription
billingProfileObject.<string, ?>alwaysA simple object to contain the BillingProfile parameters.
billingProfile.billeeuint64?optionalUnique identifier of the Company receiving the bill.
billingProfile.companyuint64?optionalUnique identifier of the Company that owns this BillingProfile and is sending the bill.
billingProfile.currencyBillingCurrency?optionalKind of money.
billingProfile.cycleBillingCycle?optionalRepeating cycle used for generating bills.
billingProfile.cycleEnddatetimeoptionalWhen should the cycle end (customer cancelled); null means it never ends.
billingProfile.cyclePostDatedbooleanoptionalPro-rated, or post-dated.
billingProfile.cycleStartdatetimeoptionalWhen is the first day of the billing cycle.
billingProfile.googleServicesEnabledbooleanoptionalAre the Google services available to be proxied by the service?
billingProfile.iduint64?optionalUnique identifier of the BillingProfile you want to update.
billingProfile.messagesArray.<BillableSmsProfile>optionalSMS messaging tiers.
billingProfile.namestringoptionalName for the BillingProfile
billingProfile.notesstringoptionalNotes about the BillingProfile for the billee or target.
billingProfile.targetuint64?optionalUnique identifier of the Company to which this rule pertains.
billingProfile.vArray.<int32>optional
reqIdint32?optionalIdentifier 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
PropertyTypeDescription
billingProfileRespIdCompanyAn object which contains the "id", "company", and "profile" keys.
billingProfile.companyuint64Identifier of the Company to which this object belongs.
billingProfile.iduint64?Identifier given as input for the command.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?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 StatusError CodeDescription
5002A communication error occurred.
If you receive this error, please contact technical support.
4003The request does not contain a billingProfile object, or it is invalid.
4003Not enough keys exist in the billingProfile object.
4003The messages are invalid.
4003The cycle is invalid.
4003The currency is invalid.
4003The cycleStart date is invalid.
4003The cycleEnd date is invalid.
4003During create: When creating a new BillingProfile, start date is invalid.
4003During create: When creating a new BillingProfile, end date is invalid.
4003During create: When creating a new BillingProfile, kind is invalid.
4003During create: When creating a new BillingProfile, a name was not given, or it is invalid.
4003During create: When creating a new BillingProfile, company is invalid.
4003During create: When creating a new BillingProfile, target is invalid.
4003During create: When creating a new BillingProfile, billee is invalid.
4003During update: When updating a BillingProfile, the name was invalid.
4003During update: When updating a BillingProfile, the v was invalid.
4015During create: You do not have permission to create new BillingProfile.
4015During update: You do not have permission to update BillingProfile.
4006During update: When updating a BillingProfile, the v was not an array, or contained too few numbers.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
40428The company was not found by its unique identifier.
40428The target was not found by its unique identifier.
40428The billee was not found by its unique identifier.
404111The BillingProfile was not found by its unique identifier.
If you receive this error, please contact technical support.
409130During update: When updating a BillingProfile, the billingProfile.company can not be changed.

DELETE/billing/profiles/{profileId}

Deletes an existing BillingProfile.
URL Parameters
ParameterTypeRequiredDescription
profileIduint64requiredUnique identifier of the BillingProfile.
Response description
PropertyTypeDescription
billingProfileRespDeletedAn object which contains the BillingProfile's unique identifier and deleted status.
billingProfile.companyuint64Identifier of the Company to which this object belongs.
billingProfile.deletedbooleanFlag showing if the object is deleted.
billingProfile.iduint64?Identifier given as input for the command.
billingProfile.vArray.<uint32>
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?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 StatusError CodeDescription
5002A communication error occurred, the BillingProfile was not deleted.
If you receive this error, please contact technical support.
4003The request does not contain a billingProfile object, or it is invalid.
4003The requested billingProfile id was invalid.
4015You do not have permission to delete this Company's BillingProfiles.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
404111The BillingProfile was not found by its unique identifier.

GET/billing/profiles/{profileId}/discounts

Gets the list of HostingDiscounts for the specified BillingProfile.
URL Parameters
ParameterTypeRequiredDescription
profileIduint64requiredUnique identifier of the BillingProfile.
Response description
PropertyTypeDescription
billingProfileRespIdCompanyAn object to contain the "id" of the BillingProfile to which the array of BillableHostingDiscounts belong.
billingProfile.companyuint64Identifier of the Company to which this object belongs.
billingProfile.iduint64?Identifier given as input for the command.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
hostingDiscountsArray.<BillableHostingDiscount>The list of requested BillableHostingDiscounts.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response structure
{
	"billingProfile": {
		"company": number,
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"hostingDiscounts": [
		{
			"amount": number,
			"company": number,
			"end": string,
			"id": number,
			"limit": number,
			"name": string,
			"notes": string,
			"percentage": boolean,
			"profile": number,
			"reference": string,
			"services": [
				string
			],
			"start": string,
			"suspended": boolean,
			"targets": string,
			"v": [
				number
			]
		}
	],
	"message": string,
	"reqId": number
}
Possible exceptions
HTTP StatusError CodeDescription
5002A communication error occurred.
If you receive this error, please contact technical support.
4003The request does not contain a billingProfile object, or it is invalid.
4003The billingProfile object does not contain an id, or it is invalid.
4015You do not have permission to view this Company's BillableHostingDiscounts.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
40428The Company was not found by its unique identifier.
404111The BillingProfile was not found by its unique identifier.
404115The BillableHostingDiscount was not found by its unique identifier.

GET/billing/profiles/{profileId}/licenses

Gets the list of BillableHostingLicenses for the specified BillingProfile.
URL Parameters
ParameterTypeRequiredDescription
profileIduint64requiredUnique identifier of the BillingProfile.
Response description
PropertyTypeDescription
billingProfileRespIdCompanyAn object to contain the "id" of the BillingProfile to which the array of BillableHostingLicenses belong.
billingProfile.companyuint64Identifier of the Company to which this object belongs.
billingProfile.iduint64?Identifier given as input for the command.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
hostingLicensesArray.<BillableHostingLicense>The list of BillableHostingLicenses.
messagestringAn English description of the error.
reqIdint32?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,
			"start": string,
			"suspended": boolean,
			"targets": string,
			"v": [
				number
			]
		}
	],
	"message": string,
	"reqId": number
}
Possible exceptions
HTTP StatusError CodeDescription
5002A communication error occurred.
If you receive this error, please contact technical support.
4003The request does not contain a billingProfile object, or it is invalid.
4003The billingProfile object does not contain an id, or it is invalid.
4015You do not have permission to view this Company's BillableHostingLicenses.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
40428The Company was not found by its unique identifier.
If you receive this error, please contact technical support.
404111The BillingProfile was not found by its unique identifier.

GET/billing/profiles/{profileId}/reports

Gets the list of BillingReports for the specified BillingProfile.
URL Parameters
ParameterTypeRequiredDescription
profileIduint64requiredUnique identifier of the BillingProfile.
Response description
PropertyTypeDescription
billingProfileRespIdCompanyAn object to contain the "id" of the BillingProfile to which the array of BillableHostingRules belong.
billingProfile.companyuint64Identifier of the Company to which this object belongs.
billingProfile.iduint64?Identifier given as input for the command.
billingReportsArray.<BillingReport>The list of requested BillingReports.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response structure
{
	"billingProfile": {
		"company": number,
		"id": number
	},
	"billingReports": [
		{
			"billee": number,
			"company": number,
			"currency": string,
			"endDate": string,
			"error": string,
			"hostingBreakdown": {
				string: [
					{
						"asset": number,
						"billableDays": number,
						"cost": number,
						"created": string,
						"deleted": string,
						"discount": number,
						"labels": [
							string
						],
						"name": string,
						"notes": string,
						"phoneNumbers": [
							number
						],
						"providers": [
							string
						],
						"suspended": string,
						"suspendedCost": number,
						"suspendedDays": number,
						"suspendedDiscount": number,
						"total": number,
						"updatedDts": string
					}
				]
			},
			"id": number,
			"name": string,
			"notes": string,
			"profile": number,
			"startDate": string,
			"status": string,
			"summary": [
				{
					"hostingSummary": [
						{
							"count": number,
							"kind": 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 StatusError CodeDescription
5002A communication error occurred.
If you receive this error, please contact technical support.
4003The request does not contain a billingProfile object, or it is invalid.
4003The billingProfile object does not contain an id, or it is invalid.
4015You do not have permission to view this Company's BillingReports.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
40428The Company was not found by its unique identifier.
404111The BillingProfile was not found by its unique identifier.

PATCH/billing/profiles/{profileId}/restore

Restores the specified BillingProfile to its previous version.
URL Parameters
ParameterTypeRequiredDescription
profileIduint64requiredUnique identifier of the BillingProfile.
Response description
PropertyTypeDescription
billingProfileRespDeletedAn object which contains the BillingProfile's unique identifier and deleted status.
billingProfile.companyuint64Identifier of the Company to which this object belongs.
billingProfile.deletedbooleanFlag showing if the object is deleted.
billingProfile.iduint64?Identifier given as input for the command.
billingProfile.vArray.<uint32>
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?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 StatusError CodeDescription
5002A communication error occurred.
If you receive this error, please contact technical support.
4003The request does not contain a billingProfile object, or it is invalid.
4003The requested billingProfile id was invalid.
4015You do not have permission to restore BillingProfiles.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
404111The BillingProfile was not found by its unique identifier.
400112The BillingProfile was found, but is not marked as deleted.

GET/billing/profiles/{profileId}/rules

Gets the list of BillableHostingRule for the specified BillingProfile.
URL Parameters
ParameterTypeRequiredDescription
profileIduint64requiredUnique identifier of the BillingProfile.
Response description
PropertyTypeDescription
billingProfileRespIdCompanyAn object to contain the "id" of the BillingProfile to which the array of BillableHostingRules belong.
billingProfile.companyuint64Identifier of the Company to which this object belongs.
billingProfile.iduint64?Identifier given as input for the command.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
hostingRulesArray.<BillableHostingRule>The list of requested BillableHostingRules.
messagestringAn English description of the error.
reqIdint32?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,
			"start": string,
			"suspended": boolean,
			"targets": string,
			"v": [
				number
			]
		}
	],
	"message": string,
	"reqId": number
}
Possible exceptions
HTTP StatusError CodeDescription
5002A communication error occurred.
If you receive this error, please contact technical support.
4003The request does not contain a billingProfile object, or it is invalid.
4003The billingProfile object does not contain an id, or it is invalid.
4015You do not have permission to view this Company's BillableHostingRules.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
40428The Company was not found by its unique identifier.
If you receive this error, please contact technical support.
404111The BillingProfile was not found by its unique identifier.

GET/billing/profiles/discounts/{discountId}

Gets details of the specified BillableHostingDiscount.
URL Parameters
ParameterTypeRequiredDescription
discountIduint64requiredUnique identifier of the BillableHostingDiscount.
Response description
PropertyTypeDescription
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
hostingDiscountBillableHostingDiscountThe requested BillableHostingDiscount.
hostingDiscount.amountdoubleCost per cycle for this plan
hostingDiscount.companyuint64Unique identifier of the Company that owns this hosting rule.
hostingDiscount.enddatetimeDate this billing rule is applied until; null means it never ends. These dates are used to determine how much of the cycle is billed.
hostingDiscount.iduint64Unique identifier of this hosting rule.
hostingDiscount.limituint32?The number of units to which this billing rule applies. Should be a non-zero value; null means unlimited
hostingDiscount.namestring
maximum-length: 254
The name of this billing rule.
hostingDiscount.notesstringNotes about billing this rule.
hostingDiscount.percentagebooleanWhen true, the amount is used as a percentage value instead of a currency values.
hostingDiscount.profileuint64Unique identifier of this rule's billing profile.
hostingDiscount.referencestring
maximum-length: 100
A custom field used to refer to an external system. Examples are a cost codes, SOCs, discount plans...
hostingDiscount.servicesArray.<BillableHostingType>The type of services being discounted.
hostingDiscount.startdatetimeDate this billing rule takes effect. These dates are used to determine how much of the cycle is billed.
hostingDiscount.suspendedbooleanDoes this hosting rule apply to suspended resources
hostingDiscount.targetsexpressionWhich assets are targetted by this hosting rule
hostingDiscount.vArray.<uint32>Object version keys used to validate synchronization for all object properties.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response structure
{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"hostingDiscount": {
		"amount": number,
		"company": number,
		"end": string,
		"id": number,
		"limit": number,
		"name": string,
		"notes": string,
		"percentage": boolean,
		"profile": number,
		"reference": string,
		"services": [
			string
		],
		"start": string,
		"suspended": boolean,
		"targets": string,
		"v": [
			number
		]
	},
	"message": string,
	"reqId": number
}
Possible exceptions
HTTP StatusError CodeDescription
4003The request does not contain a hostingDiscount object, or it is invalid.
4003The requested hostingDiscount id was invalid.
4015You do not have permission to view this Company's BillableHostingDiscounts.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
404115The BillableHostingDiscount was not found by its unique identifier.

POST/billing/profiles/discounts/{discountId}

Creates new or updates an existing BillableHostingDiscount.
URL Parameters
ParameterTypeRequiredDescription
discountIduint64?optionalUnique identifier of the BillableHostingDiscount. This value is optional, and ignored by the command.
HTTP Request body description
PropertyTypeRequiredDescription
hostingDiscountObject.<string, ?>alwaysA simple object to contain the BillableHostingDiscount parameters.
hostingDiscount.amountdouble?optionalCost per cycle for this plan
hostingDiscount.enddatetimecreateDate this billing discount is applied until; null means it never ends.
hostingDiscount.iduint64?updateUnique identifier of the BillableHostingDiscount you want to update.
hostingDiscount.limituint32?optionalThe number of units to which this billing discount applies. Should be a non-zero value; null means unlimited.
hostingDiscount.namestringcreateName for the BillableHostingDiscount
hostingDiscount.notesstringoptionalNotes about the BillableHostingDiscount.
hostingDiscount.percentagebooleanoptionalWhen true, the amount is used as a percentage value instead of a currency values.
hostingDiscount.profileuint64?createUnique identifier of this discount's billing BillingProfile.
hostingDiscount.referencestringoptionalA custom field used to refer to an external system. Examples are a cost codes, SOCs, discount plans...
hostingDiscount.servicesArray.<BillableHostingType>createThe types of service being discounted.
hostingDiscount.startdatetimecreateDate this billing discount takes effect.
hostingDiscount.suspendedbooleanoptionalDoes this BillableHostingDiscount apply to suspended resources.
hostingDiscount.targetsexpressionoptionalWhich assets are targetted by this BillableHostingDiscount.
hostingDiscount.vArray.<int32>optional
reqIdint32?optionalIdentifier used by external system to correlate requests to responses.
HTTP Request body structure
{
	"hostingDiscount": {
		"amount": number,
		"end": string,
		"id": number,
		"limit": number,
		"name": string,
		"notes": string,
		"percentage": boolean,
		"profile": number,
		"reference": string,
		"services": [
			string
		],
		"start": string,
		"suspended": boolean,
		"targets": string,
		"v": [
			number
		]
	},
	"reqId": number
}
Response description
PropertyTypeDescription
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
hostingDiscountRespIdBillingProfileAn object which contains the "id", "company", and "profile" keys.
hostingDiscount.companyuint64Identifier of the Company to which this object belongs.
hostingDiscount.iduint64?Identifier given as input for the command.
hostingDiscount.profileuint64Identifier of the BillingProfile to which this object belongs
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response structure
{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"hostingDiscount": {
		"company": number,
		"id": number,
		"profile": number
	},
	"message": string,
	"reqId": number
}
Possible exceptions
HTTP StatusError CodeDescription
5002A communication error occurred.
If you receive this error, please contact technical support.
4003The request does not contain a hostingDiscount object, or it is invalid.
4003Not enough keys exist in the hostingDiscount object.
4003During create: When creating a new BillableHostingDiscount, start date is invalid.
4003During create: When creating a new BillableHostingDiscount, end date is invalid.
4003During create: When creating a new BillableHostingDiscount, services is invalid.
4003During create: When creating a new BillableHostingDiscount, a name was not given, or it is invalid.
4003During create: When creating a new BillableHostingDiscount, profile is invalid.
4003During update: When updating a BillableHostingDiscount, the name was invalid.
4003During update: When updating a BillableHostingDiscount, the v was invalid.
4015During create: You do not have permission to create new BillableHostingDiscounts.
4015During update: You do not have permission to update BillableHostingDiscounts.
4006During update: When updating a BillableHostingDiscount, the v was not an array, or contained too few numbers.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
404111The BillingProfile was not found by its unique identifier.
If you receive this error, please contact technical support.
404115During update: The BillableHostingDiscount was not found by its unique identifier.
409130During update: When updating a BillableHostingDiscount, the hostingDiscount.profile can not be changed.

DELETE/billing/profiles/discounts/{discountId}

Deletes an existing BillableHostingDiscount.
URL Parameters
ParameterTypeRequiredDescription
discountIduint64requiredUnique identifier of the BillableHostingDiscount.
Response description
PropertyTypeDescription
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
hostingDiscountRespDeletedAn object which contains the BillableHostingDiscount's unique identifier and deleted status.
hostingDiscount.companyuint64Identifier of the Company to which this object belongs.
hostingDiscount.deletedbooleanFlag showing if the object is deleted.
hostingDiscount.iduint64?Identifier given as input for the command.
hostingDiscount.vArray.<uint32>
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response structure
{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"hostingDiscount": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"message": string,
	"reqId": number
}
Possible exceptions
HTTP StatusError CodeDescription
5002A communication error occurred.
If you receive this error, please contact technical support.
4003The request does not contain a hostingDiscount object, or it is invalid.
4003The requested hostingDiscount id was invalid.
4015You do not have permission to delete BillableHostingDiscounts.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
404115The BillableHostingDiscount was not found by its unique identifier.

PATCH/billing/profiles/discounts/{discountId}/restore

Restores the specified BillableHostingDiscount to its previous version.
URL Parameters
ParameterTypeRequiredDescription
discountIduint64requiredUnique identifier of the BillableHostingDiscount.
Response description
PropertyTypeDescription
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
hostingDiscountRespDeletedAn object which contains the BillableHostingDiscount's unique identifier and deleted status.
hostingDiscount.companyuint64Identifier of the Company to which this object belongs.
hostingDiscount.deletedbooleanFlag showing if the object is deleted.
hostingDiscount.iduint64?Identifier given as input for the command.
hostingDiscount.vArray.<uint32>
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response structure
{
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"hostingDiscount": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"message": string,
	"reqId": number
}
Possible exceptions
HTTP StatusError CodeDescription
5002A communication error occurred.
If you receive this error, please contact technical support.
4003The request does not contain a hostingDiscount object, or it is invalid.
4003The requested hostingDiscount id was invalid.
4015You do not have permission to delete BillableHostingDiscounts.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
404115The BillableHostingDiscount was not found by its unique identifier.
400116The BillableHostingDiscount was found, but is not marked as deleted.

GET/billing/profiles/licenses/{licenseId}

Gets details of the specified BillableHostingLicense.
URL Parameters
ParameterTypeRequiredDescription
licenseIduint64requiredUnique identifier of the BillableHostingLicense.
Response description
PropertyTypeDescription
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
hostingLicenseBillableHostingLicenseThe requested BillableHostingLicense.
hostingLicense.amountdoubleCost per cycle for this plan
hostingLicense.companyuint64Unique identifier of the Company that owns this hosting rule.
hostingLicense.enddatetimeDate 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.iduint64Unique identifier of this hosting rule.
hostingLicense.kindBillableLicenseTypeThe type of hardware license
hostingLicense.limituint32?The number of units to which this billing rule applies. Should be a non-zero value; null means unlimited
hostingLicense.namestring
maximum-length: 254
The name of this billing rule.
hostingLicense.notesstringNotes about billing this rule.
hostingLicense.profileuint64Unique identifier of this rule's billing profile.
hostingLicense.referencestring
maximum-length: 100
A custom field used to refer to an external system. Examples are a cost codes, SOCs, discount plans...
hostingLicense.startdatetimeDate this billing rule takes effect. These dates are used to determine how much of the cycle is billed.
hostingLicense.suspendedbooleanDoes this hosting rule apply to suspended resources
hostingLicense.targetsexpressionWhich assets are targetted by this hosting rule
hostingLicense.vArray.<uint32>Object version keys used to validate synchronization for all object properties.
messagestringAn English description of the error.
reqIdint32?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,
		"start": string,
		"suspended": boolean,
		"targets": string,
		"v": [
			number
		]
	},
	"message": string,
	"reqId": number
}
Possible exceptions
HTTP StatusError CodeDescription
4003The request does not contain a hostingLicense object, or it is invalid.
4003The requested hostingLicense id was invalid.
4015You do not have permission to view this Company's BillableHostingLicenses.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
404117The BillableHostingLicense was not found by its unique identifier.

POST/billing/profiles/licenses/{licenseId}

Creates new or updates an existing BillableHostingLicense.
URL Parameters
ParameterTypeRequiredDescription
licenseIduint64?optionalUnique identifier of the BillableHostingLicense. This value is optional, and ignored by the command.
HTTP Request body description
PropertyTypeRequiredDescription
hostingLicenseObject.<string, ?>alwaysA simple object to contain the BillableHostingLicense parameters.
hostingLicense.amountdouble?optionalCost per cycle for this plan
hostingLicense.enddatetimeoptionalDate this BillableHostingLicense is applied until; null means it never ends.
hostingLicense.iduint64?updateUnique identifier of the BillableHostingLicense you want to update.
hostingLicense.kindBillableLicenseType?createThe type of hardware BillableLicenseType.
hostingLicense.limituint32?optionalThe number of units to which this BillableHostingLicense applies. Should be a non-zero value; null means unlimited
hostingLicense.namestringcreateName for the BillableHostingLicense
hostingLicense.notesstringoptionalNotes about the BillableHostingLicense.
hostingLicense.profileuint64?createUnique identifier of this BillableHostingLicense's BillingProfile.
hostingLicense.referencestringoptionalA custom field used to refer to an external system. Examples are a cost codes, SOCs, discount plans...
hostingLicense.startdatetimeoptionalDate this BillableHostingLicense takes effect.
hostingLicense.suspendedbooleanoptionalDoes this BillableHostingLicense apply to suspended resources
hostingLicense.targetsexpressionoptionalWhich assets are targetted by this BillableHostingLicense
hostingLicense.vArray.<int32>optional
reqIdint32?optionalIdentifier 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
PropertyTypeDescription
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
hostingLicenseRespIdBillingProfileAn object which contains the "id", "company", and "profile" keys.
hostingLicense.companyuint64Identifier of the Company to which this object belongs.
hostingLicense.iduint64?Identifier given as input for the command.
hostingLicense.profileuint64Identifier of the BillingProfile to which this object belongs
messagestringAn English description of the error.
reqIdint32?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 StatusError CodeDescription
5002A communication error occurred.
If you receive this error, please contact technical support.
4003The request does not contain a hostingLicense object, or it is invalid.
4003Not enough keys exist in the hostingLicense object.
4003During create: When creating a new BillableHostingLicense, start date is invalid.
4003During create: When creating a new BillableHostingLicense, end date is invalid.
4003During create: When creating a new BillableHostingLicense, kind is invalid.
4003During create: When creating a new BillableHostingLicense, a name was not given, or it is invalid.
4003During create: When creating a new BillableHostingLicense, profile is invalid.
4003During update: When updating a BillableHostingLicense, the name was invalid.
4003During update: When updating a BillableHostingLicense, the v was invalid.
4015During create: You do not have permission to create new BillableHostingLicenses.
4015During update: You do not have permission to update BillableHostingLicenses.
4006During update: When updating a BillableHostingLicense, the v was not an array, or contained too few numbers.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
404111The BillingProfile was not found by its unique identifier.
If you receive this error, please contact technical support.
404117During update: The BillableHostingLicense was not found by its unique identifier.
409130During update: When updating a BillableHostingLicense, the hostingLicense.profile can not be changed.

DELETE/billing/profiles/licenses/{licenseId}

Deletes an existing BillableHostingLicense.
URL Parameters
ParameterTypeRequiredDescription
licenseIduint64requiredUnique identifier of the BillableHostingLicense.
Response description
PropertyTypeDescription
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
hostingLicenseRespDeletedAn object which contains the BillableHostingLicense's unique identifier and deleted status.
hostingLicense.companyuint64Identifier of the Company to which this object belongs.
hostingLicense.deletedbooleanFlag showing if the object is deleted.
hostingLicense.iduint64?Identifier given as input for the command.
hostingLicense.vArray.<uint32>
messagestringAn English description of the error.
reqIdint32?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 StatusError CodeDescription
5002A communication error occurred, the BillableHostingLicense was not deleted.
If you receive this error, please contact technical support.
4003The request does not contain a hostingLicense object, or it is invalid.
4003The requested hostingLicense id was invalid.
4015You do not have permission to delete this Company's BillableHostingLicenses.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
404117The BillableHostingLicense was not found by its unique identifier.

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

Restores the specified BillableHostingLicense to its previous version.
URL Parameters
ParameterTypeRequiredDescription
licenseIduint64requiredUnique identifier of the BillableHostingLicense.
Response description
PropertyTypeDescription
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
hostingLicenseRespDeletedAn object which contains the BillableHostingLicense's unique identifier and deleted status.
hostingLicense.companyuint64Identifier of the Company to which this object belongs.
hostingLicense.deletedbooleanFlag showing if the object is deleted.
hostingLicense.iduint64?Identifier given as input for the command.
hostingLicense.vArray.<uint32>
messagestringAn English description of the error.
reqIdint32?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 StatusError CodeDescription
5002A communication error occurred.
If you receive this error, please contact technical support.
4003The request does not contain a hostingLicense object, or it is invalid.
4003The requested hostingLicense id was invalid.
4015You do not have permission to delete BillableHostingLicenses.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
404117The BillableHostingLicense was not found by its unique identifier.
400118The BillableHostingLicense was found, but is not marked as deleted.

GET/billing/profiles/reports

This request is an alias of /companies/{your-company-id}/billing/profiles/reports.
URL Parameters
ParameterTypeRequiredDefaultDescription
your-company-iduint64aliased{your-company-id}Your own Company's identifier.

GET/billing/profiles/reports/{reportId}

Gets details of the specified BillingReport.
URL Parameters
ParameterTypeRequiredDescription
reportIduint64requiredUnique identifier of the BillingReport.
Response description
PropertyTypeDescription
billingReportBillingReportThe requested BillingReport.
billingReport.billeeuint64Unique identifier of the Company receiving the bill.
billingReport.companyuint64The company to which this report belongs and is sending the bill.
billingReport.currencyBillingCurrencyCurrency being billed in
billingReport.endDatedatetimeLast day of the billing cycle
billingReport.errorstring
maximum-length: 250
A field which contains report error details if the BillingReport.status is BillingReportStatus.failed.
billingReport.hostingBreakdownObject.<uint64, Array.<BillingReportHostingBreakdown>>
for keys see: Asset.id
Individual amounts per targeted assets used to calculate the results of the report.
billingReport.iduint64Unique identifier
billingReport.namestring
maximum-length: 100
Name of this report.
billingReport.notesstringNotes about this report.
billingReport.profileuint64The profile to which this report belongs
billingReport.startDatedatetimeFirst day of the billing cycle
billingReport.statusBillingReportStatusThe processing status of this report.
billingReport.summaryArray.<BillingReportSummary>Summary contains totals per target for this billee
billingReport.totaldoubleTotal amount being billed.
billingReport.vArray.<uint32>Object version keys used to validate synchronization for all object properties.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response structure
{
	"billingReport": {
		"billee": number,
		"company": number,
		"currency": string,
		"endDate": string,
		"error": string,
		"hostingBreakdown": {
			string: [
				{
					"asset": number,
					"billableDays": number,
					"cost": number,
					"created": string,
					"deleted": string,
					"discount": number,
					"labels": [
						string
					],
					"name": string,
					"notes": string,
					"phoneNumbers": [
						number
					],
					"providers": [
						string
					],
					"suspended": string,
					"suspendedCost": number,
					"suspendedDays": number,
					"suspendedDiscount": number,
					"total": number,
					"updatedDts": string
				}
			]
		},
		"id": number,
		"name": string,
		"notes": string,
		"profile": number,
		"startDate": string,
		"status": string,
		"summary": [
			{
				"hostingSummary": [
					{
						"count": number,
						"kind": 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 StatusError CodeDescription
4003The request does not contain a billingReport object, or it is invalid.
4003The requested billingReport id was invalid.
4015You do not have permission to view this Company's BillingReports.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
404119The BillingReport was not found by its unique identifier.

DELETE/billing/profiles/reports/{reportId}

Deletes an existing BillingReport.
URL Parameters
ParameterTypeRequiredDescription
reportIduint64requiredUnique identifier of the BillingReport.
Response description
PropertyTypeDescription
billingReportRespDeletedAn object which contains the BillingReport's unique identifier and deleted status.
billingReport.companyuint64Identifier of the Company to which this object belongs.
billingReport.deletedbooleanFlag showing if the object is deleted.
billingReport.iduint64?Identifier given as input for the command.
billingReport.vArray.<uint32>
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?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 StatusError CodeDescription
5002A communication error occurred, the BillingReport was not deleted.
If you receive this error, please contact technical support.
4003The request does not contain a billingReport object, or it is invalid.
4003The requested billingReport id was invalid.
4015You do not have permission to delete this Company's BillingReports.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
404119The BillingReport was not found by its unique identifier.

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

Restores the specified BillingReport to its previous version.
URL Parameters
ParameterTypeRequiredDescription
reportIduint64requiredUnique identifier of the BillingReport.
Response description
PropertyTypeDescription
billingReportRespDeletedAn object which contains the BillingReport's unique identifier and deleted status.
billingReport.companyuint64Identifier of the Company to which this object belongs.
billingReport.deletedbooleanFlag showing if the object is deleted.
billingReport.iduint64?Identifier given as input for the command.
billingReport.vArray.<uint32>
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?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 StatusError CodeDescription
5002A communication error occurred.
If you receive this error, please contact technical support.
4003The request does not contain a billingReport object, or it is invalid.
4003The requested billingReport id was invalid.
4015You do not have permission to restore BillingReports.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
404119The BillingReport was not found by its unique identifier.
400120The BillingReport was found, but is not marked as deleted.

GET/billing/profiles/rules/{ruleId}

Gets details of the specified BillableHostingRule.
URL Parameters
ParameterTypeRequiredDescription
ruleIduint64requiredUnique identifier of the BillableHostingRule.
Response description
PropertyTypeDescription
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
hostingRuleBillableHostingRuleThe requested BillableHostingRule.
hostingRule.amountdoubleCost per cycle for this plan
hostingRule.companyuint64Unique identifier of the Company that owns this hosting rule.
hostingRule.enddatetimeDate 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.iduint64Unique identifier of this hosting rule.
hostingRule.limituint32?The number of units to which this billing rule applies. Should be a non-zero value; null means unlimited
hostingRule.namestring
maximum-length: 254
The name of this billing rule.
hostingRule.notesstringNotes about billing this rule.
hostingRule.profileuint64Unique identifier of this rule's billing profile.
hostingRule.referencestring
maximum-length: 100
A custom field used to refer to an external system. Examples are a cost codes, SOCs, discount plans...
hostingRule.serviceBillableHostingTypeThe type of service being billed.
hostingRule.startdatetimeDate this billing rule takes effect. These dates are used to determine how much of the cycle is billed.
hostingRule.suspendedbooleanDoes this hosting rule apply to suspended resources
hostingRule.targetsexpressionWhich assets are targetted by this hosting rule
hostingRule.vArray.<uint32>Object version keys used to validate synchronization for all object properties.
messagestringAn English description of the error.
reqIdint32?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,
		"start": string,
		"suspended": boolean,
		"targets": string,
		"v": [
			number
		]
	},
	"message": string,
	"reqId": number
}
Possible exceptions
HTTP StatusError CodeDescription
4003The request does not contain a hostingRule object, or it is invalid.
4003The requested hostingRule id was invalid.
4015You do not have permission to view this Company's BillableHostingRules.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
404113The BillableHostingRule was not found by its unique identifier.

POST/billing/profiles/rules/{ruleId}

Creates new or updates an existing BillableHostingRule.
URL Parameters
ParameterTypeRequiredDescription
ruleIduint64?optionalUnique identifier of the BillableHostingRule. This value is optional, and ignored by the command.
HTTP Request body description
PropertyTypeRequiredDescription
hostingRuleObject.<string, ?>alwaysA simple object to contain the BillableHostingRule parameters.
hostingRule.amountdouble?optionalCost per cycle for this plan
hostingRule.enddatetimecreateDate this BillableHostingRule is applied until; null means it never ends.
hostingRule.iduint64?updateUnique identifier of the BillableHostingRule you want to update.
hostingRule.limituint32?optionalThe number of units to which this BillableHostingRule applies. Should be a non-zero value; null means unlimited
hostingRule.namestringcreateName for the BillableHostingRule
hostingRule.notesstringoptionalNotes about the BillableHostingRule.
hostingRule.profileuint64?createUnique identifier of this BillableHostingRule's BillingProfile.
hostingRule.referencestringoptionalA custom field used to refer to an external system. Examples are a cost codes, SOCs, discount plans...
hostingRule.serviceBillableHostingType?createThe type of service being billed.
hostingRule.startdatetimecreateDate this BillableHostingRule takes effect.
hostingRule.suspendedbooleanoptionalDoes this BillableHostingRule apply to suspended resources
hostingRule.targetsexpressionoptionalWhich assets are targetted by this BillableHostingRule
hostingRule.vArray.<int32>optional
reqIdint32?optionalIdentifier 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
PropertyTypeDescription
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
hostingRuleRespIdBillingProfileAn object which contains the "id", "company", and "profile" keys.
hostingRule.companyuint64Identifier of the Company to which this object belongs.
hostingRule.iduint64?Identifier given as input for the command.
hostingRule.profileuint64Identifier of the BillingProfile to which this object belongs
messagestringAn English description of the error.
reqIdint32?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 StatusError CodeDescription
5002A communication error occurred.
If you receive this error, please contact technical support.
4003The request does not contain a hostingRule object, or it is invalid.
4003Not enough keys exist in the hostingRule object.
4003During create: When creating a new BillableHostingRule, start date is invalid.
4003During create: When creating a new BillableHostingRule, end date is invalid.
4003During create: When creating a new BillableHostingRule, a name was not given, or it is invalid.
4003During create: When creating a new BillableHostingRule, profile is invalid.
4003During create: When creating a new BillableHostingRule, service is invalid.
4003During update: When updating a BillableHostingRule, the name was invalid.
4003During update: When updating a BillableHostingRule, the v was invalid.
4015During create: You do not have permission to create new BillableHostingRules.
4015During update: You do not have permission to update BillableHostingRules.
4006During update: When updating a BillableHostingRule, the v was not an array, or contained too few numbers.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
404111The BillingProfile was not found by its unique identifier.
If you receive this error, please contact technical support.
404113During update: The BillableHostingRule was not found by its unique identifier.
409130During update: When updating a BillableHostingRule, the hostingRule.profile can not be changed.

DELETE/billing/profiles/rules/{ruleId}

Deletes an existing BillableHostingRule.
URL Parameters
ParameterTypeRequiredDescription
ruleIduint64requiredUnique identifier of the BillableHostingRule.
Response description
PropertyTypeDescription
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
hostingRuleRespDeletedAn object which contains the BillableHostingRule's unique identifier and deleted status.
hostingRule.companyuint64Identifier of the Company to which this object belongs.
hostingRule.deletedbooleanFlag showing if the object is deleted.
hostingRule.iduint64?Identifier given as input for the command.
hostingRule.vArray.<uint32>
messagestringAn English description of the error.
reqIdint32?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 StatusError CodeDescription
5002A communication error occurred, the BillableHostingRule was not deleted.
If you receive this error, please contact technical support.
4003The request does not contain a hostingRule object, or it is invalid.
4003The requested hostingRule id was invalid.
4015You do not have permission to delete this Company's BillableHostingRules.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
404113The BillableHostingRule was not found by its unique identifier.

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

Restores the specified BillableHostingRule to its previous version.
URL Parameters
ParameterTypeRequiredDescription
ruleIduint64requiredUnique identifier of the BillableHostingRule.
Response description
PropertyTypeDescription
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
hostingRuleRespDeletedAn object which contains the BillableHostingRule's unique identifier and deleted status.
hostingRule.companyuint64Identifier of the Company to which this object belongs.
hostingRule.deletedbooleanFlag showing if the object is deleted.
hostingRule.iduint64?Identifier given as input for the command.
hostingRule.vArray.<uint32>
messagestringAn English description of the error.
reqIdint32?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 StatusError CodeDescription
5002A communication error occurred.
If you receive this error, please contact technical support.
4003The request does not contain a hostingRule object, or it is invalid.
4003The requested hostingRule id was invalid.
4015You do not have permission to restore BillableHostingRules.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
404113The BillableHostingRule was not found by its unique identifier.
400114The BillableHostingRule was found, but is not marked as deleted.

GET/companies/{companyId}/billing/profiles

Gets the list of BillingProfiles for the specified Company.
URL Parameters
ParameterTypeRequiredDescription
companyIduint64requiredUnique identifier of the Company.
Response description
PropertyTypeDescription
billingProfilesArray.<BillingProfile>The list of requested BillingProfiles.
companyRespIdAn object to contain the "id" of the Company to which the array of BillingProfiles belong.
company.iduint64?Identifier given as input for the command.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?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 StatusError CodeDescription
5002A communication error occurred.
If you receive this error, please contact technical support.
4003The request does not contain a company object, or it is invalid.
4003The company object does not contain an id, or it is invalid.
4015You do not have permission to view this Company's BillingProfiles.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
40428The Company was not found by its unique identifier.

GET/companies/{companyId}/billing/profiles/reports

Gets the list of BillingReports for the specified Company.
URL Parameters
ParameterTypeRequiredDescription
companyIduint64requiredUnique identifier of the Company.
Response description
PropertyTypeDescription
billingReportsArray.<BillingReport>The list of requested BillingReports.
companyRespIdAn object to contain the "id" of the Company to which the array of BillingReports belong.
company.iduint64?Identifier given as input for the command.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response structure
{
	"billingReports": [
		{
			"billee": number,
			"company": number,
			"currency": string,
			"endDate": string,
			"error": string,
			"hostingBreakdown": {
				string: [
					{
						"asset": number,
						"billableDays": number,
						"cost": number,
						"created": string,
						"deleted": string,
						"discount": number,
						"labels": [
							string
						],
						"name": string,
						"notes": string,
						"phoneNumbers": [
							number
						],
						"providers": [
							string
						],
						"suspended": string,
						"suspendedCost": number,
						"suspendedDays": number,
						"suspendedDiscount": number,
						"total": number,
						"updatedDts": string
					}
				]
			},
			"id": number,
			"name": string,
			"notes": string,
			"profile": number,
			"startDate": string,
			"status": string,
			"summary": [
				{
					"hostingSummary": [
						{
							"count": number,
							"kind": 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 StatusError CodeDescription
5002A communication error occurred.
If you receive this error, please contact technical support.
4003The request does not contain a company object, or it is invalid.
4003The company object does not contain an id, or it is invalid.
4015You do not have permission to view this Company's BillingReports.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
40428The Company was not found by its unique identifier.

Companies

GET/companies?tree=boolean&includeParent=boolean

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
ParameterTypeRequiredDefaultDescription
includeParentbooleanoptionaltrueDefaults to true for this alias.
treebooleanoptionalfalseDefaults to false for this alias.
your-company-iduint64aliased{your-company-id}Your own Company's identifier.

GET/companies/{companyId}

Gets details of the specified Company.
URL Parameters
ParameterTypeRequiredDescription
companyIduint64requiredUnique identifier of the Company.
Response description
PropertyTypeDescription
companyCompanyThe requested Company.
company.directoryObject.<string, Array.<uint64>>
for value-values see: Contact.id
The list of Contacts from this and other companies broken down by contact role.
company.iduint64Unique identifier of the Company.
company.labelsObject.<codified, LabelStyle>
for keys see: LabelStyle.code
The styles for labels added to Assets, Places, and other things.
company.namestring
maximum-length: 100
The organizational name.
company.notesstringNotes.
company.parentuint64The unique identifier of this company's parent organization.
company.passwordPolicyPasswordPolicyThe password complexity and expiry policy.
company.passwordPolicy.expireModePasswordExpiryModeDefines how passwords expire.
company.passwordPolicy.expireThresholdbyteThe threshold for expiry.
company.passwordPolicy.includeLettersbooleanDo passwords require alphabetical characters.
company.passwordPolicy.includeNumbersbooleanDo passwords require numeric characters.
company.passwordPolicy.includeSpecialbooleanDo passwords require non-alphanumeric characters.
company.passwordPolicy.includeUpperLowerbooleanDo passwords require upper-case and lower-case letters.
company.passwordPolicy.minimumLengthbyteThe minimum number of characters required.
company.referencesObject.<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.resellerCompanyResellerIf this company is a reseller, then they have their own theme, support and billing information.
company.reseller.contactInfoObject.<string, uint64>
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.domainstring
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.favouritestring
maximum-length: 200
The name of the icon file used for browser bookmarks.
company.reseller.gamutObject.<string, ColourStyle>
maximum-length of keys: 25
Colours used as templates for status tags, labels, and places.
company.reseller.graphicsObject.<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.iconstring
maximum-length: 200
The name of the image uploaded as the logo (used for collapsed/mobile view).
company.reseller.iduint64Unique identifier of the Company.
company.reseller.languagesArray.<codified>
maximum-length of values: 5
A list of supported languages for your customers.
company.reseller.notifyEmailNotificationServerEmailThe server used for notification and conversational email messages sent and received by the system.
company.reseller.notifyEmail.incomingAddressstringThe domain or IP address of the incoming email server.
company.reseller.notifyEmail.incomingLoginstringThe username used to login to the incoming email server.
company.reseller.notifyEmail.incomingMessageNumberuint32IMAP message sequence number so only recent messages are retrieved.
company.reseller.notifyEmail.incomingPortuint16The port number of the incoming email server.
company.reseller.notifyEmail.incomingSecurebooleanIs the incoming email server using a secure SSL/TLS connection (it should).
company.reseller.notifyEmail.incomingTypestringThe type of incoming protocol to use (IMAP or POP3).
company.reseller.notifyEmail.outgoingAddressstringThe domain or IP address of the outgoing email server.
company.reseller.notifyEmail.outgoingLoginstringThe username used to login to the outgoing email server.
company.reseller.notifyEmail.outgoingPortuint16The port number of the outgoing email server.
company.reseller.notifyEmail.outgoingReplyToemailAn optional field which can be set as the "sent from" and/or "reply-to" address.
company.reseller.notifyEmail.outgoingSecurebooleanIs the outgoing email server using a secure SSL/TLS connection (it should).
company.reseller.notifyEmail.outgoingTypestringThe type of outgoing protocol to use (only SMTP).
company.reseller.notifySmsNotificationServerSmsDefinition for load-balanced outbound SMS numbers for the reseller.
company.reseller.notifySms.notifyLimituint16A per-number/per-day limit on the amount of Notifications sent.
company.reseller.notifySms.phoneNumbersObject.<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.parentuint64The unique identifier of this company's parent organization.
company.reseller.recoverBodystringThe body of the email sent to a user requesting a password reset.
company.reseller.recoverIsHtmlboolean
company.reseller.recoverSubjectstringThe subject of the email sent to a user requesting a password reset.
company.reseller.serviceNamestring
maximum-length: 150
The name of the branded service being provided to the seller's customers.
company.reseller.termsPreamblestringA preamble to the general terms and conditions offered by Fleet Freedom.
company.reseller.termsUpdateddatetimeThe 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.vArray.<uint32>Object version keys used to validate synchronization for all object properties.
company.reseller.websiteObject.<string, colour>
maximum-length of keys: 25
maximum-length of values: 22
Themed colours used in the web-based UI.
company.sessionPolicySessionPolicyThe session lifetime policy.
company.sessionPolicy.applicationsArray.<string>The list of applications users are allowed to use to create sessions.
company.sessionPolicy.expireTimeoutuint16The lifetime duration of a session in minutes.
company.sessionPolicy.idleAllowedbooleanDefines whether a session should be automatically killed when the connection breaks.
company.sessionPolicy.ipv4RangesArray.<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.maxSessionsbyteThe maximum number of sessions allowed per user.
company.sessionPolicy.multiUserSessionMultiUserDefines the behaviour of the system when a user creates multiple sessions.
company.tagsObject.<codified, LabelStyle>
for keys see: LabelStyle.code
The styles for status tags added to Assets.
company.userGroupsArray.<UserGroup>A list of user groups that belong to this company. A user can only belong to groups from their own company.
company.vArray.<int32>
fixed count: 6
Object version keys used to validate synchronization for all object properties.
company.v[0]int32The first element is for the general properties
company.v[1]int32The second element is not used (yet)
company.v[2]int32The third element is not used (yet)
company.v[3]int32The fourth element is for the style properties
company.v[4]int32The fifth element is for the policy properties
company.v[5]int32The sixth element is for the reseller properties
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?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 StatusError CodeDescription
4003The request does not contain a company object, or it is invalid.
4003The company object does not contain an id, or it is invalid.
4015You do not have permission to view this Company.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
40428The Company was not found by its unique identifier.

POST/companies/{companyId}

Creates a new or updates an existing Company.
URL Parameters
ParameterTypeRequiredDescription
companyIduint64?optionalUnique identifier of the Company. This value is optional, and ignored by the command.
HTTP Request body description
PropertyTypeRequiredDescription
companyObject.<string, ?>alwaysA simple object to contain the company parameters.
company.directoryObject.<string, Array.<uint64>>
for value-values see: Contact.id
optionalThe list of Contacts from this and other companies broken down by contact role.
company.iduint64?updateUnique identifier of the Company.
company.labelsObject.<string, LabelStyle>optionalThe styles for labels added to Assets, Places, and other things.
company.namestring
maximum-length: 100
createThe organizational name.
company.notesstringoptionalNotes.
company.parentuint64?createThe unique identifier of this company's parent organization.
company.passwordPolicyObject.<string, ?>alwaysThe password complexity and expiry policy.
company.passwordPolicy.expireModePasswordExpiryMode?optionalDefines how passwords expire.
company.passwordPolicy.expireThresholdbyte?optionalThe threshold for expiry (in days).
company.passwordPolicy.includeLettersbooleanoptionalDo passwords require alphabetical characters.
company.passwordPolicy.includeNumbersbooleanoptionalDo passwords require numeric characters.
company.passwordPolicy.includeSpecialbooleanoptionalDo passwords require non-alphanumeric characters.
company.passwordPolicy.includeUpperLowerbooleanoptionalDo passwords require upper-case and lower-case letters.
company.passwordPolicy.minimumLengthbyte?optionalThe minimum number of characters required.
company.referencesObject.<string, string>optionalName/value collections of custom fields used to refer to external systems. If the value is null, the references are removed from the Company.
company.sessionPolicyObject.<string, ?>alwaysThe session lifetime policy.
company.sessionPolicy.applicationsArray.<string>optionalThe list of applications users are allowed to use to create sessions.
company.sessionPolicy.expireTimeoutuint16?optionalThe lifetime duration of a session in minutes.
company.sessionPolicy.idleAllowedbooleanoptionalDefines whether a session should be automatically killed when the connection breaks.
company.sessionPolicy.ipv4RangesArray.<ipv4>
maximum-length of values: 19
optionalRestrict session creation to only the provided IPv4 ranges (using CIDR slash-notation). Leave blank for Internet access.
company.sessionPolicy.maxSessionsbyte?optionalThe maximum number of sessions allowed per user.
company.sessionPolicy.multiUserSessionMultiUser?optionalDefines the behaviour of the system when a user creates multiple sessions.
company.tagsObject.<string, LabelStyle>optionalThe styles for status tags added to Assets.
company.vArray.<int32>optional
reqIdint32?optionalIdentifier 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
PropertyTypeDescription
companyRespIdParentAn object which contains the "id" and "parent" keys.
company.iduint64?Identifier given as input for the command.
company.parentuint64?Identifier of the parent to which this company belongs
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?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 StatusError CodeDescription
5002A communication error occurred.
If you receive this error, please contact technical support.
4003The request does not contain a company object, or it is invalid.
4003No valid changes would be performed.
4003One of the keys in the company.labels object is blank.
4003One of the values in the company.labels object is not valid.
4003One of the keys in the company.tags object is blank.
4003One of the values in the company.tags object is not valid.
4003One of the keys in the company.directory object is blank.
4003One of the values in the company.directory object is not an array.
4003One of the arrays in the company.directory object contains an invalid value.
4003One of the values in the company.sessionPolicy.applications array contains an invalid regular expression.
4003One of the values in the company.sessionPolicy.ipv4Ranges array contains an invalid IP address or CIDR range.
4003The given value for the company.sessionPolicy.multiUser is invalid.
4003The given value for the company.sessionPolicy.expireTimeout is invalid.
4003The given value for the company.sessionPolicy.maxSessions is invalid.
4003The given value for the company.passwordPolicy.minimumLength is invalid.
4003The given value for the company.passwordPolicy.expireMode is invalid.
4003The given value for the company.passwordPolicy.expireThreshold is invalid.
4003The company.passwordPolicy.expireThreshold is zero, and the company.passwordPolicy.expireMode is anything but PasswordExpiryMode.never.
4003The company.references were not provided as null or an object.
4003During create: When creating a new Company, a name was not given.
4003During create: When creating a new Company, a parent was not given.
4003During update: When updating a Company, the name was given as null or blank.
4003During update: When updating a Company, the v was not an array, or contained too few numbers.
4003During create: When creating a new Company, too many company.references were given as input.
Returns an ErrorDetailMinMax as the errorDetails..
4015You do not have permission to create a new Company.
4015You do not have permission to update the CompanyGeneral.
4015You do not have permission to update the CompanyDirectory.
4015You do not have permission to update the CompanyStyles.
4015You do not have permission to update the CompanyPolicies.
4006During update: When updating a Company, an incorrect v value was given as input.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
40428During update: The Company was not found by its unique identifier.
409130The given parent cannot be the same as the Company id.
Returns an ErrorDetailParent as the errorDetails..
409130The given parent would create a circular reference in the Company tree.
Returns an ErrorDetailParent as the errorDetails..
409130During 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
ParameterTypeRequiredDescription
companyIduint64requiredUnique identifier of the Company.
Response description
PropertyTypeDescription
companyRespParentDeletedAn object which contains the Company's unique identifier and deleted status.
company.deletedbooleanFlag showing if the object is deleted.
company.iduint64?Identifier given as input for the command.
company.parentuint64Identifier of the parent to which the Company is a child.
company.vArray.<uint32>
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?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 StatusError CodeDescription
5002A communication error occurred.
If you receive this error, please contact technical support.
4003The request does not contain a company object, or it is invalid.
4003The company object does not contain an id, or it is invalid.
4015You do not have permission to delete this Company.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
40428The Company was not found by its unique identifier.

PATCH/companies/{companyId}/restore

Restores the specified Company.
URL Parameters
ParameterTypeRequiredDescription
companyIduint64requiredUnique identifier of the Company.
Response description
PropertyTypeDescription
companyRespParentDeletedAn object which contains the Company's unique identifier and deleted status.
company.deletedbooleanFlag showing if the object is deleted.
company.iduint64?Identifier given as input for the command.
company.parentuint64Identifier of the parent to which the Company is a child.
company.vArray.<uint32>
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?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 StatusError CodeDescription
5002A communication error occurred.
If you receive this error, please contact technical support.
4003The request does not contain a company object, or it is invalid.
4003The company object does not contain an id, or it is invalid.
4015You do not have permission to restore this Company.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
40428The Company was not found by its unique identifier.
40029The Company was found, but is not marked as deleted.

GET/companies/{companyId}/tree?tree=boolean&includeParent=boolean

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
ParameterTypeRequiredDefaultDescription
companyIduint64requiredUnique identifier of the Company.
includeParentbooleanoptionalfalse
treebooleanoptionaltrueWhen set to true, the parent Company is included in the results.
Response description
PropertyTypeDescription
companiesArray.<CompanyGeneral>The list of requested companies.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?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 StatusError CodeDescription
4003The request does not contain a company object, or it is invalid.
4003The company object does not contain an id, or it is invalid.
4015You do not have permission to view this Company or child companies.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
40428The Company was not found by its unique identifier.

GET/companies/{companyId}/tree?{keys=values}?tree=boolean&includeParent=boolean&{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
ParameterTypeRequiredDefaultDescription
companyIduint64requiredUnique identifier of the Company.
includeParentbooleanoptionalfalse
treebooleanoptionaltrueWhen set to true, the parent Company is included in the results.
Response description
PropertyTypeDescription
companiesArray.<CompanyGeneral>The list of requested companies.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
referencesObject.<string, string>The reference string given as input.
reqIdint32?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 StatusError CodeDescription
4003The request does not contain a company object, or it is invalid.
4003The company object does not contain an id, or it is invalid.
4003The references is not an object, or it is invalid.
4015You do not have permission to view this Company or child companies.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
40428The Company was not found by its unique identifier.

GET/companies/tree?tree=boolean&includeParent=boolean

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
ParameterTypeRequiredDefaultDescription
includeParentbooleanoptionaltrueDefaults to true for this alias.
treebooleanoptionaltrueDefaults to true for this alias.
your-company-iduint64aliased{your-company-id}Your own Company's identifier.

Contacts

GET/companies/{companyId}/contacts

Gets the list of Contacts for the specified Company.
URL Parameters
ParameterTypeRequiredDescription
companyIduint64requiredUnique identifier of the Company.
Response description
PropertyTypeDescription
companyRespIdAn object to contain the "id" of the Company to which the array of Contacts belong.
company.iduint64?Identifier given as input for the command.
contactsArray.<Contact>The list of requested Contacts.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?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 StatusError CodeDescription
5002A communication error occurred.
If you receive this error, please contact technical support.
4003The request does not contain a company object, or it is invalid.
4003The company object does not contain an id, or it is invalid.
4015You do not have permission to view Contacts for this Company.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
40428The Company was not found by its unique identifier.

GET/contacts

This request is an alias of /companies/{your-company-id}/contacts/.
URL Parameters
ParameterTypeRequiredDefaultDescription
your-company-iduint64aliased{your-company-id}Your own Company's identifier.

GET/contacts/{contactId}

Gets details of the specified Contact.
URL Parameters
ParameterTypeRequiredDescription
contactIduint64requiredUnique identifier of the Contact.
Response description
PropertyTypeDescription
contactContactThe requested Contact.
contact.addressesObject.<string, string>Mailing addresses. Use the object key like a name of the address. Example keys: Home, Work, Park, etc.
contact.companyuint64The company to which this contact belongs
contact.datesObject.<string, datetime>Date information. Use the object key like a name of the date. Example keys: Birthday, Started Date, Retired On, etc.
contact.emailsObject.<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.iduint64Unique identifier of this contact.
contact.namestring
maximum-length: 100
The person's name
contact.notesstringNotes about this person.
contact.optionsObject.<string, string>Uncategorized information. Use the object keys and values however you'd like.
contact.otherNamesObject.<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.phonesObject.<string, phone>Phone numbers. Use the object key like a name of the phone number. Example keys: Mobile, Fax, Home, Office, etc.
contact.picturesArray.<uint64>
for values see: Picture.id
Pictures of this Contact.
contact.rolesArray.<string>A list of roles they play in the Company.
contact.urlsObject.<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.vArray.<uint32>Object version keys used to validate synchronization for all object properties.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?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 StatusError CodeDescription
4003The request does not contain a contact object, or it is invalid.
4003The contact object does not contain an id, or it is invalid.
4015You do not have permission to view this Contact.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
40431The Contact was not found by its unique identifier.

POST/contacts/{contactId}

Creates a new or updates an existing Contact.
URL Parameters
ParameterTypeRequiredDescription
contactIduint64?optionalUnique identifier of the Contact. This value is optional, and ignored by the command.
HTTP Request body description
PropertyTypeRequiredDescription
contactObject.<string, ?>alwaysA simple object to contain the Contact parameters.
contact.addressesObject.<string, string>optionalMailing addresses Use the object key like a name of the address. Example keys: Home, Work, Park, etc.
contact.companyuint64?createThe Company to which this Contact belongs. After creation, this value is read-only.
contact.datesObject.<string, datetime>optionalDate information Use the object key like a name of the date. Example keys: Birthday, Started Date, Retired On, etc.
contact.emailsObject.<string, email>
maximum-length of values: 254
optionalEmail addresses Use the object key like a name of the address. Example keys: Home, Work, Support, Old, etc.
contact.iduint64?updateThe unique identifier of the Contact you want to update.
contact.namestring
maximum-length: 100
optionalName for the Contact.
contact.notesstringoptionalNotes for the Contact.
contact.optionsObject.<string, string>optionalUncategorized information Use the object keys and values however you'd like.
contact.otherNamesObject.<string, string>
maximum-length of values: 254
optionalA 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.phonesObject.<string, phone?>optionalPhone numbers. Use the object key like a name of the phone number. Example keys: Mobile, Fax, Home, Office, etc.
contact.picturesArray.<uint64>
for values see: Picture.id
optionalPictures of this Contact.
contact.rolesArray.<codified>optionalA list of roles they play in the Company.
contact.urlsObject.<string, url>
maximum-length of values: 254
optionalWebsites and other online resources Use the object key like a name of the address. Example keys: Downloads, Support, FTP, etc.
contact.vArray.<int32>optional
reqIdint32?optionalIdentifier 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
PropertyTypeDescription
contactRespIdCompanyAn object which contains the "id" and "company" keys when there is no error.
contact.companyuint64Identifier of the Company to which this object belongs.
contact.iduint64?Identifier given as input for the command.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?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 StatusError CodeDescription
5002A communication error occurred.
If you receive this error, please contact technical support.
4003The request does not contain a contact object, or it is invalid.
4003Not enough keys exist in the contact object.
4003During create: When creating a new Contact, a company was not given.
4003During create: When creating a new Contact, a name was not given, or it is invalid.
4003During update: When updating a Contact, the id was invalid.
4003During update: When updating a Contact, the name was given as blank.
4003During update: When updating a Contact, the v was not an array, or contained too few numbers.
4003One of the contact.otherNames keys or values is invalid.
Returns an ErrorDetailInput as the errorDetails..
4003One of the contact.emails keys or values is invalid.
Returns an ErrorDetailInput as the errorDetails..
4003One of the contact.phones keys or values is invalid.
Returns an ErrorDetailInput as the errorDetails..
4003One of the contact.addresses keys or values is invalid.
Returns an ErrorDetailInput as the errorDetails..
4003One of the contact.urls keys or values is invalid.
Returns an ErrorDetailInput as the errorDetails..
4003One of the contact.dates keys or values is invalid.
Returns an ErrorDetailInput as the errorDetails..
4003One of the contact.options keys or values is invalid.
Returns an ErrorDetailInput as the errorDetails..
4003One of the contact.pictures values is invalid.
Returns an ErrorDetailInput as the errorDetails..
4015You do not have permission to create a new Contact.
4015You do not have permission to update this Contact.
4006During update: When updating a Contact, an incorrect v value was given as input.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
40431During update: The Contact was not found by its unique identifier.
40469One of the contact.pictures given as input in the Pictures array was not found.
Returns an ErrorDetailBadIds as the errorDetails..
409130During update: When updating a Contact, the company was provided as a different value.

DELETE/contacts/{contactId}

Deletes an existing Contact.
URL Parameters
ParameterTypeRequiredDescription
contactIduint64requiredUnique identifier of the Contact.
Response description
PropertyTypeDescription
contactRespDeletedAn object which contains the Contact's id, owning Company id, and deleted status.
contact.companyuint64Identifier of the Company to which this object belongs.
contact.deletedbooleanFlag showing if the object is deleted.
contact.iduint64?Identifier given as input for the command.
contact.vArray.<uint32>
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?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 StatusError CodeDescription
5002A communication error occurred.
If you receive this error, please contact technical support.
4003The request does not contain a contact object, or it is invalid.
4003The contact object does not contain an id, or it is invalid.
4015You do not have permission to delete this Contact.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
40431The Contact was not found by its unique identifier.
409121This 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
ParameterTypeRequiredDescription
contactIduint64requiredUnique identifier of the Contact.
Response description
PropertyTypeDescription
contactRespDeletedAn object which contains the Contact's id, owning Company id, and deleted status.
contact.companyuint64Identifier of the Company to which this object belongs.
contact.deletedbooleanFlag showing if the object is deleted.
contact.iduint64?Identifier given as input for the command.
contact.vArray.<uint32>
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?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 StatusError CodeDescription
5002A communication error occurred.
If you receive this error, please contact technical support.
4003The request does not contain a contact object, or it is invalid.
4003The contact object does not contain an id, or it is invalid.
4015You do not have permission to restore this Contact.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
40431The Contact was not found by its unique identifier.
40032The Contact was found, but is not marked as deleted.

Dispatch

POST/assets/{assetId}/dispatch

Updates an existing AssetDispatch.
URL Parameters
ParameterTypeRequiredDescription
assetIduint64?optionalUnique identifier of the Asset. This value is optional, and ignored by the command.
HTTP Request body description
PropertyTypeRequiredDescription
assetDispatchObject.<string, ?>alwaysA simple object to contain the AssetDispatch parameters.
assetDispatch.directionsArray.<DispatchDirection>optionalDriving directions and route path details.
assetDispatch.iduint64alwaysThe unique identifier of the asset you want to update.
assetDispatch.jobsArray.<uint64>optionalThe list of DispatchJobs to be assigned to this asset.
assetDispatch.optimizebooleanoptionalIndicates whether the jobs should be optimized based on distance and priority.
assetDispatch.vArray.<int32>optional
reqIdint32?optionalIdentifier 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
PropertyTypeDescription
assetDispatchRespIdCompanyAn object which contains the "id" and "company" keys.
assetDispatch.companyuint64Identifier of the Company to which this object belongs.
assetDispatch.iduint64?Identifier given as input for the command.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?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 StatusError CodeDescription
5002A communication error occurred.
If you receive this error, please contact technical support.
4003The request does not contain an assetDispatch object, or it is invalid.
4003Not enough keys exist in the assetDispatch object.
4003The assetDispatch.id is invalid.
4003The v was not an array, or contained too few numbers.
4003One of the assetDispatch.jobs given in the array cannot be parsed, or is a value less than zero.
Returns an ErrorDetailInput as the errorDetails..
4003One of the assetDispatch.directions given in the array cannot be parsed.
Returns an ErrorDetailInput as the errorDetails..
4015You do not have permission to update the AssetDispatch.
4015You do not have permission to view this Asset.
4006During update: When updating an AssetDispatch, the wrong version key was given.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
40420This Asset was not found by its unique identifier.
40420The Asset for one of the assetDispatch.jobs was not found.
50282An error occured while optimizing the job steps.
40396This Asset is suspended. Before updating AssetDispatch, it must be reactivated.
40396The Asset for one of the assetDispatch.jobs is suspended.
409130One or more of the assetDispatch.jobs cannot be re-assigned to this Asset as they are completed.
409130One or more of the assetDispatch.jobs don't belong to the same Company as this Asset
409130One or more of the assetDispatch.jobs don't have any matching labels with this Asset
404139One of the assetDispatch.jobs was not found.
404141One or more of the assetDispatch.jobs given as input in the jobs array was not found.
Returns an ErrorDetailBadIds as the errorDetails..

GET/assets/{assetId}/dispatch/jobs

Gets the list of DispatchJobs for the specified Asset.
URL Parameters
ParameterTypeRequiredDescription
assetIduint64requiredUnique identifier of the Asset.
Response description
PropertyTypeDescription
assetRespIdCompanyAn object to contain the "id" of the Asset to which the array of DispatchJobs belong.
asset.companyuint64Identifier of the Company to which this object belongs.
asset.iduint64?Identifier given as input for the command.
dispatchJobsArray.<DispatchJob>The list of requested DispatchJobs.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response structure
{
	"asset": {
		"company": number,
		"id": number
	},
	"dispatchJobs": [
		{
			"asset": number,
			"attachments": [
				number
			],
			"company": number,
			"created": string,
			"forms": [
				number
			],
			"id": number,
			"instructions": string,
			"labels": [
				string
			],
			"name": string,
			"priority": string,
			"references": {
				string: string
			},
			"steps": [
				{
					"address": string,
					"duration": string,
					"eta": string,
					"latlng": {
						"lat": number,
						"lng": number
					},
					"name": string,
					"notes": string,
					"place": number,
					"signatory": string,
					"signature": boolean,
					"states": {
						string: {
							"latlng": {
								"lat": number,
								"lng": number
							},
							"updated": string
						}
					}
				}
			],
			"tags": [
				string
			],
			"v": [
				number
			]
		}
	],
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}
Possible exceptions
HTTP StatusError CodeDescription
4003The request does not contain a asset object, or it is invalid.
4003The asset object does not contain an id, or it is invalid.
4015You do not have permission to view DispatchJobs.
4015You do not have permission to view the associated Asset.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
40420The Asset was not found by its unique identifier.
40428The Company containing the DispatchJobs was not found.
40396The Asset was found, but it is suspended. Before using any Asset resources, it must be reactivated.

GET/assets/{assetId}/dispatch/jobs?{keys=values}?{keys=values}

Gets the list of DispatchJobs for the specified Asset only if the specified reference fields match. If no references are specified, it will match any DispatchJob with no references. If a reference value is null, it will match any DispatchJob without that reference key.
URL Parameters
ParameterTypeRequiredDescription
assetIduint64requiredUnique identifier of the Asset.
Response description
PropertyTypeDescription
assetRespIdCompanyAn object to contain the "id" of the Asset to which the array of DispatchJobs belong.
asset.companyuint64Identifier of the Company to which this object belongs.
asset.iduint64?Identifier given as input for the command.
dispatchJobsArray.<DispatchJob>The list of requested DispatchJobs.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
referencesObject.<string, string>The reference string given as input.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response structure
{
	"asset": {
		"company": number,
		"id": number
	},
	"dispatchJobs": [
		{
			"asset": number,
			"attachments": [
				number
			],
			"company": number,
			"created": string,
			"forms": [
				number
			],
			"id": number,
			"instructions": string,
			"labels": [
				string
			],
			"name": string,
			"priority": string,
			"references": {
				string: string
			},
			"steps": [
				{
					"address": string,
					"duration": string,
					"eta": string,
					"latlng": {
						"lat": number,
						"lng": number
					},
					"name": string,
					"notes": string,
					"place": number,
					"signatory": string,
					"signature": boolean,
					"states": {
						string: {
							"latlng": {
								"lat": number,
								"lng": number
							},
							"updated": string
						}
					}
				}
			],
			"tags": [
				string
			],
			"v": [
				number
			]
		}
	],
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"references": {
		string: string
	},
	"reqId": number
}
Possible exceptions
HTTP StatusError CodeDescription
4003The request does not contain a asset object, or it is invalid.
4003The request does not contain a references object, or it is invalid.
4003The asset object does not contain an id, or it is invalid.
4015You do not have permission to view DispatchJobs.
4015You do not have permission to view the associated Asset.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
40420The Asset was not found by its unique identifier.
40428The Company containing the DispatchJobs was not found.
40396The Asset was found, but it is suspended. Before using any Asset resources, it must be reactivated.

GET/assets/{assetId}/dispatch/tasks

Gets the list of DispatchTasks for the specified Asset.
URL Parameters
ParameterTypeRequiredDescription
assetIduint64requiredUnique identifier of the Asset.
Response description
PropertyTypeDescription
assetRespIdCompanyAn object to contain the "id" of the Asset to which the array of DispatchTasks belong.
asset.companyuint64Identifier of the Company to which this object belongs.
asset.iduint64?Identifier given as input for the command.
dispatchTasksArray.<DispatchTask>The list of requested DispatchTasks.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response structure
{
	"asset": {
		"company": number,
		"id": number
	},
	"dispatchTasks": [
		{
			"address": string,
			"arrived": string,
			"asset": number,
			"attachments": [
				number
			],
			"company": number,
			"completed": string,
			"created": string,
			"duration": string,
			"eta": string,
			"id": number,
			"instructions": string,
			"latlng": {
				"lat": number,
				"lng": number
			},
			"name": string,
			"notes": string,
			"place": number,
			"reference": string,
			"references": {
				string: string
			},
			"signatory": string,
			"signature": boolean,
			"status": string,
			"v": [
				number
			]
		}
	],
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}
Possible exceptions
HTTP StatusError CodeDescription
4003The request does not contain a asset object, or it is invalid.
4003The asset object does not contain an id, or it is invalid.
4015You do not have permission to view DispatchTasks.
4015You do not have permission to view the associated Asset.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
40420The Asset was not found by its unique identifier.
40428The Company containing the DispatchTasks was not found.
40396The Asset was found, but it is suspended. Before using any Asset resources, it must be reactivated.

GET/assets/{assetId}/dispatch/tasks?{keys=values}?{keys=values}

Gets the list of DispatchTasks for the specified Asset only if the specified reference fields match. If no references are specified, it will match any DispatchTask with no references. If a reference value is null, it will match any DispatchTask without that reference key.
URL Parameters
ParameterTypeRequiredDescription
assetIduint64requiredUnique identifier of the Asset.
Response description
PropertyTypeDescription
assetRespIdCompanyAn object to contain the "id" of the Asset to which the array of DispatchTasks belong.
asset.companyuint64Identifier of the Company to which this object belongs.
asset.iduint64?Identifier given as input for the command.
dispatchTasksArray.<DispatchTask>The list of requested DispatchTasks.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
referencesObject.<string, string>The reference string given as input.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response structure
{
	"asset": {
		"company": number,
		"id": number
	},
	"dispatchTasks": [
		{
			"address": string,
			"arrived": string,
			"asset": number,
			"attachments": [
				number
			],
			"company": number,
			"completed": string,
			"created": string,
			"duration": string,
			"eta": string,
			"id": number,
			"instructions": string,
			"latlng": {
				"lat": number,
				"lng": number
			},
			"name": string,
			"notes": string,
			"place": number,
			"reference": string,
			"references": {
				string: string
			},
			"signatory": string,
			"signature": boolean,
			"status": string,
			"v": [
				number
			]
		}
	],
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"references": {
		string: string
	},
	"reqId": number
}
Possible exceptions
HTTP StatusError CodeDescription
4003The request does not contain a asset object, or it is invalid.
4003The request does not contain a references object, or it is invalid.
4003The asset object does not contain an id, or it is invalid.
4015You do not have permission to view DispatchTasks.
4015You do not have permission to view the associated Asset.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
40420The Asset was not found by its unique identifier.
40428The Company containing the DispatchTasks was not found.
40396The Asset was found, but it is suspended. Before using any Asset resources, it must be reactivated.

GET/companies/{companyId}/assets/dispatch/jobs?{keys=values}?{keys=values}

Gets the list of DispatchJobs for the specified Company only if the specified reference fields match. If no references are specified, it will match any DispatchJob with no references. If a reference value is null, it will match any DispatchJob without that reference key.
URL Parameters
ParameterTypeRequiredDescription
companyIduint64requiredUnique identifier of the Company.
Response description
PropertyTypeDescription
companyRespIdAn object to contain the "id" of the Company to which the array of DispatchJobs belong.
company.iduint64?Identifier given as input for the command.
dispatchJobsArray.<DispatchJob>The list of requested DispatchJobs.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
referencesObject.<string, string>The reference string given as input.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response structure
{
	"company": {
		"id": number
	},
	"dispatchJobs": [
		{
			"asset": number,
			"attachments": [
				number
			],
			"company": number,
			"created": string,
			"forms": [
				number
			],
			"id": number,
			"instructions": string,
			"labels": [
				string
			],
			"name": string,
			"priority": string,
			"references": {
				string: string
			},
			"steps": [
				{
					"address": string,
					"duration": string,
					"eta": string,
					"latlng": {
						"lat": number,
						"lng": number
					},
					"name": string,
					"notes": string,
					"place": number,
					"signatory": string,
					"signature": boolean,
					"states": {
						string: {
							"latlng": {
								"lat": number,
								"lng": number
							},
							"updated": string
						}
					}
				}
			],
			"tags": [
				string
			],
			"v": [
				number
			]
		}
	],
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"references": {
		string: string
	},
	"reqId": number
}
Possible exceptions
HTTP StatusError CodeDescription
4003The request does not contain a company object, or it is invalid.
4003The request does not contain a references object, or it is invalid.
4003The company object does not contain an id, or it is invalid.
4015You do not have permission to view DispatchJobs.
4015You do not have permission to view Assets.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
40428The Company containing the DispatchJobs was not found.

GET/companies/{companyId}/assets/dispatch/jobs

Gets the list of DispatchJobs for the specified Company.
URL Parameters
ParameterTypeRequiredDescription
companyIduint64requiredUnique identifier of the Company.
Response description
PropertyTypeDescription
companyRespIdAn object to contain the "id" of the Company to which the array of DispatchJobs belong.
company.iduint64?Identifier given as input for the command.
dispatchJobsArray.<DispatchJob>The list of requested DispatchJobs.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response structure
{
	"company": {
		"id": number
	},
	"dispatchJobs": [
		{
			"asset": number,
			"attachments": [
				number
			],
			"company": number,
			"created": string,
			"forms": [
				number
			],
			"id": number,
			"instructions": string,
			"labels": [
				string
			],
			"name": string,
			"priority": string,
			"references": {
				string: string
			},
			"steps": [
				{
					"address": string,
					"duration": string,
					"eta": string,
					"latlng": {
						"lat": number,
						"lng": number
					},
					"name": string,
					"notes": string,
					"place": number,
					"signatory": string,
					"signature": boolean,
					"states": {
						string: {
							"latlng": {
								"lat": number,
								"lng": number
							},
							"updated": string
						}
					}
				}
			],
			"tags": [
				string
			],
			"v": [
				number
			]
		}
	],
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}
Possible exceptions
HTTP StatusError CodeDescription
4003The request does not contain a company object, or it is invalid.
4003The company object does not contain an id, or it is invalid.
4015You do not have permission to view DispatchJobs.
4015You do not have permission to view Assets.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
40428The Company containing the DispatchJobs was not found.

GET/companies/{companyId}/assets/dispatch/jobs?labels={string}

Gets the list of DispatchJobs for the specified Company only if the DispatchJob.labels matches all of the given labels.
URL Parameters
ParameterTypeRequiredDescription
companyIduint64requiredUnique identifier of the Company.
labelsstringrequiredLabels to match the DispatchJob.
Response description
PropertyTypeDescription
companyRespIdAn object to contain the "id" of the Company to which the array of DispatchJobs belong.
company.iduint64?Identifier given as input for the command.
dispatchJobsArray.<DispatchJob>The list of requested DispatchJobs.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
labelsArray.<string>The labels given as input.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response structure
{
	"company": {
		"id": number
	},
	"dispatchJobs": [
		{
			"asset": number,
			"attachments": [
				number
			],
			"company": number,
			"created": string,
			"forms": [
				number
			],
			"id": number,
			"instructions": string,
			"labels": [
				string
			],
			"name": string,
			"priority": string,
			"references": {
				string: string
			},
			"steps": [
				{
					"address": string,
					"duration": string,
					"eta": string,
					"latlng": {
						"lat": number,
						"lng": number
					},
					"name": string,
					"notes": string,
					"place": number,
					"signatory": string,
					"signature": boolean,
					"states": {
						string: {
							"latlng": {
								"lat": number,
								"lng": number
							},
							"updated": string
						}
					}
				}
			],
			"tags": [
				string
			],
			"v": [
				number
			]
		}
	],
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"labels": [
		string
	],
	"message": string,
	"reqId": number
}
Possible exceptions
HTTP StatusError CodeDescription
4003The request does not contain a company object, or it is invalid.
4003The company object does not contain an id, or it is invalid.
4003The labels is not an array.
4015You do not have permission to view any DispatchJobs for this Company.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
40428The Company was not found by its unique identifier.

GET/companies/{companyId}/assets/dispatch/tasks?{keys=values}?{keys=values}

Gets the list of DispatchTasks for the specified Company only if the specified reference fields match. If no references are specified, it will match any DispatchTask with no references. If a reference value is null, it will match any DispatchTask without that reference key.
URL Parameters
ParameterTypeRequiredDescription
companyIduint64requiredUnique identifier of the Company.
Response description
PropertyTypeDescription
companyRespIdAn object to contain the "id" of the Company to which the array of DispatchTasks belong.
company.iduint64?Identifier given as input for the command.
dispatchTasksArray.<DispatchTask>The list of requested DispatchTasks.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
referencesObject.<string, string>The reference string given as input.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response structure
{
	"company": {
		"id": number
	},
	"dispatchTasks": [
		{
			"address": string,
			"arrived": string,
			"asset": number,
			"attachments": [
				number
			],
			"company": number,
			"completed": string,
			"created": string,
			"duration": string,
			"eta": string,
			"id": number,
			"instructions": string,
			"latlng": {
				"lat": number,
				"lng": number
			},
			"name": string,
			"notes": string,
			"place": number,
			"reference": string,
			"references": {
				string: string
			},
			"signatory": string,
			"signature": boolean,
			"status": string,
			"v": [
				number
			]
		}
	],
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"references": {
		string: string
	},
	"reqId": number
}
Possible exceptions
HTTP StatusError CodeDescription
4003The request does not contain a company object, or it is invalid.
4003The request does not contain a references object, or it is invalid.
4003The company object does not contain an id, or it is invalid.
4015You do not have permission to view DispatchTasks.
4015You do not have permission to view Assets.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
40428The Company containing the DispatchTasks was not found.

GET/companies/{companyId}/assets/dispatch/tasks

Gets the list of DispatchTasks for the specified Company.
URL Parameters
ParameterTypeRequiredDescription
companyIduint64requiredUnique identifier of the Company.
Response description
PropertyTypeDescription
companyRespIdAn object to contain the "id" of the Company to which the array of DispatchTasks belong.
company.iduint64?Identifier given as input for the command.
dispatchTasksArray.<DispatchTask>The list of requested DispatchTasks.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response structure
{
	"company": {
		"id": number
	},
	"dispatchTasks": [
		{
			"address": string,
			"arrived": string,
			"asset": number,
			"attachments": [
				number
			],
			"company": number,
			"completed": string,
			"created": string,
			"duration": string,
			"eta": string,
			"id": number,
			"instructions": string,
			"latlng": {
				"lat": number,
				"lng": number
			},
			"name": string,
			"notes": string,
			"place": number,
			"reference": string,
			"references": {
				string: string
			},
			"signatory": string,
			"signature": boolean,
			"status": string,
			"v": [
				number
			]
		}
	],
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}
Possible exceptions
HTTP StatusError CodeDescription
4003The request does not contain a company object, or it is invalid.
4003The company object does not contain an id, or it is invalid.
4015You do not have permission to view DispatchTasks.
4015You do not have permission to view Assets.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
40428The Company containing the DispatchTasks was not found.

GET/dispatch/jobs

This request is an alias of /companies/{your-company-id}/assets/dispatch/jobs?{keys=values} (when No at least query-string key/value is given) or /companies/{your-company-id}/assets/dispatch/jobs (when No query-string parameters are given).
URL Parameters
ParameterTypeRequiredDefaultDescription
your-company-iduint64aliased{your-company-id}Your own Company's identifier.

PATCH/dispatch/jobs

Creates multiple new, or updates multiple existing DispatchJobs.
HTTP Request body description
PropertyTypeRequiredDescription
dispatchJobsArray.<ParameterContent>optionalArray of parameters successfully parsed by the sub-command.
reqIdint32?optionalIdentifier used by external system to correlate requests to responses.
HTTP Request body structure
{
	"dispatchJobs": [
		{
			"asset": number,
			"attachments": [
				number
			],
			"company": number,
			"forms": [
				number
			],
			"id": number,
			"instructions": string,
			"labels": [
				string
			],
			"name": string,
			"priority": string,
			"references": {
				string: string
			},
			"steps": [
				{
					"address": string,
					"duration": string,
					"eta": string,
					"latlng": {
						"lat": number,
						"lng": number
					},
					"name": string,
					"place": number,
					"signature": boolean
				}
			],
			"v": [
				number
			]
		}
	],
	"reqId": number
}
Response description
PropertyTypeDescription
dispatchJobsArray.<RespIdCompany>Array or responses successfully processed by the sub-command.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response structure
{
	"dispatchJobs": [
		{
			"company": number,
			"id": number
		}
	],
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}
Possible exceptions
HTTP StatusError CodeDescription
4003The request does not contain an operation collection, or it is invalid.
4003The operation collection is empty.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
429105Too many items exist in the operation collection.
500110One or more of the sub-operations failed, see errorDetails for more information.
Returns an ErrorDetailBatch as the errorDetails..

DELETE/dispatch/jobs

Deletes multiple DispatchJobs.
HTTP Request body description
PropertyTypeRequiredDescription
dispatchJobsArray.<ParamId>optionalArray of parameters successfully parsed by the sub-command.
reqIdint32?optionalIdentifier used by external system to correlate requests to responses.
HTTP Request body structure
{
	"dispatchJobs": [
		{
			"id": number
		}
	],
	"reqId": number
}
Response description
PropertyTypeDescription
dispatchJobsArray.<RespDeleted>Array or responses successfully processed by the sub-command.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response structure
{
	"dispatchJobs": [
		{
			"company": number,
			"deleted": boolean,
			"id": number,
			"v": [
				number
			]
		}
	],
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}
Possible exceptions
HTTP StatusError CodeDescription
4003The request does not contain an operation collection, or it is invalid.
4003The operation collection is empty.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
429105Too many items exist in the operation collection.
500110One or more of the sub-operations failed, see errorDetails for more information.
Returns an ErrorDetailBatch as the errorDetails..

GET/dispatch/jobs/{jobId}

Gets details of the specified DispatchJob.
URL Parameters
ParameterTypeRequiredDescription
jobIduint64requiredUnique identifier of the DispatchJob.
Response description
PropertyTypeDescription
dispatchJobDispatchJobThe requested DispatchJob.
dispatchJob.assetuint64?The Asset to which this job belongs. This value is null when unassigned.
dispatchJob.attachmentsArray.<uint64>
maximum-count: 10
for values see: Document.id
A list of hosted Document identifiers attached to this job.
dispatchJob.companyuint64The company to which this job belongs.
dispatchJob.createddatetimeWhen this job was originally created.
dispatchJob.formsArray.<uint64>
maximum-count: 10
for values see: FormResult.id
A list of hosted FormResult identifiers attached to this job.
dispatchJob.iduint64Unique identifier of this job.
dispatchJob.instructionsstringInstructions (filled out by dispatcher) for the field-employee to help them complete the job.
dispatchJob.labelsArray.<codified>
for values see: LabelStyle.code
Codified label names used to relate (unassigned) jobs to Assets.
dispatchJob.namestring
maximum-length: 100
A name for the work needed to be performed.
dispatchJob.priorityDispatchJobPriorityThe importance of this job when scheduling for an asset.
dispatchJob.referencesObject.<string, string>
maximum-count: 10
maximum-length of keys: 20
maximum-length of values: 100
Name/value collections of custom fields used to refer to external systems.
dispatchJob.stepsArray.<DispatchStep>A list of coordinates to visit in order to carry out the work for this job.
dispatchJob.tagsArray.<codified>
for values see: LabelStyle.code
The codified status tag names reflecting the conditions of this job.
dispatchJob.vArray.<uint32>Object version keys used to validate synchronization for all object properties.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response structure
{
	"dispatchJob": {
		"asset": number,
		"attachments": [
			number
		],
		"company": number,
		"created": string,
		"forms": [
			number
		],
		"id": number,
		"instructions": string,
		"labels": [
			string
		],
		"name": string,
		"priority": string,
		"references": {
			string: string
		},
		"steps": [
			{
				"address": string,
				"duration": string,
				"eta": string,
				"latlng": {
					"lat": number,
					"lng": number
				},
				"name": string,
				"notes": string,
				"place": number,
				"signatory": string,
				"signature": boolean,
				"states": {
					string: {
						"latlng": {
							"lat": number,
							"lng": number
						},
						"updated": string
					}
				}
			}
		],
		"tags": [
			string
		],
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}
Possible exceptions
HTTP StatusError CodeDescription
4003The request does not contain a dispatchJob object, or it is invalid.
4003The dispatchJob object does not contain an id, or it is invalid.
4015You do not have permission to view this DispatchJob.
4015You do not have permission to view the associated Asset.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
40420The DispatchJob was found, but the associated asset was not found.
40396The DispatchJob was found, but the associated asset is suspended. Before using any asset resources, it must be reactivated.
404139The DispatchJob was not found by its unique identifier.

POST/dispatch/jobs/{jobId}

Creates a new or updates an existing DispatchJob.
URL Parameters
ParameterTypeRequiredDescription
jobIduint64?optionalUnique identifier of the DispatchJob. This value is optional, and ignored by the command.
HTTP Request body description
PropertyTypeRequiredDescription
dispatchJobObject.<string, ?>alwaysThe details of a DispatchJob either for creation or update.
dispatchJob.assetuint64?optionalThe identifier of the Asset assigned to this DispatchJob.
dispatchJob.attachmentsArray.<uint64>
for values see: Document.id
optionalA list of Document identifiers to attach to this DispatchJob for both driver and dispatcher review.
dispatchJob.companyuint64?createThe identifier of the Company to which this DispatchJob belongs. After creation, this value is read-only.
dispatchJob.formsArray.<uint64>
for values see: FormResult.id
optionalA list of FormResult identifiers to attach to this DispatchJob.
dispatchJob.iduint64?updateThe unique identifier of the DispatchJob you want to update.
dispatchJob.instructionsstringoptionalInstructions for the driver to help them complete the DispatchJob. Such as which door to use, a buzz code to enter the facility, etc...
dispatchJob.labelsArray.<codified>
for values see: LabelStyle.code
optionalA list of codified label names used to relate (unassigned) DispatchJobs to Assets.
dispatchJob.namestring
maximum-length: 100
createName for the DispatchJob.
dispatchJob.priorityDispatchJobPriority?optionalThe importance of this job when scheduling for an asset.
dispatchJob.referencesObject.<string, string>optionalA custom field used to refer this DispatchJob an external system. Examples are a work order, pick-up, waybill, etc... If value is null, the field is removed from the DispatchJob. If a new value or null is not provided for a current attribute, no change is made.
dispatchJob.stepsArray.<ParamDispatchStep>createA list of coordinates to visit in order to carry out the work for this job.
dispatchJob.vArray.<int32>optional
reqIdint32?optionalIdentifier used by external system to correlate requests to responses.
HTTP Request body structure
{
	"dispatchJob": {
		"asset": number,
		"attachments": [
			number
		],
		"company": number,
		"forms": [
			number
		],
		"id": number,
		"instructions": string,
		"labels": [
			string
		],
		"name": string,
		"priority": string,
		"references": {
			string: string
		},
		"steps": [
			{
				"address": string,
				"duration": string,
				"eta": string,
				"latlng": {
					"lat": number,
					"lng": number
				},
				"name": string,
				"place": number,
				"signature": boolean
			}
		],
		"v": [
			number
		]
	},
	"reqId": number
}
Response description
PropertyTypeDescription
dispatchJobRespIdCompanyThe id, owning Company id and owning Asset id of the object requested/created.
dispatchJob.companyuint64Identifier of the Company to which this object belongs.
dispatchJob.iduint64?Identifier given as input for the command.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response structure
{
	"dispatchJob": {
		"company": number,
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}
Possible exceptions
HTTP StatusError CodeDescription
5002A communication error occurred.
If you receive this error, please contact technical support.
4003The request does not contain a dispatchJob object, or it is invalid.
4003Not enough keys exist in the dispatchJob object.
4003The request contains an invalid dispatchJob.steps array.
4003The request contains an invalid dispatchJob.references object.
4003The request contains an invalid dispatchJob.attachments array.
4003The request contains an invalid dispatchJob.forms array.
4003During create: When creating a new DispatchJob, a name was not given, or was blank.
4003During create: When creating a new DispatchJob, company was not given.
4003During create: When creating a new DispatchJob, not enough steps were given.
4003During create: When creating a new DispatchJob, a place, a latlng, or an address must be given for each step.
4003During update: When updating a DispatchJob, the new name cannot be blank.
4003During update: When updating a DispatchJob, not enough v values were given.
4003During update: When updating a DispatchJob, latlng cannot be set to null.
4003The dispatchJob.priority value is not a known DispatchJobPriority.
Returns an ErrorDetailEnum as the errorDetails..
4003The ParamDispatchStep.name was not given, or was blank.
Returns an ErrorDetailInput as the errorDetails..
4003The ParamDispatchStep.eta value is invalid.
Returns an ErrorDetailInput as the errorDetails..
4003The ParamDispatchStep.duration value is invalid.
Returns an ErrorDetailInput as the errorDetails..
4003The ParamDispatchStep.place value is invalid.
Returns an ErrorDetailInput as the errorDetails..
4003The ParamDispatchStep.latlng value is invalid.
Returns an ErrorDetailInput as the errorDetails..
4003The ParamDispatchStep.signature value is invalid.
Returns an ErrorDetailInput as the errorDetails..
4003Too many DispatchJob steps were given.
Returns an ErrorDetailMinMax as the errorDetails..
4003Too many DispatchJob references were given.
Returns an ErrorDetailMinMax as the errorDetails..
4003Too many DispatchJob attachements and forms were given.
Returns an ErrorDetailMinMax as the errorDetails..
4003During update: There are too many combined dispatchJob.references after adding the newly given keys.
Returns an ErrorDetailMinMax as the errorDetails..
4015You do not have permission to view the Asset to which the DispatchJob belongs.
4015During create: You do not have permission to create new DispatchJobs.
4015During update: You do not have permission to update DispatchJobs.
4006During update: When updating a DispatchJob, the wrong version key(s) were given.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
40420The Asset to which this DispatchJob is assigned was not found.
40440The Place being given for the DispatchJob was not found.
40171During update: Changing the labels on this DispatchJob in the requested way would grant you elevated access to it.
Returns an ErrorDetailEscalation as the errorDetails..
40481When giving only an address (not a Place or ParamDispatchStep.latlng), the address could not be geocoded.
40481When giving only an address (not a Place or ParamDispatchStep.latlng), the address was not street-level accurate enough.
Returns an ErrorDetailExternals as the errorDetails..
40396The Asset to which this DispatchJob is assigned is suspended. Before sending or updating DispatchJobs for a Asset, it must be reactivated.
404124One or more of the given attachments could not be found.
Returns an ErrorDetailBadIds as the errorDetails..
409130The dispatchJob.asset doesn't belong to the same Company as this DispatchJob
409130The dispatchJob.asset doesn't have any matching labels with this DispatchJob.
409130During update: When updating a DispatchJob, you cannot change the Company.
409130During update: When updating a DispatchJob, you cannot change the Asset to which it is assigned if any of the steps are underway.
404139During update: The DispatchJob was not found.

DELETE/dispatch/jobs/{jobId}

Deletes an existing DispatchJob.
URL Parameters
ParameterTypeRequiredDescription
jobIduint64requiredUnique identifier of the DispatchJob.
Response description
PropertyTypeDescription
dispatchJobRespDeletedThe id, owning Asset id, owning Company id, and deleted state.
dispatchJob.companyuint64Identifier of the Company to which this object belongs.
dispatchJob.deletedbooleanFlag showing if the object is deleted.
dispatchJob.iduint64?Identifier given as input for the command.
dispatchJob.vArray.<uint32>
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response structure
{
	"dispatchJob": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}
Possible exceptions
HTTP StatusError CodeDescription
4003The request does not contain a dispatchJob object, or it is invalid.
4003The dispatchJob object does not contain an id, or it is invalid.
4015You do not have permission to delete DispatchJobs.
4015You do not have permission to view the associated Asset.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
40420The DispatchJob was found, but the associated Asset was not found.
40396The DispatchJob was found, but the associated Asset is suspended. Before using any Asset resources, it must be reactivated.
404139The DispatchJob was not found by its unique identifier.

PATCH/dispatch/jobs/{jobId}/restore

Restores a deleted DispatchJob.
URL Parameters
ParameterTypeRequiredDescription
jobIduint64requiredUnique identifier of the DispatchJob.
Response description
PropertyTypeDescription
dispatchJobRespDeletedThe id, owning Asset id, owning Company id, and deleted state.
dispatchJob.companyuint64Identifier of the Company to which this object belongs.
dispatchJob.deletedbooleanFlag showing if the object is deleted.
dispatchJob.iduint64?Identifier given as input for the command.
dispatchJob.vArray.<uint32>
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response structure
{
	"dispatchJob": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}
Possible exceptions
HTTP StatusError CodeDescription
4003The request does not contain a dispatchJob object, or it is invalid.
4003The dispatchJob object does not contain an id, or it is invalid.
4015You do not have permission to create DispatchJobs.
4015You do not have permission to view the associated Asset.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
404139The DispatchJob was not found by its unique identifier.
400140The DispatchJob was found, but is not marked as deleted.

GET/dispatch/jobs?labels={string}

This request is an alias of /companies/{your-company-id}/assets/dispatch/jobs?labels={labels}.
URL Parameters
ParameterTypeRequiredDefaultDescription
labelsstringoptionalLabels to match the DispatchJob.
your-company-iduint64aliased{your-company-id}Your own Company's identifier.

GET/dispatch/tasks

This request is an alias of /companies/{your-company-id}/assets/dispatch/tasks?{keys=values} (when No at least query-string key/value is given) or /companies/{your-company-id}/assets/dispatch/tasks (when No query-string parameters are given).
URL Parameters
ParameterTypeRequiredDefaultDescription
your-company-iduint64aliased{your-company-id}Your own Company's identifier.

PATCH/dispatch/tasks

Creates multiple new, or updates multiple existing DispatchTasks.
HTTP Request body description
PropertyTypeRequiredDescription
dispatchTasksArray.<ParameterContent>optionalArray of parameters successfully parsed by the sub-command.
reqIdint32?optionalIdentifier used by external system to correlate requests to responses.
HTTP Request body structure
{
	"dispatchTasks": [
		{
			"address": string,
			"asset": number,
			"attachments": [
				number
			],
			"duration": string,
			"eta": string,
			"id": number,
			"instructions": string,
			"latlng": {
				"lat": number,
				"lng": number
			},
			"name": string,
			"notes": string,
			"place": number,
			"references": {
				string: string
			},
			"status": string,
			"v": [
				number
			]
		}
	],
	"reqId": number
}
Response description
PropertyTypeDescription
dispatchTasksArray.<RespIdAsset>Array or responses successfully processed by the sub-command.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response structure
{
	"dispatchTasks": [
		{
			"asset": number,
			"company": number,
			"id": number
		}
	],
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}
Possible exceptions
HTTP StatusError CodeDescription
4003The request does not contain an operation collection, or it is invalid.
4003The operation collection is empty.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
429105Too many items exist in the operation collection.
500110One or more of the sub-operations failed, see errorDetails for more information.
Returns an ErrorDetailBatch as the errorDetails..

DELETE/dispatch/tasks

Deletes multiple DispatchTasks.
HTTP Request body description
PropertyTypeRequiredDescription
dispatchTasksArray.<ParamId>optionalArray of parameters successfully parsed by the sub-command.
reqIdint32?optionalIdentifier used by external system to correlate requests to responses.
HTTP Request body structure
{
	"dispatchTasks": [
		{
			"id": number
		}
	],
	"reqId": number
}
Response description
PropertyTypeDescription
dispatchTasksArray.<RespAssetDeleted>Array or responses successfully processed by the sub-command.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response structure
{
	"dispatchTasks": [
		{
			"asset": number,
			"company": number,
			"deleted": boolean,
			"id": number,
			"v": [
				number
			]
		}
	],
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}
Possible exceptions
HTTP StatusError CodeDescription
4003The request does not contain an operation collection, or it is invalid.
4003The operation collection is empty.
4017You cannot execute this command because your session has expired.
5028You cannot execute this command because you are not logged in.
40316You cannot execute this command because your password has expired.
429105Too many items exist in the operation collection.
500110One or more of the sub-operations failed, see errorDetails for more information.
Returns an ErrorDetailBatch as the errorDetails..
</