WebSocket Reference

Download JSDoc Helper
©2024 Trak-iT Wireless Inc.
Updated Wednesday August 21, 2024 10:22AM
Version 19.28.04
Beta end-point:
wss://kraken.trakit.ca/
Production end-point:
wss://socket.trakit.ca/

API Definitions

BroadcastTypestring

The kinds of broadcast messages sent to all connected clients.

Value	Description
maintenance	Notification of impending maintenance window involving downtime. During a maintenance window, the service may go down and come back online repeatedly until the window ends.
upgrade	Notification that an upgrade will be available.

connectionobject

This is the first message sent after a connection has been initialized. If you begin sending messages before receiving the connectionResponse message, your connection may be closed abruptly.

JSON description

Property	Type	Description
client		The KrakenClient that invoked the command.
isLogin	boolean	Set in the ctor, will be true if this connection doesn't come with a ghostId, but a username/password.
killUnauthenticated	boolean	Disabled so expired/invalid sessions aren't killed during cleanup.
name	string	The name is used to create a well formed response during the answer phase.
requestBody	string
requestJson	Json.Linq.JObject
session		The socket user's session. This value is null until after HttpResponseMessage) is invoked (in the pipeline).
updateSession	boolean	Overridden because we always want to log when a session creates a new connection or logs in.

JSON structure

{
	"client": {
	},
	"isLogin": boolean,
	"killUnauthenticated": boolean,
	"name": string,
	"requestBody": string,
	"requestJson": Json.Linq.JObject,
	"session": {
	},
	"updateSession": boolean
}

getSubscriptionsList

Gets the list of current subscriptions for this socket.

Request message description

Property	Type	Required	Description
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

Request message structure

getSubscriptionsList {
	"reqId": number
}

Response message description

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

Response message structure

getSubscriptionsListResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number,
	"subscriptions": [
		{
			"company": number,
			"subscriptionTypes": [
				string
			]
		}
	]
}

Possible exceptions

Error Code	Description
7	You cannot execute this command because your session has expired.
8	You cannot execute this command because you are not logged in.
16	You cannot execute this command because your password has expired.

getTimezone

Gets details of the specified Timezone.

Request message description

Property	Type	Required	Description
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.
timezone	ParamCode	always	An object to contain the "code" of the Timezone.
timezone.code	string	always	A "code" identifying a resource.

Request message structure

getTimezone {
	"reqId": number,
	"timezone": {
		"code": string
	}
}

Response message description

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

Response message structure

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

Possible exceptions

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

getTimezonesList

Gets a list of Timezones.

Request message description

Property	Type	Required	Description
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

Request message structure

getTimezonesList {
	"reqId": number
}

Response message description

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

Response message structure

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

Possible exceptions

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

noop

Performs no operation, but will return an error if you are not logged in.

Request message description

Property	Type	Required	Description
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

Request message structure

noop {
	"reqId": number
}

Response message description

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

Response message structure

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

Possible exceptions

Error Code	Description
7	Your session is invalid or expired.
7	You cannot execute this command because your session has expired.
8	You haven't logged in yet.
8	You cannot execute this command because you are not logged in.
16	You are logged in, but your pasword is expired.
16	You cannot execute this command because your password has expired.

Subscribes the socket to receive notifications for merge/delete changes to objects.

Request message description

Property	Type	Required	Description
company	ParamId see: Company.id	always	An object to contain the "id" key.
company.id	uint64	always	Identifier given as input for the command.
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.
subscriptionTypes	Array.<SubscriptionType>	always	The list of subscription types you want to receive.

Request message structure

subscribe {
	"company": {
		"id": number
	},
	"reqId": number,
	"subscriptionTypes": [
		string
	]
}

Response message description

Property	Type	Description
company	RespId see: Company.id	An object which contains only one key "id" when there is no error. The "id" key is the unique identifier of the company to which the array of objects relate.
company.id	uint64?	Identifier given as input for the command.
denied	Array.<SubscriptionType>	Subscription types not added to your socket due to insufficient permissions.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
invalid	Array.<string>	A returned list of nonsense you sent to my beautiful service.
merged	Array.<SubscriptionType>	Subscription types added/removed (or were not applicable) to your socket's subscription list.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

subscribeResponse {
	"company": {
		"id": number
	},
	"denied": [
		string
	],
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"invalid": [
		string
	],
	"merged": [
		string
	],
	"message": string,
	"reqId": number
}

Possible exceptions

Error Code	Description
3	The request does not contain a company or it is invalid.
3	The request does not contain a subscriptionTypes or it is invalid.
3	The given subscriptionTypes is empty.
5	Access was denied for all subscription types. This error is not returned if at least one subscription type succeeds. Returns an ErrorDetailBadKeys as the `errorDetails`.
7	You cannot execute this command because your session has expired.
8	You cannot execute this command because you are not logged in.
9	Your session has expired during pocessing.
16	You cannot execute this command because your password has expired.

Subscriptionobject

Contains a Company.id and an array of SubscriptionTypes for each Company.

JSON description

Property	Type	Description
company	uint64 see: Company.id	The company relevant to the subscription types you want to receive.
subscriptionTypes	Array.<SubscriptionType>	List of subscription types for the company.

JSON structure

{
	"company": number,
	"subscriptionTypes": [
		string
	]
}

SubscriptionTypestring

The types of subscriptions available using subscribe/unsubscribe. Each type has a different synchronization messages and objects.

Value	Message Name	Message Objects	Description
assetAdvanced	assetAdvanced	AssetAdvanced VehicleAdvanced	Assets' advanced properties such as position, attributes, and status tags.
assetDispatch	assetDispatch	AssetDispatch	Assets' current dispatch such as DispatchJobs and route progress.
assetGeneral	assetDeleted assetGeneral assetSuspended	AssetDeleted AssetGeneral AssetSuspended PersonGeneral TrailerGeneral VehicleGeneral	Assets' general properties such as name, icon, and labels.
assetMessage	assetMessage assetMessageDeleted	AssetMessage AssetMessageDeleted	AssetMessages between Assets and Users.
behaviour	behaviour behaviourDeleted	Behaviour BehaviourDeleted	Configured behaviours.
behaviourLog	behaviourLog behaviourLogDeleted	BehaviourLog BehaviourLogDeleted	Behaviour log messages to help developers debug their BehaviourScript.
behaviourScript	behaviourScript behaviourScriptDeleted	BehaviourScript BehaviourScriptDeleted	Behaviour script logic.
billingDiscount			Discount rules for Assets.
billingHosting	billableHostingRule billableHostingRuleDeleted	BillableHostingRule BillableHostingRuleDeleted	Billing rules for Assets.
billingLicense	billableHostingLicense billableHostingLicenseDeleted	BillableHostingLicense BillableHostingLicenseDeleted	Hardware licenses for Providers.
billingProfile	billingProfile billingProfileDeleted	BillingProfile BillingProfileDeleted	Profiles used to generate BillingReport for a customer.
billingReport	billingReport billingReportDeleted	BillingReport BillingReportDeleted	Reports generated for a billee Company.
companyGeneral	companyDeleted companyGeneral	CompanyDeleted CompanyGeneral	Renaming and changing the nodes of a company.
companyLabels	companyStyles	CompanyStyles	Company's label and tag styles.
companyPolicies	companyPolicies	CompanyPolicies	Company's SessionPolicy and PasswordPolicy.
companyReseller	companyReseller companyResellerDeleted	CompanyReseller CompanyResellerDeleted	A Company's white-labelling details.
contact	contact contactDeleted	Contact ContactDeleted	Contact information used by Assets and Users.
dispatchJob	dispatchJob dispatchJobDeleted	DispatchJob DispatchJobDeleted	Some work that needs to be done by performing one or more DispatchSteps.
dispatchTask	dispatchTask dispatchTaskDeleted	DispatchTask DispatchTaskDeleted	Assets' DispatchTask information.
document	document documentDeleted	Document DocumentDeleted	Hosted document information.
formResult	formResult formResultDeleted	FormResult FormResultDeleted	Forms that are completed and fully filled out.
formTemplate	formTemplate formTemplateDeleted	FormTemplate FormTemplateDeleted	Customized forms to be filled.
icon	icon iconDeleted	Icon IconDeleted	Synchronizes icon information.
machine	machine machineDeleted	Machine MachineDeleted	API Credentials information and permissions.
maintenanceJob	maintenanceJob maintenanceJobDeleted	MaintenanceJob MaintenanceJobDeleted	Historical Vehicle and Trailer maintenance work.
maintenanceSchedule	maintenanceSchedule maintenanceScheduleDeleted	MaintenanceSchedule MaintenanceScheduleDeleted	Recurring maintenance work for Vehicles and Trailers.
picture	picture pictureDeleted	Picture PictureDeleted	Synchronizes picture information.
placeGeneral	placeDeleted placeGeneral	PlaceDeleted PlaceGeneral	Place information.
providerAdvanced	providerAdvanced	ProviderAdvanced	Raw provider (device) data like GPS coordinates and parsed ODB-II values.
providerConfig	providerConfig providerConfigDeleted	ProviderConfig ProviderConfigDeleted	Provider (device) configurations.
providerConfiguration Deprecated	providerConfiguration providerConfigurationDeleted	ProviderConfiguration ProviderConfigurationDeleted	Provider (device) configurations. Use providerConfig instead.
providerGeneral	providerDeleted providerGeneral providerSuspended	ProviderDeleted ProviderGeneral ProviderSuspended	Providers' (device) general properties such as name, notes, and selected Asset.
providerRegistration	providerRegistration providerRegistrationDeleted	ProviderRegistration ProviderRegistrationDeleted	Pending Providers (devices) that have not yet been configured or provisioned.
providerScript	providerScript providerScriptDeleted	ProviderScript ProviderScriptDeleted	Provider (device) script logic.
reportResult	reportResult reportResultDeleted	ReportResult ReportResultDeleted	Historical asset details like breadcrumb trails.
reportSchedule	reportSchedule reportScheduleDeleted	ReportSchedule ReportScheduleDeleted	Schedules for reports that run automatically.
reportTemplate	reportTemplate reportTemplateDeleted	ReportTemplate ReportTemplateDeleted	Report configurations.
userAdvanced	userAdvanced	UserAdvanced	User information such as permissions and group membership.
userGeneral	userDeleted userGeneral	UserDeleted UserGeneral	General user information such as name, contact information, and preferences.
userGroup	userGroup userGroupDeleted	UserGroup UserGroupDeleted	Group information for easy access control.

unknownCommandobject

A Text message was received by the server, but the prefix of the message (before the first space) was not found in the known commands list.

JSON description

Property	Type	Description
client		The KrakenClient that invoked the command.
killUnauthenticated	boolean	If the error for this session is not an authenticated user (session expired/not yet logged in), close connection after command completes
name	string	The name is used to create a well formed response during the answer phase.
requestBody	string
requestJson	Json.Linq.JObject
session		The socket user's session. This value is null until after HttpResponseMessage) is invoked (in the pipeline).
updateSession	boolean

JSON structure

{
	"client": {
	},
	"killUnauthenticated": boolean,
	"name": string,
	"requestBody": string,
	"requestJson": Json.Linq.JObject,
	"session": {
	},
	"updateSession": boolean
}

unknownMessageobject

A message was received, but it was not a Text or Close, and so cannot be processed.

JSON description

Property	Type	Description
client		The KrakenClient that invoked the command.
killUnauthenticated	boolean	If the error for this session is not an authenticated user (session expired/not yet logged in), close connection after command completes
name	string	The name is used to create a well formed response during the answer phase.
requestBody	string
requestJson	Json.Linq.JObject
session		The socket user's session. This value is null until after HttpResponseMessage) is invoked (in the pipeline).
updateSession	boolean

JSON structure

{
	"client": {
	},
	"killUnauthenticated": boolean,
	"name": string,
	"requestBody": string,
	"requestJson": Json.Linq.JObject,
	"session": {
	},
	"updateSession": boolean
}

unsubscribe

Unsubscribes the socket from receiving notifications for merge/delete changes to objects.

Request message description

Property	Type	Required	Description
company	ParamId see: Company.id	always	An object to contain the "id" key.
company.id	uint64	always	Identifier given as input for the command.
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.
subscriptionTypes	Array.<SubscriptionType>	always	The list of subscription types you want to receive.

Request message structure

unsubscribe {
	"company": {
		"id": number
	},
	"reqId": number,
	"subscriptionTypes": [
		string
	]
}

Response message description

Property	Type	Description
company	RespId see: Company.id	An object which contains only one key "id" when there is no error. The "id" key is the unique identifier of the company to which the array of objects relate.
company.id	uint64?	Identifier given as input for the command.
denied	Array.<SubscriptionType>	Subscription types not added to your socket due to insufficient permissions.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
invalid	Array.<string>	A returned list of nonsense you sent to my beautiful service.
merged	Array.<SubscriptionType>	Subscription types added/removed (or were not applicable) to your socket's subscription list.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

unsubscribeResponse {
	"company": {
		"id": number
	},
	"denied": [
		string
	],
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"invalid": [
		string
	],
	"merged": [
		string
	],
	"message": string,
	"reqId": number
}

Possible exceptions

Error Code	Description
3	The request does not contain a company or it is invalid.
3	The request does not contain a subscriptionTypes or it is invalid.
3	The given subscriptionTypes is empty.
5	Access was denied for all subscription types. This error is not returned if at least one subscription type succeeds. Returns an ErrorDetailBadKeys as the `errorDetails`.
7	You cannot execute this command because your session has expired.
8	You cannot execute this command because you are not logged in.
9	Your session has expired during pocessing.
16	You cannot execute this command because your password has expired.

Assets

getAsset

Gets details of the specified Asset. The RESTful service does not return Asset.tasks or Asset.messages by default, but for the WebSocket the includeDispatch and includeDispatch will default to true. This behaviour will be deprecated in a future release to match the RESTful service.

Request message description

Property	Type	Required	Default	Description
asset	ParamId	always		An object to contain the "id" of the Asset.
asset.id	uint64	always		Identifier given as input for the command.
includeDeleted	boolean	optional	`false`	When true, the command will also return a deleted Asset.
includeMessages	boolean	optional	`false`	When true, the command will also return AssetMessages for the asset.
includeTasks	boolean	optional	`false`	When true, the command will also return the AssetDispatch for the asset.
reqId	int32?	optional		Identifier used by external system to correlate requests to responses.

Request message structure

getAsset {
	"asset": {
		"id": number
	},
	"includeDeleted": boolean,
	"includeMessages": boolean,
	"includeTasks": boolean,
	"reqId": number
}

Response message description

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

Response message structure

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

Possible exceptions

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

getAssetsList

Gets the list of Assets for the specified Company. The RESTful service does not return Asset.tasks or Asset.messages by default, but for the WebSocket the includeTasks and includeTasks will default to true. This behaviour will be deprecated in a future release to match the RESTful service.

Request message description

Property	Type	Required	Default	Description
company	ParamId	always		An object to contain the "id" of the Company.
company.id	uint64	always		Identifier given as input for the command.
highest	uint64?	optional
includeArchive	boolean	optional		Takes the value of includeDeleted when not specified. When true, the command will also return archived objects.
includeDeleted	boolean	optional	`false`	When true, the command will also return deleted objects.
includeMessages	boolean	optional	`false`	When true, the command will also return AssetMessages for the asset.
includeSuspended	boolean	optional	`true`	When true, the command will also return suspended Assets.
includeTasks	boolean	optional	`false`	When true, the command will also return DispatchTasks for the asset.
limit	uint16?	optional		Maximum number of objects in this response.
lowest	uint64?	optional
reqId	int32?	optional		Identifier used by external system to correlate requests to responses.

Request message structure

getAssetsList {
	"company": {
		"id": number
	},
	"highest": number,
	"includeArchive": boolean,
	"includeDeleted": boolean,
	"includeMessages": boolean,
	"includeSuspended": boolean,
	"includeTasks": boolean,
	"limit": number,
	"lowest": number,
	"reqId": number
}

Response message description

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

Response message structure

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

Possible exceptions

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

getAssetsListByReference

Gets the list of Assets for the specified Company only if the Asset.reference field is a match. The RESTful service does not return Asset.tasks or Asset.messages by default, but for the WebSocket the includeTasks and includeTasks will default to true. This behaviour will be deprecated in a future release to match the RESTful service.

Request message description

Property	Type	Required	Default	Description
company	ParamId	always		An object to contain the "id" of the Company.
company.id	uint64	always		Identifier given as input for the command.
highest	uint64?	optional
includeArchive	boolean	optional		Takes the value of includeDeleted when not specified. When true, the command will also return archived objects.
includeDeleted	boolean	optional	`false`	When true, the command will also return deleted objects.
includeMessages	boolean	optional	`false`	When true, the command will also return AssetMessages for the asset.
includeSuspended	boolean	optional	`true`	When true, the command will also return suspended Assets.
includeTasks	boolean	optional	`false`	When true, the command will also return DispatchTasks for the asset.
limit	uint16?	optional		Maximum number of objects in this response.
lowest	uint64?	optional
reference	string see: AssetGeneral.reference	optional		Case-insensitive reference used to match Assets.
reqId	int32?	optional		Identifier used by external system to correlate requests to responses.

Request message structure

getAssetsListByReference {
	"company": {
		"id": number
	},
	"highest": number,
	"includeArchive": boolean,
	"includeDeleted": boolean,
	"includeMessages": boolean,
	"includeSuspended": boolean,
	"includeTasks": boolean,
	"limit": number,
	"lowest": number,
	"reference": string,
	"reqId": number
}

Response message description

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

Response message structure

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

Possible exceptions

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

getAssetsListByReferences

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. The RESTful service does not return Asset.tasks or Asset.messages by default, but for the WebSocket the includeTasks and includeTasks will default to true. This behaviour will be deprecated in a future release to match the RESTful service.

Request message description

Property	Type	Required	Default	Description
company	ParamId	always		An object to contain the "id" of the Company.
company.id	uint64	always		Identifier given as input for the command.
highest	uint64?	optional
includeArchive	boolean	optional		Takes the value of includeDeleted when not specified. When true, the command will also return archived objects.
includeDeleted	boolean	optional	`false`	When true, the command will also return deleted objects.
includeMessages	boolean	optional	`false`	When true, the command will also return AssetMessages for the asset.
includeSuspended	boolean	optional	`true`	When true, the command will also return suspended Assets.
includeTasks	boolean	optional	`false`	When true, the command will also return DispatchTasks for the asset.
limit	uint16?	optional		Maximum number of objects in this response.
lowest	uint64?	optional
references	Object.<string, string> see: AssetGeneral.references	optional		Case-insensitive reference pairs used to match Assets.
reqId	int32?	optional		Identifier used by external system to correlate requests to responses.

Request message structure

getAssetsListByReferences {
	"company": {
		"id": number
	},
	"highest": number,
	"includeArchive": boolean,
	"includeDeleted": boolean,
	"includeMessages": boolean,
	"includeSuspended": boolean,
	"includeTasks": boolean,
	"limit": number,
	"lowest": number,
	"references": {
		string: string
	},
	"reqId": number
}

Response message description

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

Response message structure

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

Possible exceptions

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

mergeAsset

Creates a new, or updates an existing Asset.

Request message description

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

Request message structure

mergeAsset {
	"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 message description

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

Response message structure

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

Possible exceptions

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

removeAsset

Deletes an existing Asset.

Request message description

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

Request message structure

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

Response message description

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

Response message structure

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

Possible exceptions

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

restoreAsset

Restores the specified Asset.

Request message description

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

Request message structure

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

Response message description

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

Response message structure

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

Possible exceptions

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

reviveAsset

Revives (disables suspension on) an existing Asset.

Request message description

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

Request message structure

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

Response message description

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

Response message structure

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

Possible exceptions

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

suspendAsset

Suspends an existing Asset.

Request message description

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

Request message structure

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

Response message description

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

Response message structure

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

Possible exceptions

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

Behaviours

clearBehaviourLogsByAsset

Gets the list of BehaviourLogs for the specified Asset.

Request message description

Property	Type	Required	Default	Description
asset	ParamId	always		An object to contain the "id" of the Asset.
asset.id	uint64	always		Identifier given as input for the command.
highest	uint64?	optional
includeArchive	boolean	optional
includeDeleted	boolean	optional	`false`	When true, the command will also return deleted objects.
limit	uint16?	optional		Maximum number of objects in this response.
lowest	uint64?	optional
reqId	int32?	optional		Identifier used by external system to correlate requests to responses.

Request message structure

clearBehaviourLogsByAsset {
	"asset": {
		"id": number
	},
	"highest": number,
	"includeArchive": boolean,
	"includeDeleted": boolean,
	"limit": number,
	"lowest": number,
	"reqId": number
}

Response message description

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

Response message structure

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

Possible exceptions

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

clearBehaviourLogsByBehaviour

Gets the list of BehaviourLogs for the specified Behaviour.

Request message description

Property	Type	Required	Default	Description
behaviour	ParamId	always		An object to contain the "id" of the Behaviour.
behaviour.id	uint64	always		Identifier given as input for the command.
highest	uint64?	optional
includeArchive	boolean	optional
includeDeleted	boolean	optional	`false`	When true, the command will also return deleted objects.
limit	uint16?	optional		Maximum number of objects in this response.
lowest	uint64?	optional
reqId	int32?	optional		Identifier used by external system to correlate requests to responses.

Request message structure

clearBehaviourLogsByBehaviour {
	"behaviour": {
		"id": number
	},
	"highest": number,
	"includeArchive": boolean,
	"includeDeleted": boolean,
	"limit": number,
	"lowest": number,
	"reqId": number
}

Response message description

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

Response message structure

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

Possible exceptions

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

clearBehaviourLogsByScript

Gets the list of BehaviourLogs for the specified BehaviourScript.

Request message description

Property	Type	Required	Default	Description
behaviourScript	ParamId	always		An object to contain the "id" of the BehaviourScript.
behaviourScript.id	uint64	always		Identifier given as input for the command.
highest	uint64?	optional
includeArchive	boolean	optional
includeDeleted	boolean	optional	`false`	When true, the command will also return deleted objects.
limit	uint16?	optional		Maximum number of objects in this response.
lowest	uint64?	optional
reqId	int32?	optional		Identifier used by external system to correlate requests to responses.

Request message structure

clearBehaviourLogsByScript {
	"behaviourScript": {
		"id": number
	},
	"highest": number,
	"includeArchive": boolean,
	"includeDeleted": boolean,
	"limit": number,
	"lowest": number,
	"reqId": number
}

Response message description

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

Response message structure

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

Possible exceptions

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

getBehaviour

Gets details of the specified Behaviour.

Request message description

Property	Type	Required	Default	Description
behaviour	ParamId	always		An object to contain the "id" key.
behaviour.id	uint64	always		Identifier given as input for the command.
includeDeleted	boolean	optional	`false`	When true, the command will also return a deleted Behaviour.
reqId	int32?	optional		Identifier used by external system to correlate requests to responses.

Request message structure

getBehaviour {
	"behaviour": {
		"id": number
	},
	"includeDeleted": boolean,
	"reqId": number
}

Response message description

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

Response message structure

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

Possible exceptions

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

getBehaviourLogsListByAsset

Gets the list of BehaviourLogs for the specified Asset.

Request message description

Property	Type	Required	Default	Description
asset	ParamId	always		An object to contain the "id" of the Asset.
asset.id	uint64	always		Identifier given as input for the command.
highest	uint64?	optional
includeArchive	boolean	optional		Takes the value of includeDeleted when not specified. When true, the command will also return archived objects.
includeDeleted	boolean	optional	`false`	When true, the command will also return deleted objects.
limit	uint16?	optional		Maximum number of objects in this response.
lowest	uint64?	optional
reqId	int32?	optional		Identifier used by external system to correlate requests to responses.

Request message structure

getBehaviourLogsListByAsset {
	"asset": {
		"id": number
	},
	"highest": number,
	"includeArchive": boolean,
	"includeDeleted": boolean,
	"limit": number,
	"lowest": number,
	"reqId": number
}

Response message description

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

Response message structure

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

Possible exceptions

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

getBehaviourLogsListByBehaviour

Gets the list of BehaviourLog for the specified Behaviour.

Request message description

Property	Type	Required	Default	Description
behaviour	ParamId	always		An object to contain the "id" of the Behaviour.
behaviour.id	uint64	always		Identifier given as input for the command.
highest	uint64?	optional
includeArchive	boolean	optional		Takes the value of includeDeleted when not specified. When true, the command will also return archived objects.
includeDeleted	boolean	optional	`false`	When true, the command will also return deleted objects.
limit	uint16?	optional		Maximum number of objects in this response.
lowest	uint64?	optional
reqId	int32?	optional		Identifier used by external system to correlate requests to responses.

Request message structure

getBehaviourLogsListByBehaviour {
	"behaviour": {
		"id": number
	},
	"highest": number,
	"includeArchive": boolean,
	"includeDeleted": boolean,
	"limit": number,
	"lowest": number,
	"reqId": number
}

Response message description

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

Response message structure

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

Possible exceptions

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

getBehaviourLogsListByScript

Gets the list of BehaviourLogs for the specified BehaviourScript.

Request message description

Property	Type	Required	Default	Description
behaviourScript	ParamId	always		An object to contain the "id" of the BehaviourScript.
behaviourScript.id	uint64	always		Identifier given as input for the command.
highest	uint64?	optional
includeArchive	boolean	optional		Takes the value of includeDeleted when not specified. When true, the command will also return archived objects.
includeDeleted	boolean	optional	`false`	When true, the command will also return deleted objects.
limit	uint16?	optional		Maximum number of objects in this response.
lowest	uint64?	optional
reqId	int32?	optional		Identifier used by external system to correlate requests to responses.

Request message structure

getBehaviourLogsListByScript {
	"behaviourScript": {
		"id": number
	},
	"highest": number,
	"includeArchive": boolean,
	"includeDeleted": boolean,
	"limit": number,
	"lowest": number,
	"reqId": number
}

Response message description

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

Response message structure

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

Possible exceptions

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

getBehaviourScript

Gets details of the specified BehaviourScript.

Request message description

Property	Type	Required	Default	Description
behaviourScript	ParamId	always		An object to contain the "id" key.
behaviourScript.id	uint64	always		Identifier given as input for the command.
includeDeleted	boolean	optional	`false`	When true, the command will also return a deleted BehaviourScript.
reqId	int32?	optional		Identifier used by external system to correlate requests to responses.

Request message structure

getBehaviourScript {
	"behaviourScript": {
		"id": number
	},
	"includeDeleted": boolean,
	"reqId": number
}

Response message description

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

Response message structure

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

Possible exceptions

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

getBehaviourScriptsList

Gets the list of BehaviourScripts for the specified Company.

Request message description

Property	Type	Required	Default	Description
company	ParamId	always		An object to contain the "id" of the Company.
company.id	uint64	always		Identifier given as input for the command.
highest	uint64?	optional
includeArchive	boolean	optional		Takes the value of includeDeleted when not specified. When true, the command will also return archived objects.
includeDeleted	boolean	optional	`false`	When true, the command will also return deleted objects.
limit	uint16?	optional		Maximum number of objects in this response.
lowest	uint64?	optional
reqId	int32?	optional		Identifier used by external system to correlate requests to responses.
tree	boolean	optional		When true (default) the getter to retrieve the given Company's list of BehaviourScripts as well as any publicly available BehaviourScripts for the Company's parent(s).

Request message structure

getBehaviourScriptsList {
	"company": {
		"id": number
	},
	"highest": number,
	"includeArchive": boolean,
	"includeDeleted": boolean,
	"limit": number,
	"lowest": number,
	"reqId": number,
	"tree": boolean
}

Response message description

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

Response message structure

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

Possible exceptions

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

getBehavioursList

Gets the list of Behaviours for the specified Company.

Request message description

Property	Type	Required	Default	Description
company	ParamId	always		An object to contain the "id" of the Company.
company.id	uint64	always		Identifier given as input for the command.
highest	uint64?	optional
includeArchive	boolean	optional		Takes the value of includeDeleted when not specified. When true, the command will also return archived objects.
includeDeleted	boolean	optional	`false`	When true, the command will also return deleted objects.
limit	uint16?	optional		Maximum number of objects in this response.
lowest	uint64?	optional
reqId	int32?	optional		Identifier used by external system to correlate requests to responses.

Request message structure

getBehavioursList {
	"company": {
		"id": number
	},
	"highest": number,
	"includeArchive": boolean,
	"includeDeleted": boolean,
	"limit": number,
	"lowest": number,
	"reqId": number
}

Response message description

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

Response message structure

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

Possible exceptions

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

mergeBehaviour

Creates a new or updates an existing Behaviour.

Request message description

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

Request message structure

mergeBehaviour {
	"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 message description

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

Response message structure

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

Possible exceptions

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

mergeBehaviourScript

Creates a new or updates an existing BehaviourScript.

Request message description

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

Request message structure

mergeBehaviourScript {
	"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 message description

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

Response message structure

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

Possible exceptions

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

removeBehaviour

Deletes a Behaviour.

Request message description

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

Request message structure

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

Response message description

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

Response message structure

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

Possible exceptions

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

removeBehaviourScript

Deletes an existing BehaviourScript.

Request message description

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

Request message structure

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

Response message description

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

Response message structure

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

Possible exceptions

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

restoreBehaviour

Restores a deleted Behaviour.

Request message description

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

Request message structure

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

Response message description

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

Response message structure

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

Possible exceptions

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

restoreBehaviourScript

Restores the specified BehaviourScript.

Request message description

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

Request message structure

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

Response message description

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

Response message structure

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

Possible exceptions

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

Billing

getBillingProfile

Gets details of the specified BillingProfile.

Request message description

Property	Type	Required	Default	Description
billingProfile	ParamId	always		An object to contain the "id" of the BillingProfile.
billingProfile.id	uint64	always		Identifier given as input for the command.
includeDeleted	boolean	optional	`false`	When true, the command will also return a deleted BillingProfile.
reqId	int32?	optional		Identifier used by external system to correlate requests to responses.

Request message structure

getBillingProfile {
	"billingProfile": {
		"id": number
	},
	"includeDeleted": boolean,
	"reqId": number
}

Response message description

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

Response message structure

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

Possible exceptions

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

getBillingProfilesList

Gets the list of BillingProfiles for the specified Company.

Request message description

Property	Type	Required	Default	Description
company	ParamId	always		An object to contain the "id" of the Company.
company.id	uint64	always		Identifier given as input for the command.
highest	uint64?	optional
includeArchive	boolean	optional		Takes the value of includeDeleted when not specified. When true, the command will also return archived objects.
includeDeleted	boolean	optional	`false`	When true, the command will also return deleted objects.
limit	uint16?	optional		Maximum number of objects in this response.
lowest	uint64?	optional
reqId	int32?	optional		Identifier used by external system to correlate requests to responses.

Request message structure

getBillingProfilesList {
	"company": {
		"id": number
	},
	"highest": number,
	"includeArchive": boolean,
	"includeDeleted": boolean,
	"limit": number,
	"lowest": number,
	"reqId": number
}

Response message description

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

Response message structure

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

Possible exceptions

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

getBillingReport

Gets details of the specified BillingReport.

Request message description

Property	Type	Required	Default	Description
billingReport	ParamId	always		An object to contain the "id" of the BillingReport.
billingReport.id	uint64	always		Identifier given as input for the command.
includeDeleted	boolean	optional	`false`	When true, the command will also return a deleted BillingReport.
reqId	int32?	optional		Identifier used by external system to correlate requests to responses.

Request message structure

getBillingReport {
	"billingReport": {
		"id": number
	},
	"includeDeleted": boolean,
	"reqId": number
}

Response message description

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

Response message structure

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

Possible exceptions

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

getBillingReportsList

Gets the list of BillingReports for the specified BillingProfile.

Request message description

Property	Type	Required	Default	Description
after	datetime	optional
before	datetime	optional
billingProfile	ParamId	always		An object to contain the "id" of the BillingProfile.
billingProfile.id	uint64	always		Identifier given as input for the command.
includeArchive	boolean	optional		Takes the value of includeDeleted when not specified. When true, the command will also return archived objects.
includeDeleted	boolean	optional	`false`	When true, the command will also return deleted objects.
limit	uint16?	optional		Maximum number of objects in this response.
reqId	int32?	optional		Identifier used by external system to correlate requests to responses.

Request message structure

getBillingReportsList {
	"after": string,
	"before": string,
	"billingProfile": {
		"id": number
	},
	"includeArchive": boolean,
	"includeDeleted": boolean,
	"limit": number,
	"reqId": number
}

Response message description

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

Response message structure

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

Possible exceptions

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

getBillingReportsListByCompany

Gets the list of BillingReports for the specified Company.

Request message description

Property	Type	Required	Default	Description
after	datetime	optional
before	datetime	optional
company	ParamId	always		An object to contain the "id" of the Company.
company.id	uint64	always		Identifier given as input for the command.
includeArchive	boolean	optional		Takes the value of includeDeleted when not specified. When true, the command will also return archived objects.
includeDeleted	boolean	optional	`false`	When true, the command will also return deleted objects.
limit	uint16?	optional		Maximum number of objects in this response.
reqId	int32?	optional		Identifier used by external system to correlate requests to responses.

Request message structure

getBillingReportsListByCompany {
	"after": string,
	"before": string,
	"company": {
		"id": number
	},
	"includeArchive": boolean,
	"includeDeleted": boolean,
	"limit": number,
	"reqId": number
}

Response message description

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

Response message structure

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

Possible exceptions

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

getHostingLicense

Gets details of the specified BillableHostingLicense.

Request message description

Property	Type	Required	Default	Description
hostingLicense	ParamId	always		An object to contain the "id" of the BillableHostingLicense.
hostingLicense.id	uint64	always		Identifier given as input for the command.
includeDeleted	boolean	optional	`false`	When true, the command will also return a deleted BillableHostingLicense.
reqId	int32?	optional		Identifier used by external system to correlate requests to responses.

Request message structure

getHostingLicense {
	"hostingLicense": {
		"id": number
	},
	"includeDeleted": boolean,
	"reqId": number
}

Response message description

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

Response message structure

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

Possible exceptions

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

getHostingLicensesList

Gets the list of BillableHostingLicenses for the specified BillingProfile.

Request message description

Property	Type	Required	Default	Description
billingProfile	ParamId	always		An object to contain the "id" of the BillingProfile.
billingProfile.id	uint64	always		Identifier given as input for the command.
highest	uint64?	optional
includeArchive	boolean	optional		Takes the value of includeDeleted when not specified. When true, the command will also return archived objects.
includeDeleted	boolean	optional	`false`	When true, the command will also return deleted objects.
limit	uint16?	optional		Maximum number of objects in this response.
lowest	uint64?	optional
reqId	int32?	optional		Identifier used by external system to correlate requests to responses.

Request message structure

getHostingLicensesList {
	"billingProfile": {
		"id": number
	},
	"highest": number,
	"includeArchive": boolean,
	"includeDeleted": boolean,
	"limit": number,
	"lowest": number,
	"reqId": number
}

Response message description

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

Response message structure

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

Possible exceptions

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

getHostingRule

Gets details of the specified BillableHostingRule.

Request message description

Property	Type	Required	Default	Description
hostingRule	ParamId	always		An object to contain the "id" of the BillableHostingRule.
hostingRule.id	uint64	always		Identifier given as input for the command.
includeDeleted	boolean	optional	`false`	When true, the command will also return a deleted BillableHostingRule.
reqId	int32?	optional		Identifier used by external system to correlate requests to responses.

Request message structure

getHostingRule {
	"hostingRule": {
		"id": number
	},
	"includeDeleted": boolean,
	"reqId": number
}

Response message description

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

Response message structure

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

Possible exceptions

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

getHostingRulesList

Creates new or updates an existing BillableHostingRule.

Request message description

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

Request message structure

getHostingRulesList {
	"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 message description

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

Response message structure

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

Possible exceptions

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

mergeBillingProfile

Creates new or updates an existing BillingProfile.

Request message description

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

Request message structure

mergeBillingProfile {
	"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 message description

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

Response message structure

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

Possible exceptions

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

mergeHostingLicense

Creates new or updates an existing BillableHostingLicense.

Request message description

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

Request message structure

mergeHostingLicense {
	"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 message description

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

Response message structure

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

Possible exceptions

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

mergeHostingRule

Creates new or updates an existing BillableHostingRule.

Request message description

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

Request message structure

mergeHostingRule {
	"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 message description

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

Response message structure

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

Possible exceptions

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

removeBillingProfile

Deletes an existing BillingProfile.

Request message description

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

Request message structure

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

Response message description

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

Response message structure

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

Possible exceptions

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

removeBillingReport

Deletes an existing BillingReport.

Request message description

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

Request message structure

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

Response message description

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

Response message structure

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

Possible exceptions

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

removeHostingLicense

Deletes an existing BillableHostingLicense.

Request message description

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

Request message structure

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

Response message description

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

Response message structure

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

Possible exceptions

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

removeHostingRule

Deletes an existing BillableHostingRule.

Request message description

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

Request message structure

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

Response message description

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

Response message structure

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

Possible exceptions

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

restoreBillingProfile

Restores the specified BillingProfile to its previous version.

Request message description

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

Request message structure

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

Response message description

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

Response message structure

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

Possible exceptions

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

restoreBillingReport

Restores the specified BillingReport to its previous version.

Request message description

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

Request message structure

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

Response message description

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

Response message structure

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

Possible exceptions

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

restoreHostingLicense

Restores the specified BillableHostingLicense to its previous version.

Request message description

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

Request message structure

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

Response message description

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

Response message structure

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

Possible exceptions

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

restoreHostingRule

Restores the specified BillableHostingRule to its previous version.

Request message description

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

Request message structure

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

Response message description

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

Response message structure

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

Possible exceptions

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

Companies

getCompaniesList

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.

Request message description

Property	Type	Required	Default	Description
includeArchive	boolean	optional		Takes the value of includeDeleted when not specified. When true, the command will also return archived objects.
includeDeleted	boolean	optional	`false`	When true, the command will also return deleted objects.
limit	uint16?	optional		Maximum number of objects in this response.
reqId	int32?	optional		Identifier used by external system to correlate requests to responses.

Request message structure

getCompaniesList {
	"includeArchive": boolean,
	"includeDeleted": boolean,
	"limit": number,
	"reqId": number
}

Response message description

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

Response message structure

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

Possible exceptions

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

getCompany

Gets details of the specified Company.

Request message description

Property	Type	Required	Default	Description
company	ParamId	always		An object to contain the "id" key.
company.id	uint64	always		Identifier given as input for the command.
includeDeleted	boolean	optional	`false`	When true, the command will also return a deleted Company.
reqId	int32?	optional		Identifier used by external system to correlate requests to responses.

Request message structure

getCompany {
	"company": {
		"id": number
	},
	"includeDeleted": boolean,
	"reqId": number
}

Response message description

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

Response message structure

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

Possible exceptions

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

mergeCompany

Creates a new or updates an existing Company.

Request message description

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

Request message structure

mergeCompany {
	"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 message description

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

Response message structure

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

Possible exceptions

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

removeCompany

Deletes an existing Company.

Request message description

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

Request message structure

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

Response message description

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

Response message structure

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

Possible exceptions

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

restoreCompany

Restores the specified Company.

Request message description

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

Request message structure

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

Response message description

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

Response message structure

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

Possible exceptions

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

Dispatch

getDispatchTask

Gets details of the specified DispatchTask.

Request message description

Property	Type	Required	Default	Description
dispatchTask	ParamId	always		Identifier object to contain the DispatchTask's identifier.
dispatchTask.id	uint64	always		Identifier given as input for the command.
includeDeleted	boolean	optional	`false`	When true, the command will also return a deleted DispatchTask.
reqId	int32?	optional		Identifier used by external system to correlate requests to responses.

Request message structure

getDispatchTask {
	"dispatchTask": {
		"id": number
	},
	"includeDeleted": boolean,
	"reqId": number
}

Response message description

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

Response message structure

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

Possible exceptions

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

getDispatchTasksList

Gets the list of DispatchTasks for the specified Asset.

Request message description

Property	Type	Required	Default	Description
after	datetime	optional
asset	ParamId	always		An object to contain the "id" of the Asset.
asset.id	uint64	always		Identifier given as input for the command.
before	datetime	optional
includeArchive	boolean	optional		Takes the value of includeDeleted when not specified. When true, the command will also return archived objects.
includeDeleted	boolean	optional	`false`	When true, the command will also return deleted objects.
limit	uint16?	optional		Maximum number of objects in this response.
reqId	int32?	optional		Identifier used by external system to correlate requests to responses.

Request message structure

getDispatchTasksList {
	"after": string,
	"asset": {
		"id": number
	},
	"before": string,
	"includeArchive": boolean,
	"includeDeleted": boolean,
	"limit": number,
	"reqId": number
}

Response message description

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

Response message structure

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

Possible exceptions

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

getDispatchTasksListByCompany

Gets the list of DispatchTasks for the specified Company.

Request message description

Property	Type	Required	Default	Description
after	datetime	optional
before	datetime	optional
company	ParamId	always		An object to contain the "id" of the Company.
company.id	uint64	always		Identifier given as input for the command.
includeArchive	boolean	optional		Takes the value of includeDeleted when not specified. When true, the command will also return archived objects.
includeDeleted	boolean	optional	`false`	When true, the command will also return deleted objects.
limit	uint16?	optional		Maximum number of objects in this response.
reqId	int32?	optional		Identifier used by external system to correlate requests to responses.

Request message structure

getDispatchTasksListByCompany {
	"after": string,
	"before": string,
	"company": {
		"id": number
	},
	"includeArchive": boolean,
	"includeDeleted": boolean,
	"limit": number,
	"reqId": number
}

Response message description

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

Response message structure

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

Possible exceptions

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

getDispatchTasksListByReference

Gets the list of DispatchTask for the specified Asset that match the given reference.

Request message description

Property	Type	Required	Default	Description
after	datetime	optional
asset	ParamId	always		An object to contain the "id" of the Asset.
asset.id	uint64	always		Identifier given as input for the command.
before	datetime	optional
includeArchive	boolean	optional		Takes the value of includeDeleted when not specified. When true, the command will also return archived objects.
includeDeleted	boolean	optional	`false`	When true, the command will also return deleted objects.
limit	uint16?	optional		Maximum number of objects in this response.
reference	string	optional		The "Reference" field value to match.
reqId	int32?	optional		Identifier used by external system to correlate requests to responses.

Request message structure

getDispatchTasksListByReference {
	"after": string,
	"asset": {
		"id": number
	},
	"before": string,
	"includeArchive": boolean,
	"includeDeleted": boolean,
	"limit": number,
	"reference": string,
	"reqId": number
}

Response message description

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

Response message structure

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

Possible exceptions

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

getDispatchTasksListByReferences

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.

Request message description

Property	Type	Required	Default	Description
after	datetime	optional
asset	ParamId	always		An object to contain the "id" of the Asset.
asset.id	uint64	always		Identifier given as input for the command.
before	datetime	optional
includeArchive	boolean	optional		Takes the value of includeDeleted when not specified. When true, the command will also return archived objects.
includeDeleted	boolean	optional	`false`	When true, the command will also return deleted objects.
limit	uint16?	optional		Maximum number of objects in this response.
references	Object.<string, string> see: DispatchTask.references	optional		Case-insensitive reference pairs used to match tasks.
reqId	int32?	optional		Identifier used by external system to correlate requests to responses.

Request message structure

getDispatchTasksListByReferences {
	"after": string,
	"asset": {
		"id": number
	},
	"before": string,
	"includeArchive": boolean,
	"includeDeleted": boolean,
	"limit": number,
	"references": {
		string: string
	},
	"reqId": number
}

Response message description

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

Response message structure

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

Possible exceptions

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

mergeDispatchTask

Creates a new or updates an existing DispatchTask.

Request message description

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

Request message structure

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

Response message description

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

Response message structure

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

Possible exceptions

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

multiMergeDispatchTask

Creates multiple new, or updates multiple existing DispatchTasks.

Request message description

Property	Type	Required	Description
dispatchTasks	Array.<ParameterContent>	optional	Array of parameters successfully parsed by the sub-command.
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

Request message structure

multiMergeDispatchTask {
	"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 message description

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

Response message structure

multiMergeDispatchTaskResponse {
	"dispatchTasks": [
		{
			"asset": number,
			"company": number,
			"id": number
		}
	],
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

Error Code	Description
3	The request does not contain an operation collection, or it is invalid.
3	The operation collection is empty.
7	You cannot execute this command because your session has expired.
8	You cannot execute this command because you are not logged in.
16	You cannot execute this command because your password has expired.
105	Too many items exist in the operation collection.
110	One or more of the sub-operations failed, see errorDetails for more information. Returns an ErrorDetailBatch as the `errorDetails`.

multiRemoveDispatchTask

Deletes multiple DispatchTasks.

Request message description

Property	Type	Required	Description
dispatchTasks	Array.<ParamId>	optional	Array of parameters successfully parsed by the sub-command.
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

Request message structure

multiRemoveDispatchTask {
	"dispatchTasks": [
		{
			"id": number
		}
	],
	"reqId": number
}

Response message description

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

Response message structure

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

Possible exceptions

Error Code	Description
3	The request does not contain an operation collection, or it is invalid.
3	The operation collection is empty.
7	You cannot execute this command because your session has expired.
8	You cannot execute this command because you are not logged in.
16	You cannot execute this command because your password has expired.
105	Too many items exist in the operation collection.
110	One or more of the sub-operations failed, see errorDetails for more information. Returns an ErrorDetailBatch as the `errorDetails`.

removeDispatchTask

Deletes an existing DispatchTask.

Request message description

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

Request message structure

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

Response message description

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

Response message structure

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

Possible exceptions

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

restoreDispatchTask

Restores a deleted DispatchTask.

Request message description

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

Request message structure

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

Response message description

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

Response message structure

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

Possible exceptions

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

File Hosting

getDocument

Gets details of the specified Document.

Request message description

Property	Type	Required	Default	Description
document	ParamId	always		An object to contain the identifier of the Document.
document.id	uint64	always		Identifier given as input for the command.
includeDeleted	boolean	optional	`false`	When true, the command will also return a deleted Document.
reqId	int32?	optional		Identifier used by external system to correlate requests to responses.

Request message structure

getDocument {
	"document": {
		"id": number
	},
	"includeDeleted": boolean,
	"reqId": number
}

Response message description

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

Response message structure

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

Possible exceptions

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

getDocumentsList

Gets the list of Documents for the specified Company.

Request message description

Property	Type	Required	Default	Description
company	ParamId	always		An object to contain the "id" of the Company.
company.id	uint64	always		Identifier given as input for the command.
highest	uint64?	optional
includeArchive	boolean	optional		Takes the value of includeDeleted when not specified. When true, the command will also return archived objects.
includeDeleted	boolean	optional	`false`	When true, the command will also return deleted objects.
limit	uint16?	optional		Maximum number of objects in this response.
lowest	uint64?	optional
reqId	int32?	optional		Identifier used by external system to correlate requests to responses.

Request message structure

getDocumentsList {
	"company": {
		"id": number
	},
	"highest": number,
	"includeArchive": boolean,
	"includeDeleted": boolean,
	"limit": number,
	"lowest": number,
	"reqId": number
}

Response message description

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

Response message structure

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

Possible exceptions

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

getIcon

Gets details of the specified Icon.

Request message description

Property	Type	Required	Default	Description
icon	ParamId	always		An object to contain the "id" of the Icon.
icon.id	uint64	always		Identifier given as input for the command.
includeDeleted	boolean	optional	`false`	When true, the command will also return a deleted Icon.
reqId	int32?	optional		Identifier used by external system to correlate requests to responses.

Request message structure

getIcon {
	"icon": {
		"id": number
	},
	"includeDeleted": boolean,
	"reqId": number
}

Response message description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
icon	Icon	The requested Icon.
icon.badge	IconLabel	Where the notification will appear for a mapped icon. Such as the number of dispatches an asset is working on, or the number of dispatches at a place.
icon.badge.align	string	Determines which corner of the label is attached to the anchor.
icon.badge.anchor	Point	The offset from the lat/long in pixels.
icon.badge.anchor.x	double	Horizontal coordinate
icon.badge.anchor.y	double	Vertical coordinate
icon.badge.colour	string	Background colour of the label.
icon.category	string maximum-length: 100	A noun to describe the type of thing represented. Like Truck, Car, Trailer, Hot-Air Balloon, etc...
icon.company	uint64 see: Company.id	The company to which this icon belongs.
icon.global	boolean	Indicates whether this icon is available to child companies.
icon.glyphs	Array.<IconGlyph>	The images used to show the detail of this icon.
icon.id	uint64	Unique identifier of this icon.
icon.label	IconLabel	Definition for the name bubble above the icon on a map.
icon.label.align	string	Determines which corner of the label is attached to the anchor.
icon.label.anchor	Point	The offset from the lat/long in pixels.
icon.label.anchor.x	double	Horizontal coordinate
icon.label.anchor.y	double	Vertical coordinate
icon.label.colour	string	Background colour of the label.
icon.name	string maximum-length: 100	A specific adjective to describe the thing. Like Blue, Red, Empty, Full, etc...
icon.notes	string	Notes.
icon.processedUtc	datetime	When the was change procesed.
icon.updated		by: login, from: monster
icon.usage	Array.<string>	A list of things that this icon can be used to represent. Like asset, place, user, etc...
icon.v	Array.<uint32>	Object version keys used to validate synchronization for all object properties.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

getIconResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"icon": {
		"badge": {
			"align": string,
			"anchor": {
				"x": number,
				"y": number
			},
			"colour": string
		},
		"category": string,
		"company": number,
		"global": boolean,
		"glyphs": [
			{
				"anchor": {
					"x": number,
					"y": number
				},
				"layer": string,
				"rotates": boolean,
				"size": {
					"height": number,
					"width": number
				},
				"src": string,
				"tags": [
					string
				],
				"zIndex": number
			}
		],
		"id": number,
		"label": {
			"align": string,
			"anchor": {
				"x": number,
				"y": number
			},
			"colour": string
		},
		"name": string,
		"notes": string,
		"processedUtc": string,
		"updated": {
		},
		"usage": [
			string
		],
		"v": [
			number
		]
	},
	"message": string,
	"reqId": number
}

Possible exceptions

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

getIconsList

Gets the list of Icons for the specified Company.

Request message description

Property	Type	Required	Default	Description
branch	boolean	optional	`false`	When true the list of Icons from the given Company and all child-companies are returned. Otherwise, only Icons from the given Company are included.
company	ParamId	always		An object to contain the "id" of the Company.
company.id	uint64	always		Identifier given as input for the command.
highest	uint64?	optional
includeArchive	boolean	optional		Takes the value of includeDeleted when not specified. When true, the command will also return archived objects.
includeDeleted	boolean	optional	`false`	When true, the command will also return deleted objects.
limit	uint16?	optional		Maximum number of objects in this response.
lowest	uint64?	optional
reqId	int32?	optional		Identifier used by external system to correlate requests to responses.
trunk	boolean	optional	`true`	When true (default) the list of Icons will include any publicly available Icons from the given Company's parent(s).

Request message structure

getIconsList {
	"branch": boolean,
	"company": {
		"id": number
	},
	"highest": number,
	"includeArchive": boolean,
	"includeDeleted": boolean,
	"limit": number,
	"lowest": number,
	"reqId": number,
	"trunk": boolean
}

Response message description

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

Response message structure

getIconsListResponse {
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"icons": [
		{
			"badge": {
				"align": string,
				"anchor": {
					"x": number,
					"y": number
				},
				"colour": string
			},
			"category": string,
			"company": number,
			"global": boolean,
			"glyphs": [
				{
					"anchor": {
						"x": number,
						"y": number
					},
					"layer": string,
					"rotates": boolean,
					"size": {
						"height": number,
						"width": number
					},
					"src": string,
					"tags": [
						string
					],
					"zIndex": number
				}
			],
			"id": number,
			"label": {
				"align": string,
				"anchor": {
					"x": number,
					"y": number
				},
				"colour": string
			},
			"name": string,
			"notes": string,
			"processedUtc": string,
			"updated": {
			},
			"usage": [
				string
			],
			"v": [
				number
			]
		}
	],
	"message": string,
	"reqId": number
}

Possible exceptions

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

getPicture

Gets details of the specified Picture.

Request message description

Property	Type	Required	Default	Description
includeDeleted	boolean	optional	`false`	When true, the command will also return a deleted Picture.
picture	ParamId	always		An object to contain the "id" of the Picture.
picture.id	uint64	always		Identifier given as input for the command.
reqId	int32?	optional		Identifier used by external system to correlate requests to responses.

Request message structure

getPicture {
	"includeDeleted": boolean,
	"picture": {
		"id": number
	},
	"reqId": number
}

Response message description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
picture	Picture	The requested Picture.
picture.bytes	uint64	The file-size on the disk.
picture.company	uint64 see: Company.id	The company to which this image belongs.
picture.focals	Array.<Square>	A list of focal points in the images like faces.
picture.id	uint64	Unique identifier of this image.
picture.name	string maximum-length: 100	The file name of this image.
picture.notes	string	Notes about this image.
picture.processedUtc	datetime	When the was change procesed.
picture.size	Size	Resolution defined in pixels.
picture.size.height	double	Height
picture.size.width	double	Width
picture.src	string maximum-length: 200	The URL/path to find this image.
picture.updated		by: login, from: monster
picture.uses	uint32	A count of the times this image was used for something (asset, contact, task, etc).
picture.v	Array.<uint32>	Object version keys used to validate synchronization for all object properties.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

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

Possible exceptions

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

getPicturesList

Gets the list of Pictures for the specified Company.

Request message description

Property	Type	Required	Default	Description
branch	boolean	optional	`false`	When true the list of Pictures from the given Company and all child-companies are returned. Otherwise, only Pictures from the given Company are included.
company	ParamId	always		An object to contain the "id" of the Company.
company.id	uint64	always		Identifier given as input for the command.
highest	uint64?	optional
includeArchive	boolean	optional		Takes the value of includeDeleted when not specified. When true, the command will also return archived objects.
includeDeleted	boolean	optional	`false`	When true, the command will also return deleted objects.
limit	uint16?	optional		Maximum number of objects in this response.
lowest	uint64?	optional
reqId	int32?	optional		Identifier used by external system to correlate requests to responses.

Request message structure

getPicturesList {
	"branch": boolean,
	"company": {
		"id": number
	},
	"highest": number,
	"includeArchive": boolean,
	"includeDeleted": boolean,
	"limit": number,
	"lowest": number,
	"reqId": number
}

Response message description

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

Response message structure

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

Possible exceptions

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

mergeDocument

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

Request message description

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

Request message structure

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

Response message description

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

Response message structure

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

Possible exceptions

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

mergeIcon

Creates a new or updates an existing Icon.

Request message description

Property	Type	Required	Description
icon	Object.<string, ?>	always	A simple object to contain the Icon parameters.
icon.badge	IconLabel	optional	Definition for the name badge beside the Icon on a map.
icon.badge.align	string	optional	Determines which corner of the label is attached to the anchor.
icon.badge.anchor	Point	optional	The offset from the lat/long in pixels.
icon.badge.anchor.x	double	optional	Horizontal coordinate
icon.badge.anchor.y	double	optional	Vertical coordinate
icon.badge.colour	string	optional	Background colour of the label.
icon.category	string maximum-length: 100	optional	A noun to describe the type of thing represented. Like Truck, Car, Trailer, Hot-Air Balloon, etc...
icon.company	uint64?	create	The Company to which these Icons belongs.
icon.global	boolean	optional	Indicates whether this Icon is available to child companies.
icon.glyphs	Array.<IconGlyph>	optional	The images used to show the detail of this Icon.
icon.id	uint64?	update	The unique identifier of the Icon you want to update.
icon.label	IconLabel	optional	Definition for the name bubble above the Icon on a map.
icon.label.align	string	optional	Determines which corner of the label is attached to the anchor.
icon.label.anchor	Point	optional	The offset from the lat/long in pixels.
icon.label.anchor.x	double	optional	Horizontal coordinate
icon.label.anchor.y	double	optional	Vertical coordinate
icon.label.colour	string	optional	Background colour of the label.
icon.name	string maximum-length: 100	create	A specific adjective to describe the thing. Like Blue, Red, Empty, Full, etc...
icon.notes	string	optional	Notes.
icon.usage	Array.<string>	optional	A list of things that this Icon can be used to represent. Like `asset`, `place`, `user`, etc...
icon.v	Array.<int32>	optional
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

Request message structure

mergeIcon {
	"icon": {
		"badge": {
			"align": string,
			"anchor": {
				"x": number,
				"y": number
			},
			"colour": string
		},
		"category": string,
		"company": number,
		"global": boolean,
		"glyphs": [
			{
				"anchor": {
					"x": number,
					"y": number
				},
				"layer": string,
				"rotates": boolean,
				"size": {
					"height": number,
					"width": number
				},
				"src": string,
				"tags": [
					string
				],
				"zIndex": number
			}
		],
		"id": number,
		"label": {
			"align": string,
			"anchor": {
				"x": number,
				"y": number
			},
			"colour": string
		},
		"name": string,
		"notes": string,
		"usage": [
			string
		],
		"v": [
			number
		]
	},
	"reqId": number
}

Response message description

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

Response message structure

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

Possible exceptions

Error Code	Description
2	A communication error occurred. If you receive this error, please contact technical support.
3	The request does not contain a icon object, or it is invalid.
3	Not enough keys exist in the icon object.
3	The icon.usage was invalid.
3	During create: When creating a new Icon, a company was not given.
3	During create: When creating a new Icon, a name was not given, or it is invalid.
3	During update: When updating a Icon, the id was invalid.
3	During update: When updating a Icon, the name was given as blank.
3	During update: When updating a Icon, the v was not an array, or contained too few numbers.
3	One of the icon.glyphs values is invalid. Returns an ErrorDetailInput as the `errorDetails`.
5	You do not have permission to create a new Icon.
5	You do not have permission to update this Icon.
6	During update: When updating a Icon, an incorrect v value was given as input.
7	You cannot execute this command because your session has expired.
8	You cannot execute this command because you are not logged in.
16	You cannot execute this command because your password has expired.
33	During update: The Icon was not found by its unique identifier.
130	During update: When updating a Icon, the company can not be changed.

mergePicture

Creates a new or updates an existing Picture.

Request message description

Property	Type	Required	Description
picture	Object.<string, ?>	always	A simple object to contain the Picture parameters.
picture.company	uint64?	create	The Company to which this Picture belongs. After creation, this value is read-only.
picture.focals	Array.<Square>	optional	A list of focal points in the Picture like faces.
picture.id	uint64?	update	The unique identifier of the Picture you want to update.
picture.name	string maximum-length: 100	create	The file name of this Picture.
picture.notes	string	optional	Notes about this Picture.
picture.v	Array.<int32>	optional
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

Request message structure

mergePicture {
	"picture": {
		"company": number,
		"focals": [
			{
				"bottom": number,
				"left": number,
				"right": number,
				"top": number
			}
		],
		"id": number,
		"name": string,
		"notes": string,
		"v": [
			number
		]
	},
	"reqId": number
}

Response message description

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

Response message structure

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

Possible exceptions

Error Code	Description
2	A communication error occurred. If you receive this error, please contact technical support.
2	During create: When creating a new Picture, the file size could not be determined. If you receive this error, please contact technical support.
2	During create: When creating a new Picture, the upload was not successful. If you receive this error, please contact technical support.
3	The request does not contain a picture object, or it is invalid.
3	Not enough keys exist in the picture object.
3	During create: When creating a new Picture, a company was not given.
3	During create: When creating a new Picture, a name was not given, or it is invalid.
3	During update: When updating a Picture, the id was invalid.
3	During update: When updating a Picture, the name was given as blank.
3	During update: When updating a Picture, the v was not an array, or contained too few numbers.
3	One of the picture.focals values is invalid. Returns an ErrorDetailInput as the `errorDetails`.
5	You do not have permission to create a new Picture.
5	You do not have permission to update this Picture.
6	During update: When updating a Picture, an incorrect v value was given as input.
7	You cannot execute this command because your session has expired.
8	You cannot execute this command because you are not logged in.
16	You cannot execute this command because your password has expired.
68	During update: The Picture was not found by its unique identifier.
90	During create: When creating a new Picture, the given mime type is not supported.
91	During create: When creating a new Picture, the file size was too large. Returns an ErrorDetailMinMax as the `errorDetails`.
130	During update: When updating a Picture, the company can not be changed.

removeDocument

Deletes an existing Document.

Request message description

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

Request message structure

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

Response message description

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

Response message structure

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

Possible exceptions

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

removeIcon

Deletes an existing Icon.

Request message description

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

Request message structure

removeIcon {
	"icon": {
		"id": number
	},
	"reqId": number
}

Response message description

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

Response message structure

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

Possible exceptions

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

removePicture

Deletes an existing Picture.

Request message description

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

Request message structure

removePicture {
	"picture": {
		"id": number
	},
	"reqId": number
}

Response message description

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

Response message structure

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

Possible exceptions

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

restoreDocument

Restores a deleted Document.

Request message description

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

Request message structure

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

Response message description

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

Response message structure

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

Possible exceptions

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

restoreIcon

Restores the specified Icon.

Request message description

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

Request message structure

restoreIcon {
	"icon": {
		"id": number
	},
	"reqId": number
}

Response message description

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

Response message structure

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

Possible exceptions

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

restorePicture

Restores the specified Picture.

Request message description

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

Request message structure

restorePicture {
	"picture": {
		"id": number
	},
	"reqId": number
}

Response message description

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

Response message structure

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

Possible exceptions

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

Maintenance

getMaintenanceJob

Gets details of the specified MaintenanceJob.

Request message description

Property	Type	Required	Default	Description
includeDeleted	boolean	optional	`false`	When true, the command will also return a deleted MaintenanceJob.
maintenanceJob	ParamId	always		An object to contain the "id" of the MaintenanceJob.
maintenanceJob.id	uint64	always		Identifier given as input for the command.
reqId	int32?	optional		Identifier used by external system to correlate requests to responses.

Request message structure

getMaintenanceJob {
	"includeDeleted": boolean,
	"maintenanceJob": {
		"id": number
	},
	"reqId": number
}

Response message description

Property	Type	Description
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
maintenanceJob	MaintenanceJob	The requested MaintenanceJob.
maintenanceJob.asset	uint64 see: Asset.id	The Vehicle or Trailer to which this job belongs
maintenanceJob.company	uint64 see: Company.id	The company to which this Vehicle or Trailer belongs
maintenanceJob.completed	datetime	When was this job created.
maintenanceJob.cost	double	How much the job cost in dollars.
maintenanceJob.created	datetime	When was this job created.
maintenanceJob.duration	timespan	Time it took to complete the job.
maintenanceJob.engineHours	double?	The operating time at the time of the service.
maintenanceJob.garage	string maximum-length: 100	The name of the garage or service facility where the work is done.
maintenanceJob.id	uint64	Unique identifier
maintenanceJob.name	string maximum-length: 100	The work being done. Like "oil change".
maintenanceJob.notes	string	Notes about the job. Like "changed the oil and filter".
maintenanceJob.odometer	double?	The odometer at the time of the service.
maintenanceJob.pictures	Array.<uint64> see: Picture.id for values see: Picture.id	Images taken while performing the work for reference.
maintenanceJob.processedUtc	datetime	When the was change procesed.
maintenanceJob.reference	string maximum-length: 100	A reference code used to track this job
maintenanceJob.schedule	uint64? see: MaintenanceSchedule.id	The Maintenance Schedule from which this job was created
maintenanceJob.status	MaintenanceJobStatus	The status of this job.
maintenanceJob.technician	string maximum-length: 100	The mechanic who performed the work.
maintenanceJob.updated		by: login, from: monster
maintenanceJob.v	Array.<uint32>	Object version keys used to validate synchronization for all object properties.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

getMaintenanceJobResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"maintenanceJob": {
		"asset": number,
		"company": number,
		"completed": string,
		"cost": number,
		"created": string,
		"duration": string,
		"engineHours": number,
		"garage": string,
		"id": number,
		"name": string,
		"notes": string,
		"odometer": number,
		"pictures": [
			number
		],
		"processedUtc": string,
		"reference": string,
		"schedule": number,
		"status": string,
		"technician": string,
		"updated": {
		},
		"v": [
			number
		]
	},
	"message": string,
	"reqId": number
}

Possible exceptions

Error Code	Description
3	The request does not contain a maintenanceJob object, or it is invalid.
3	The