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 maintenanceJob object does not contain an id, or it is invalid.
5	You do not have permission to view this MaintenanceJob.
5	You do not have permission to view this MaintenanceJob's 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. If you receive this error, please contact technical support.
35	The MaintenanceJob was not found by its unique identifier.

getMaintenanceJobsList

Gets a list of MaintenanceJobs by the 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.
pending	boolean	optional		Optional parameter to including pending/past-due MaintenanceJobs.
reqId	int32?	optional		Identifier used by external system to correlate requests to responses.

Request message structure

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

Response message description

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

Response message structure

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

Possible exceptions

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.
3	The (optional) before date is invalid.
3	The (optional) after date is invalid.
5	You do not have permission to view this MaintenanceJob.
5	You do not have permission to view any Assets in the given 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.

getMaintenanceJobsListByAsset

Gets a list of MaintenanceJobs by the 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.
pending	boolean	optional		Optional parameter to including pending/past-due MaintenanceJobs.
reqId	int32?	optional		Identifier used by external system to correlate requests to responses.

Request message structure

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

Response message description

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

Response message structure

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

Possible exceptions

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.
3	The (optional) before date is invalid.
3	The (optional) after date is invalid.
5	You do not have permission to view this MaintenanceJob.
5	You do not have permission to view this Asset's MaintenanceJobs.
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.

getMaintenanceJobsListBySchedule

Gets a list of MaintenanceJobs by the schedule under which they were created/completed.

Request message description

Property	Type	Required	Default	Description
after	datetime	optional
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.
maintenanceSchedule	ParamId	always		An object to contain the "id" of the MaintenanceSchedule.
maintenanceSchedule.id	uint64	always		Identifier given as input for the command.
pending	boolean	optional		Optional parameter to including pending/past-due MaintenanceJobs.
reqId	int32?	optional		Identifier used by external system to correlate requests to responses.

Request message structure

getMaintenanceJobsListBySchedule {
	"after": string,
	"before": string,
	"includeArchive": boolean,
	"includeDeleted": boolean,
	"limit": number,
	"maintenanceSchedule": {
		"id": number
	},
	"pending": 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.
maintenanceJobs	Array.<MaintenanceJob>	The list of requested MaintenanceJobs.
maintenanceSchedule	RespIdCompany	An object to contain the "id" of the MaintenanceSchedule to which the array of MaintenanceJobs belong.
maintenanceSchedule.company	uint64	Identifier of the Company to which this object belongs.
maintenanceSchedule.id	uint64?	Identifier given as input for the command.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

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

Possible exceptions

Error Code	Description
2	A communication error occurred. If you receive this error, please contact technical support.
3	The request does not contain a maintenanceSchedule object, or it is invalid.
3	The maintenanceSchedule object does not contain an id, or it is invalid.
3	The (optional) before date is invalid.
3	The (optional) after date is invalid.
5	You do not have permission to view this MaintenanceJob.
5	You do not have permission to view any Assets in the given 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.
37	The MaintenanceSchedule was not found by its unique identifier.

getMaintenanceSchedule

Gets details of the specified MaintenanceSchedule.

Request message description

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

Request message structure

getMaintenanceSchedule {
	"includeDeleted": boolean,
	"maintenanceSchedule": {
		"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.
maintenanceSchedule	MaintenanceSchedule	The requested MaintenanceSchedule.
maintenanceSchedule.company	uint64 see: Company.id	The company to which this schedule belongs
maintenanceSchedule.cost	double	The estimated cost for the job cost in dollars.
maintenanceSchedule.duration	timespan	The estimated time for the job.
maintenanceSchedule.fill	colour maximum-length: 22	The fill/background colour of the icon.
maintenanceSchedule.garage	string maximum-length: 100	The name of the garage or service facility where the work is done.
maintenanceSchedule.graphic	codified maximum-length: 22	The name of the symbol for this schedule.
maintenanceSchedule.id	uint64	Unique identifier
maintenanceSchedule.intervals	Object.<uint64, MaintenanceInterval> for keys see: Asset.id	The per-asset details calculated by the system to help predict the creation of Maintenance Jobs.
maintenanceSchedule.name	string maximum-length: 100	The name of the work to be done. Like "oil change".
maintenanceSchedule.notes	string	Notes about the work to be done. Like "change the oil and oil filter".
maintenanceSchedule.notify	Array.<email> for values see: User.login	List of Users to send notifications.
maintenanceSchedule.predictionDays	uint32	The number of days in advance to predict a job will become pending.
maintenanceSchedule.processedUtc	datetime	When the was change procesed.
maintenanceSchedule.recurDays	uint32?	The number of days between service visits.
maintenanceSchedule.recurDistance	double?	The amount of mileage between service visits.
maintenanceSchedule.recurEngineHours	double?	The number of operating hours between service visits.
maintenanceSchedule.reference	string maximum-length: 100	A reference code used to track this job
maintenanceSchedule.stroke	colour maximum-length: 22	Outline and graphic colour.
maintenanceSchedule.targets	expression	The targeting expression to select which Vehicles and Trailers require this maintenance work.
maintenanceSchedule.updated		by: login, from: monster
maintenanceSchedule.v	Array.<uint32>	Object version keys used to validate synchronization for all object properties.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

getMaintenanceScheduleResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"maintenanceSchedule": {
		"company": number,
		"cost": number,
		"duration": string,
		"fill": string,
		"garage": string,
		"graphic": string,
		"id": number,
		"intervals": {
			string: {
				"asset": number,
				"date": string,
				"engineHours": number,
				"lastJob": number,
				"odometer": number
			}
		},
		"name": string,
		"notes": string,
		"notify": [
			string
		],
		"predictionDays": number,
		"processedUtc": string,
		"recurDays": number,
		"recurDistance": number,
		"recurEngineHours": number,
		"reference": string,
		"stroke": string,
		"targets": string,
		"updated": {
		},
		"v": [
			number
		]
	},
	"message": string,
	"reqId": number
}

Possible exceptions

Error Code	Description
3	The request does not contain a maintenanceSchedule object, or it is invalid.
3	The maintenanceSchedule object does not contain an id, or it is invalid.
5	You do not have permission to view this MaintenanceSchedule.
5	You do not have permission to view any assets in the given 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.
37	The MaintenanceSchedule was not found by its unique identifier.

getMaintenanceSchedulesList

Gets the list of MaintenanceSchedules 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

getMaintenanceSchedulesList {
	"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 MaintenanceSchedules belong.
company.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
maintenanceSchedules	Array.<MaintenanceSchedule>	The list of requested MaintenanceSchedules.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

getMaintenanceSchedulesListResponse {
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"maintenanceSchedules": [
		{
			"company": number,
			"cost": number,
			"duration": string,
			"fill": string,
			"garage": string,
			"graphic": string,
			"id": number,
			"intervals": {
				string: {
					"asset": number,
					"date": string,
					"engineHours": number,
					"lastJob": number,
					"odometer": number
				}
			},
			"name": string,
			"notes": string,
			"notify": [
				string
			],
			"predictionDays": number,
			"processedUtc": string,
			"recurDays": number,
			"recurDistance": number,
			"recurEngineHours": number,
			"reference": string,
			"stroke": string,
			"targets": string,
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"message": string,
	"reqId": number
}

Possible exceptions

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 MaintenanceSchedule.
5	You do not have permission to view any assets in the given 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.

mergeMaintenanceJob

Creates a new or updates an existing MaintenanceJob.

Request message description

Property	Type	Required	Description
maintenanceJob	Object.<string, ?>	always	A simple object to contain the MaintenanceJob parameters.
maintenanceJob.asset	uint64?	create	The identifier of the Asset to which this MaintenanceJob is assigned.
maintenanceJob.completed	datetime	optional	When was this MaintenanceJob created.
maintenanceJob.cost	double?	optional	How much the MaintenanceJob cost in dollars.
maintenanceJob.created	datetime	optional	When was this MaintenanceJob created.
maintenanceJob.duration	timespan	optional	Time it took to complete the MaintenanceJob.
maintenanceJob.engineHours	double?	optional	The operating time at the time of the service.
maintenanceJob.garage	string maximum-length: 100	optional	The name of the garage or service facility where the work is done.
maintenanceJob.id	uint64?	update	The unique identifier of the MaintenanceJob you want to update.
maintenanceJob.name	string maximum-length: 100	create	The work being done. Like "oil change".
maintenanceJob.notes	string	optional	Notes about the MaintenanceJob. Like "changed the oil and filter".
maintenanceJob.odometer	double?	optional	The odometer at the time of the service.
maintenanceJob.pictures	Array.<uint64> for values see: Picture.id	optional	Pictures taken while performing the work for reference.
maintenanceJob.reference	string maximum-length: 100	optional	A reference code used to track this MaintenanceJob.
maintenanceJob.schedule	uint64? see: MaintenanceSchedule.id	optional	The MaintenanceSchedule from which this job was created
maintenanceJob.status	MaintenanceJobStatus?	optional	The status of this MaintenanceJob.
maintenanceJob.technician	string maximum-length: 100	optional	The mechanic who performed the work.
maintenanceJob.v	Array.<int32>	optional
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

Request message structure

mergeMaintenanceJob {
	"maintenanceJob": {
		"asset": number,
		"completed": string,
		"cost": number,
		"created": string,
		"duration": string,
		"engineHours": number,
		"garage": string,
		"id": number,
		"name": string,
		"notes": string,
		"odometer": number,
		"pictures": [
			number
		],
		"reference": string,
		"schedule": number,
		"status": string,
		"technician": string,
		"v": [
			number
		]
	},
	"reqId": number
}

Response 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	RespIdAsset	An object which contains the "id", "asset", and "company" keys.
maintenanceJob.asset	uint64	Identifier of the Asset to which this object belongs
maintenanceJob.company	uint64	Identifier of the Company to which this object belongs.
maintenanceJob.id	uint64?	Identifier given as input for the command.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

mergeMaintenanceJobResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"maintenanceJob": {
		"asset": number,
		"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 maintenanceJob object, or it is invalid.
3	Not enough keys exist in the maintenanceJob object.
3	The given maintenanceJob.completed is too far into the future.
3	maintenanceJob.asset can not be changed
3	The given maintenanceJob.asset was invalid.
3	The given maintenanceJob.schedule was invalid.
3	The given maintenanceJob.status was invalid.
3	The given maintenanceJob.created date was invalid.
3	The given maintenanceJob.completed date was invalid.
3	The given maintenanceJob.odometer was invalid.
3	The given maintenanceJob.engineHours was invalid.
3	The given maintenanceJob.duration was invalid, or it was not positive.
3	The given maintenanceJob.cost was invalid.
3	The given maintenanceJob.pictures was invalid.
3	During create: When creating a new MaintenanceJob, a maintenanceJob.name was not given, or it is invalid.
3	During update: When updating a MaintenanceJob, the maintenanceJob.id was invalid.
3	During update: When updating a MaintenanceJob, the maintenanceJob.name was given as blank.
3	During update: When updating a MaintenanceJob, the v was not an array, or contained too few numbers.
3	One of the maintenanceJob.pictures values is invalid. Returns an ErrorDetailInput as the `errorDetails`.
5	You do not have permission to create a new MaintenanceJob.
5	You do not have permission to update this MaintenanceJob.
5	You do not have permission to view the target Asset.
6	During update: When updating a MaintenanceJob, 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	The Asset was not found by its unique identifier.
35	The MaintenanceJob was not found by its unique identifier.
37	The MaintenanceSchedule was not found by its unique identifier.
69	One or more Pictures were not found by their unique identifiers.
130	The maintenanceJob.schedule and maintenanceJob.asset belong to different companies.
130	During update: When updating a MaintenanceJob, the maintenanceJob.asset can not be changed.

mergeMaintenanceSchedule

Creates a new or updates an existing MaintenanceSchedule.

Request message description

Property	Type	Required	Description
maintenanceSchedule	Object.<string, ?>	always	A simple object to contain the MaintenanceSchedule parameters.
maintenanceSchedule.company	uint64?	optional	The company to which this MaintenanceSchedule. After creation, this value is read-only.
maintenanceSchedule.cost	double?	optional	The estimated cost for the created MaintenanceJob cost in dollars.
maintenanceSchedule.duration	timespan	optional	The estimated time for the created MaintenanceJob.
maintenanceSchedule.fill	string maximum-length: 22	optional	The fill/background colour of the icon. Should be a hex colour in the format #RRGGBB.
maintenanceSchedule.garage	string maximum-length: 100	optional	The name of the garage or service facility where the work is done.
maintenanceSchedule.graphic	codified maximum-length: 22	optional	The name of the symbol for this report.
maintenanceSchedule.id	uint64?	update	The unique identifier of the MaintenanceSchedule you want to update.
maintenanceSchedule.intervals	Object.<uint64, MaintenanceInterval>	optional	The per-Asset details calculated by the system to help predict the creation of MaintenanceJobs.
maintenanceSchedule.name	string maximum-length: 100	create	The name of the MaintenanceSchedule.
maintenanceSchedule.notes	string	optional	Notes about the MaintenanceSchedule.
maintenanceSchedule.notify	Array.<email>	optional	List of Users to send notifications.
maintenanceSchedule.predictionDays	uint32?	optional	The number of days in advance to predict a MaintenanceJob will become pending.
maintenanceSchedule.recurDays	uint32?	optional	The number of days between service visits.
maintenanceSchedule.recurDistance	double?	optional	The amount of mileage between service visits.
maintenanceSchedule.recurEngineHours	double?	optional	The number of operating hours between service visits.
maintenanceSchedule.reference	string maximum-length: 100	optional	A reference code used to track this created MaintenanceJob.
maintenanceSchedule.stroke	string maximum-length: 22	optional	Outline and graphic colour. Should be a hex colour in the format #RRGGBB.
maintenanceSchedule.targets	expression	optional	Which Assets are targetted by this MaintenanceSchedule.
maintenanceSchedule.v	Array.<int32>	optional
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

Request message structure

mergeMaintenanceSchedule {
	"maintenanceSchedule": {
		"company": number,
		"cost": number,
		"duration": string,
		"fill": string,
		"garage": string,
		"graphic": string,
		"id": number,
		"intervals": {
			string: {
				"asset": number,
				"date": string,
				"engineHours": number,
				"lastJob": number,
				"odometer": number
			}
		},
		"name": string,
		"notes": string,
		"notify": [
			string
		],
		"predictionDays": number,
		"recurDays": number,
		"recurDistance": number,
		"recurEngineHours": number,
		"reference": string,
		"stroke": string,
		"targets": string,
		"v": [
			number
		]
	},
	"reqId": number
}

Response 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.
maintenanceSchedule	RespIdCompany	An object which contains the "id" and "company" keys.
maintenanceSchedule.company	uint64	Identifier of the Company to which this object belongs.
maintenanceSchedule.id	uint64?	Identifier given as input for the command.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

mergeMaintenanceScheduleResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"maintenanceSchedule": {
		"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 maintenanceSchedule object, or it is invalid.
3	Not enough keys exist in the maintenanceSchedule object.
3	The maintenanceSchedule.name was not given, or it is invalid.
3	The maintenanceSchedule.notify was invalid.
3	The maintenanceSchedule.predictionDays was invalid, or the value was not between 5 and 180.
3	The maintenanceSchedule.recurDays was invalid.
3	The maintenanceSchedule.recurDistance was invalid.
3	The maintenanceSchedule.recurEngineHours was invalid.
3	The maintenanceSchedule.intervals was invalid.
3	The maintenanceSchedule.duration was invalid, or it was not positive.
3	The maintenanceSchedule.cost was invalid.
3	The maintenanceSchedule.notify was invalid.
3	One of the maintenanceSchedule.notify values was invalid.
3	The maintenanceSchedule.intervals was invalid.
3	One of the maintenanceSchedule.intervals values was invalid.
3	During create: The maintenanceSchedule.company was invalid.
3	During create: When creating a MaintenanceSchedule, the maintenanceSchedule.targets was invalid.
3	During update: When updating a MaintenanceSchedule, the maintenanceSchedule.id was invalid.
3	During update: When updating a MaintenanceSchedule, the maintenanceSchedule.name was given as blank.
3	During update: When updating a MaintenanceSchedule, the v was not an array, or contained too few numbers.
5	You do not have permission to create a new MaintenanceSchedule.
5	You do not have permission to update this MaintenanceSchedule.
5	You do not have permission to view one of the Assets in a given maintenanceSchedule.intervals.
6	During update: When updating a MaintenanceSchedule, 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	The Asset was not found by its unique identifier.
37	The MaintenanceSchedule was not found by its unique identifier.
130	During update: When updating a MaintenanceSchedule, the maintenanceSchedule.companycompany was provided as a different value.

removeMaintenanceJob

Deletes an existing MaintenanceJob.

Request message description

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

Request message structure

removeMaintenanceJob {
	"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	RespAssetDeleted	An object which contains the MaintenanceJob's id, owning Company id, related Asset id, and deleted status.
maintenanceJob.asset	uint64	Identifier of the Asset to which this object belongs.
maintenanceJob.company	uint64	Identifier of the Company to which this object belongs.
maintenanceJob.deleted	boolean	Flag showing if the object is deleted.
maintenanceJob.id	uint64?	Identifier given as input for the command.
maintenanceJob.v	Array.<uint32>
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

removeMaintenanceJobResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"maintenanceJob": {
		"asset": number,
		"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 maintenanceJob object, or it is invalid.
3	The maintenanceJob object does not contain an id, or it is invalid.
5	You do not have permission to delete this MaintenanceJob.
5	You do not have permission to view this MaintenanceJob's 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. If you receive this error, please contact technical support.
35	The MaintenanceJob was not found by its unique identifier.

removeMaintenanceSchedule

Deletes an existing MaintenanceSchedule.

Request message description

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

Request message structure

removeMaintenanceSchedule {
	"maintenanceSchedule": {
		"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.
maintenanceSchedule	RespDeleted	An object which contains the MaintenanceSchedule's unique identifier and deleted status.
maintenanceSchedule.company	uint64	Identifier of the Company to which this object belongs.
maintenanceSchedule.deleted	boolean	Flag showing if the object is deleted.
maintenanceSchedule.id	uint64?	Identifier given as input for the command.
maintenanceSchedule.v	Array.<uint32>
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

removeMaintenanceScheduleResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"maintenanceSchedule": {
		"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 maintenanceSchedule object, or it is invalid.
3	The maintenanceSchedule object does not contain an id, or it is invalid.
5	You do not have permission to delete this MaintenanceSchedule.
5	You do not have permission to view any Assets targeted by this MaintenanceSchedule.
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.
37	The MaintenanceSchedule was not found by its unique identifier.

restoreMaintenanceJob

Restores the specified MaintenanceJob.

Request message description

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

Request message structure

restoreMaintenanceJob {
	"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	RespAssetDeleted	An object which contains the MaintenanceJob's id, owning Company id, related Asset id, and deleted status.
maintenanceJob.asset	uint64	Identifier of the Asset to which this object belongs.
maintenanceJob.company	uint64	Identifier of the Company to which this object belongs.
maintenanceJob.deleted	boolean	Flag showing if the object is deleted.
maintenanceJob.id	uint64?	Identifier given as input for the command.
maintenanceJob.v	Array.<uint32>
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

restoreMaintenanceJobResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"maintenanceJob": {
		"asset": number,
		"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 maintenanceJob object, or it is invalid.
3	The maintenanceJob object does not contain an id, or it is invalid.
5	You do not have permission to restore this MaintenanceJob.
5	You do not have permission to view this MaintenanceJob's 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. If you receive this error, please contact technical support.
35	The MaintenanceJob was not found by its unique identifier.
36	The MaintenanceJob was found, but is not marked as deleted.

restoreMaintenanceSchedule

Restores the specified MaintenanceSchedule.

Request message description

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

Request message structure

restoreMaintenanceSchedule {
	"maintenanceSchedule": {
		"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.
maintenanceSchedule	RespDeleted	An object which contains the MaintenanceSchedule's unique identifier and deleted status.
maintenanceSchedule.company	uint64	Identifier of the Company to which this object belongs.
maintenanceSchedule.deleted	boolean	Flag showing if the object is deleted.
maintenanceSchedule.id	uint64?	Identifier given as input for the command.
maintenanceSchedule.v	Array.<uint32>
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

restoreMaintenanceScheduleResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"maintenanceSchedule": {
		"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 maintenanceSchedule object, or it is invalid.
3	The maintenanceSchedule object does not contain an id, or it is invalid.
5	You do not have permission to restore this MaintenanceSchedule.
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.
37	The MaintenanceSchedule was not found by its unique identifier.
38	The MaintenanceSchedule was found, but is not marked as deleted.

Messaging

getAssetMessage

Gets details of the specified AssetMessage.

Request message description

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

Request message structure

getAssetMessage {
	"assetMessage": {
		"id": number
	},
	"includeDeleted": boolean,
	"reqId": number
}

Response message description

Property	Type	Description
assetMessage	AssetMessage	The requested AssetMessage.
assetMessage.asset	uint64 see: Asset.id	The asset to which this message relates.
assetMessage.body	string	The main contents of the memo.
assetMessage.company	uint64 see: Company.id	The company to which this memo belongs.
assetMessage.delivered	datetime	Date/time stamp of when the memo was delivered (or sent if delivery information unavailable).
assetMessage.folder	MessageFolder	The folder under which this message is stored.
assetMessage.from	string maximum-length: 254 minimum-length: 6	Sender address
assetMessage.id	uint64	Unique identifier of this memo.
assetMessage.incoming	boolean	Indicates that this is a received message instead of a sent message.
assetMessage.kind	MessageType	Protocol type
assetMessage.processed	datetime	Date/time stamp of when the memo was processed.
assetMessage.processedUtc	datetime	When the was change procesed.
assetMessage.readBy	email see: User.login maximum-length: 254	The user that read this message. This field is blank/null when unread.
assetMessage.status	MessageStatus	Lifetime status
assetMessage.subject	string maximum-length: 100	The subject of this message.
assetMessage.to	string maximum-length: 254 minimum-length: 6	Recipient address
assetMessage.updated		by: login, from: monster
assetMessage.user	email see: User.login maximum-length: 254	The user who sent/received this message.
assetMessage.v	Array.<uint32>	Object version keys used to validate synchronization for all object properties.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

getAssetMessageResponse {
	"assetMessage": {
		"asset": number,
		"body": string,
		"company": number,
		"delivered": string,
		"folder": string,
		"from": string,
		"id": number,
		"incoming": boolean,
		"kind": string,
		"processed": string,
		"processedUtc": string,
		"readBy": string,
		"status": string,
		"subject": string,
		"to": string,
		"updated": {
		},
		"user": string,
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

Error Code	Description
3	The request does not contain a assetMessage object, or it is invalid.
3	The assetMessage object does not contain an id, or it is invalid.
5	You do not have permission to view the AssetMessages.
5	You do not have permission to view the Asset to which the AssetMessage belongs.
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 that owns this AssetMessage was not found. If you receive this error, please contact technical support.
63	The AssetMessage was not found by its unique identifier.
96	The Asset that owns this AssetMessage is suspended. Before reading AssetMessages from an Asset, it must be reactivated.

getAssetMessagesList

Gets the list of AssetMessages 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
folder	MessageFolder	optional		The folder from which to retrieve AssetMessages. Default is MessageFolder.inbox.
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.
reqId	int32?	optional		Identifier used by external system to correlate requests to responses.

Request message structure

getAssetMessagesList {
	"after": string,
	"asset": {
		"id": number
	},
	"before": string,
	"folder": 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 AssetMessages belong.
asset.company	uint64	Identifier of the Company to which this object belongs.
asset.id	uint64?	Identifier given as input for the command.
assetMessages	Array.<AssetMessage>	The list of requested AssetMessages.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

getAssetMessagesListResponse {
	"asset": {
		"company": number,
		"id": number
	},
	"assetMessages": [
		{
			"asset": number,
			"body": string,
			"company": number,
			"delivered": string,
			"folder": string,
			"from": string,
			"id": number,
			"incoming": boolean,
			"kind": string,
			"processed": string,
			"processedUtc": string,
			"readBy": string,
			"status": string,
			"subject": string,
			"to": string,
			"updated": {
			},
			"user": string,
			"v": [
				number
			]
		}
	],
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

Error Code	Description
2	A communication error occurred. If you receive this error, please contact technical support.
3	The request contains a folder value, but it is not valid.
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 AssetMessages.
5	You do not have permission to view the specified 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 that owns this message was not found.
96	The Asset that owns this message is suspended. Before reading messages from a Asset, it must be reactivated.

getAssetMessagesListByCompany

Gets the list of AssetMessages 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.
folder	MessageFolder	optional		The folder from which to retrieve AssetMessages. Default is MessageFolder.inbox.
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.
reqId	int32?	optional		Identifier used by external system to correlate requests to responses.

Request message structure

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

Response message description

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

Response message structure

getAssetMessagesListByCompanyResponse {
	"assetMessages": [
		{
			"asset": number,
			"body": string,
			"company": number,
			"delivered": string,
			"folder": string,
			"from": string,
			"id": number,
			"incoming": boolean,
			"kind": string,
			"processed": string,
			"processedUtc": string,
			"readBy": string,
			"status": string,
			"subject": string,
			"to": string,
			"updated": {
			},
			"user": string,
			"v": [
				number
			]
		}
	],
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

Error Code	Description
2	A communication error occurred. If you receive this error, please contact technical support.
3	The request contains a folder value, but it is not valid.
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 in the given Company.
5	You do not have permission to view AssetMessages.
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.

mergeAssetMessage

Creates a new or updates an existing AssetMessage.

Request message description

Property	Type	Required	Description
assetMessage	Object.<string, ?>	always	A simple object to contain the AssetMessage parameters.
assetMessage.asset	uint64?	create	The Asset that this AssetMessage was sent from or to. After creation, this value is read-only.
assetMessage.body	string	create	The body of the AssetMessage. After creation, this value is read-only.
assetMessage.folder	MessageFolder?	optional	The folder where this AssetMessage is stored.
assetMessage.id	uint64?	update	The unique identifier of the AssetMessage you want to update.
assetMessage.kind	MessageType?	create	The kind of protocol used for this AssetMessage. After creation, this value is read-only.
assetMessage.read	boolean	optional	Set to true to log that the AssetMessage was received and read by yourself. Once set, the AssetMessage.readBy value will be your login, and cannot be set by anyone else.
assetMessage.subject	string	optional	The AssetMessage subject field. After creation, this value is read-only. This is used exclusively with MessageType.email type AssetMessages.
assetMessage.to	string	create	Optional to address used when creating the AssetMessage if no messaging address is available. After creation, this value is read-only.
assetMessage.v	Array.<int32>	optional
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

Request message structure

mergeAssetMessage {
	"assetMessage": {
		"asset": number,
		"body": string,
		"folder": string,
		"id": number,
		"kind": string,
		"read": boolean,
		"subject": string,
		"to": string,
		"v": [
			number
		]
	},
	"reqId": number
}

Response message description

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

Response message structure

mergeAssetMessageResponse {
	"assetMessage": {
		"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 an assetMessage object, or it is invalid.
3	Not enough keys exist in the assetMessage object.
3	The folder was given, but is invalid.
3	During create: When creating a new AssetMessage, an assetMessage.asset was not given.
3	During create: When creating a new AssetMessage, a assetMessage.kind was not given.
3	During create: When creating a new AssetMessage, the assetMessage.kind was an invalid value.
3	During update: When updating a AssetMessage, the assetMessage.id was invalid.
3	During update: When updating a AssetMessage, the v was not an array, or contained too few numbers.
3	During update after read: When updating a AssetMessage after it has been read, the readBy field can not be changed.
5	You do not have permission to view the Asset to which the AssetMessage belongs.
5	During create: You do not have permission to send new AssetMessages.
5	During update: You do not have permission to update AssetMessages.
6	During update: When updating a AssetMessage, 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	During create: The Asset that owns this AssetMessage was not found.
63	During update: The AssetMessage was not found by its unique identifier.
96	During create: The Asset that owns this AssetMessage is suspended. Before sending or updating AssetMessages from a Asset, it must be reactivated.
130	During update: When updating a AssetMessage, the asset can not be changed.
130	During update: When updating a AssetMessage, the kind field can not be changed.
130	During update: When updating a AssetMessage, the to field can not be changed.
130	During update after sent: When updating a AssetMessage after processing, the subject field can not be changed.
130	During update after sent: When updating a AssetMessage after processing, the body field can not be changed.

multiMergeAssetMessage

Creates multiple new, or updates multiple existing AssetMessages.

Request message description

Property	Type	Required	Description
assetMessages	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

multiMergeAssetMessage {
	"assetMessages": [
		{
			"asset": number,
			"body": string,
			"folder": string,
			"id": number,
			"kind": string,
			"read": boolean,
			"subject": string,
			"to": string,
			"v": [
				number
			]
		}
	],
	"reqId": number
}

Response message description

Property	Type	Description
assetMessages	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

multiMergeAssetMessageResponse {
	"assetMessages": [
		{
			"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`.

removeAssetMessage

Deletes an existing AssetMessage.

Request message description

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

Request message structure

removeAssetMessage {
	"assetMessage": {
		"id": number
	},
	"reqId": number
}

Response message description

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

Response message structure

removeAssetMessageResponse {
	"assetMessage": {
		"asset": number,
		"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 assetMessage object, or it is invalid.
3	The assetMessage object does not contain an id, or it is invalid.
5	You do not have permission to delete AssetMessages.
5	You do not have permission to view the asset to which the AssetMessage belongs.
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 that owns this AssetMessage was not found. If you receive this error, please contact technical support.
63	The AssetMessage was not found by its unique identifier.
96	The asset that owns this AssetMessage is suspended. Before reading AssetMessages from an Asset, it must be reactivated.

restoreAssetMessage

Restores the specified AssetMessage to its previous version.

Request message description

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

Request message structure

restoreAssetMessage {
	"assetMessage": {
		"id": number
	},
	"reqId": number
}

Response message description

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

Response message structure

restoreAssetMessageResponse {
	"assetMessage": {
		"asset": number,
		"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 assetMessage object, or it is invalid.
3	The assetMessage object does not contain an id, or it is invalid.
5	You do not have permission to restore AssetMessages.
5	You do not have permission to view the Asset to which the AssetMessage belongs.
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 that owns this AssetMessage was not found. If you receive this error, please contact technical support.
63	The AssetMessage was not found by its unique identifier.
96	The Asset that owns this AssetMessage is suspended. Before reading AssetMessages from an Asset, it must be reactivated.
101	The AssetMessage was found, but is not marked as deleted.

Places

getPlace

Gets details of the specified Place.

Request message description

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

Request message structure

getPlace {
	"includeDeleted": boolean,
	"place": {
		"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.
place	Place	The requested Place.
place.address	string maximum-length: 200	Full street address including province/state, country, and postal/zip code.
place.anchor	LatLng	A central point of the shape. This is the exact centre of a PlaceType.radial and PlaceType.point shaped places, and the location of the pin on the map for all types. When routing, PlaceType.polygon and PlaceType.rectangle shapes use the anchor as the location within the place for deliveries.
place.anchor.lat	double	Latitude
place.anchor.lng	double	Longitude
place.colour	colour maximum-length: 22	The fill colour given to this place for easy visual identification on the map (given in 24bit hex; #RRGGBB)
place.company	uint64 see: Company.id	The company to which this POI belongs.
place.icon	uint64 see: Icon.id	The icon used to display this POI in lists and on the map.
place.id	uint64	Unique identifier of this place.
place.kind	PlaceType	The kind of geography represented by this POI.
place.labels	Array.<codified> for values see: LabelStyle.code	The codified names of labels
place.name	string maximum-length: 100	POI's common name instead of street address.
place.notes	string	Notes!
place.pictures	Array.<uint64> for values see: Picture.id	Images of this POI.
place.processedUtc	datetime	When the was change procesed.
place.radius	double?	This member is only present for PlaceType.radial shapes, and is the radius in meters from the centre anchor.
place.reference	string maximum-length: 100	A custom field used to refer to an external system.
place.shape	Array.<LatLng>	The geography representing this POI for rectangle and polygon shape types. For PlaceType.radial and PlaceType.point shape types, the shape key is not present. For a PlaceType.rectangle, the array contains the north east and south west corner coordinates. For a PlaceType.polygon, the array lists all coordinates (oriented as counter-clockwise) needed to draw the geofence.
place.updated		by: login, from: monster
place.v	Array.<int32> fixed count: 2	Object version keys used to validate synchronization for all object properties.
place.v[0]	int32	The first element is for the general properties
place.v[1]	int32	The second element is not used
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

getPlaceResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"place": {
		"address": string,
		"anchor": {
			"lat": number,
			"lng": number
		},
		"colour": string,
		"company": number,
		"icon": number,
		"id": number,
		"kind": string,
		"labels": [
			string
		],
		"name": string,
		"notes": string,
		"pictures": [
			number
		],
		"processedUtc": string,
		"radius": number,
		"reference": string,
		"shape": [
			{
				"lat": number,
				"lng": number
			}
		],
		"updated": {
		},
		"v": [
			number
		]
	},
	"reqId": number
}

Possible exceptions

Error Code	Description
3	The request does not contain a place object, or it is invalid.
3	The place object does not contain an id, or it is invalid.
5	You do not have permission to view this Place.
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.
40	The Place was not found by its unique identifier.

getPlacesList

Gets the list of Places 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

getPlacesList {
	"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 Places belong.
company.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
places	Array.<Place>	The list of requested Places.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

getPlacesListResponse {
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"places": [
		{
			"address": string,
			"anchor": {
				"lat": number,
				"lng": number
			},
			"colour": string,
			"company": number,
			"icon": number,
			"id": number,
			"kind": string,
			"labels": [
				string
			],
			"name": string,
			"notes": string,
			"pictures": [
				number
			],
			"processedUtc": string,
			"radius": number,
			"reference": string,
			"shape": [
				{
					"lat": number,
					"lng": number
				}
			],
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"reqId": number
}

Possible exceptions

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 Places 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.

getPlacesListByReference

Gets the list of Places for the specified Company only if the Place reference field is a match.

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
reference	string see: PlaceGeneral.reference	optional		Case-insensitive reference used to match Places.
reqId	int32?	optional		Identifier used by external system to correlate requests to responses.

Request message structure

getPlacesListByReference {
	"company": {
		"id": number
	},
	"highest": number,
	"includeArchive": boolean,
	"includeDeleted": boolean,
	"limit": number,
	"lowest": number,
	"reference": string,
	"reqId": number
}

Response message description

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

Response message structure

getPlacesListByReferenceResponse {
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"places": [
		{
			"address": string,
			"anchor": {
				"lat": number,
				"lng": number
			},
			"colour": string,
			"company": number,
			"icon": number,
			"id": number,
			"kind": string,
			"labels": [
				string
			],
			"name": string,
			"notes": string,
			"pictures": [
				number
			],
			"processedUtc": string,
			"radius": number,
			"reference": string,
			"shape": [
				{
					"lat": number,
					"lng": number
				}
			],
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"reference": string,
	"reqId": number
}

Possible exceptions

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 Places 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.

mergePlace

Creates a new, or updates an existing Place.

Request message description

Property	Type	Required	Description
place	Object.<string, ?>	always	A simple object to contain the Place parameters.
place.address	string	optional	Full street address including province/state, country, and postal/zip code.
place.anchor	LatLng	optional	Central lat/long coordinates. When not present, the shape centre is used for routing.
place.anchor.lat	double	optional	Latitude
place.anchor.lng	double	optional	Longitude
place.colour	colour maximum-length: 22	optional	The fill colour given to this Place for easy visual identification on the map.
place.company	uint64?	create	The Company to which this Place belongs. After creation, this value is read-only.
place.icon	uint64? see: Icon.id	create	The Icon used to display this POI in lists and on the map.
place.id	uint64?	update	The unique identifier of the Place you want to update.
place.kind	PlaceType?	create	The kind of shape being created.
place.labels	Array.<codified> for values see: LabelStyle.code	optional	The codified names of labels
place.name	string maximum-length: 100	create	Name for the Place.
place.notes	string	optional	Notes for the Place.
place.pictures	Array.<uint64> for values see: Picture.id	optional	The identifiers of Pictures of this Place.
place.radius	double?	create (radial)	Boundary threshold (in meters)
place.reference	string maximum-length: 100	optional	A custom field used to refer to an external system.
place.shape	Array.<LatLng>	create (rectangle or polygon)	For a PlaceType.rectangle, the input contains the north east and south west corner coordinates. For a PlaceType.polygon, the input lists all coordinates (oriented as counter-clockwise) needed to draw the geofence.
place.v	Array.<int32>	optional
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

Request message structure

mergePlace {
	"place": {
		"address": string,
		"anchor": {
			"lat": number,
			"lng": number
		},
		"colour": string,
		"company": number,
		"icon": number,
		"id": number,
		"kind": string,
		"labels": [
			string
		],
		"name": string,
		"notes": string,
		"pictures": [
			number
		],
		"radius": number,
		"reference": string,
		"shape": [
			{
				"lat": number,
				"lng": number
			}
		],
		"v": [
			number
		]
	},
	"reqId": number
}

Response 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.
place	RespIdCompany	An object which contains the "id" and "company" keys.
place.company	uint64	Identifier of the Company to which this object belongs.
place.id	uint64?	Identifier given as input for the command.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

mergePlaceResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"place": {
		"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.
3	The request does not contain a place object, or it is invalid.
3	No valid changes would be performed.
3	For a PlaceType.rectangle shape, the shape has fewer than 2 coordinates.
3	For a PlaceType.polygon shape, the shape has fewer than 3 coordinates.
3	During create: When creating a new Place, a name was not given.
3	During create: When creating a new Place, a company was not given.
3	During create: When creating a new Place, an icon was not given.
3	During update: When updating a Place, the name was given as null or blank.
3	During update: When updating a Place, the v was not an array, or contained too few numbers.
3	The place.kind was given, but it was invalid. Returns an ErrorDetailInput as the `errorDetails`.
3	The place.colour was given, but it was invalid. Returns an ErrorDetailInput as the `errorDetails`.
3	One of the place.pictures identifiers given in the array cannot be parsed, or is a value less than zero. Returns an ErrorDetailInput as the `errorDetails`.
3	The place.anchor was given, but it was invalid. Returns an ErrorDetailInput as the `errorDetails`.
3	One of the place.shape coordinates given in the array cannot be parsed, or is invalid. Returns an ErrorDetailInput as the `errorDetails`.
3	The place.shape string cannot be decoded using Google's Encoded Polyline algorithm. Returns an ErrorDetailInput as the `errorDetails`.
3	For a PlaceType.radial shape, the radius is outside of the size restrictions. Returns an ErrorDetailMinMax as the `errorDetails`.
3	For a PlaceType.rectangle shape, the diagonal distance is outside of the size restrictions. Returns an ErrorDetailMinMax as the `errorDetails`.
3	For a PlaceType.polygon shape, the widest diagonal distance is outside of the size restrictions. Returns an ErrorDetailMinMax as the `errorDetails`.
5	You do not have permission to create a new Place (with the given labels).
5	You do not have permission to update this Place.
6	During update: When updating a Place, 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	The place.icon given as input was not found.
40	During update: The Place was not found by its unique identifier.
69	One or more of the Picture identifiers given as input in the place.pictures array was not found. Returns an ErrorDetailBadIds as the `errorDetails`.
71	During update: Changing the labels on this Place in the requested way would grant you elevated access to it. Returns an ErrorDetailEscalation as the `errorDetails`.
130	During create: When creating a new `point` or `radial` Place, an anchor or address was not given.
130	During update: When updating a Place, the place.company can not be changed.

removePlace

Deletes an existing Place.

Request message description

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

Request message structure

removePlace {
	"place": {
		"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.
place	RespDeleted	An object which contains the place's id, owning company id, and deleted status.
place.company	uint64	Identifier of the Company to which this object belongs.
place.deleted	boolean	Flag showing if the object is deleted.
place.id	uint64?	Identifier given as input for the command.
place.v	Array.<uint32>
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

removePlaceResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"place": {
		"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 place object, or it is invalid.
3	The place object does not contain an id, or it is invalid.
5	You do not have permission to delete this Place.
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.
40	The Place was not found by its unique identifier.

restorePlace

Restores the specified Place.

Request message description

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

Request message structure

restorePlace {
	"place": {
		"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.
place	RespDeleted	An object which contains the place's id, owning company id, and deleted status.
place.company	uint64	Identifier of the Company to which this object belongs.
place.deleted	boolean	Flag showing if the object is deleted.
place.id	uint64?	Identifier given as input for the command.
place.v	Array.<uint32>
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

restorePlaceResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"place": {
		"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 place object, or it is invalid.
3	The place object does not contain an id, or it is invalid.
5	You do not have permission to restore this Place.
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.
40	The Place was not found by its unique identifier.
41	The Place was found, but is not marked as deleted.

Providers and Configurations

getProvider

Gets details of the specified Provider.

Request message description

Property	Type	Required	Default	Description
includeDeleted	boolean	optional	`false`	When true, the command will also return a deleted Provider.
provider	ParamIdentifier	always		An object to contain the "id" of the Provider.
provider.id	string	always		The Provider's identifier.
reqId	int32?	optional		Identifier used by external system to correlate requests to responses.

Request message structure

getProvider {
	"includeDeleted": boolean,
	"provider": {
		"id": string
	},
	"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.
provider	Provider	The requested Provider.
provider.asset	uint64? see: Asset.id	The asset for which this device provides field data.
provider.attributes	Object.<string, Object.<string, ProviderData>> for keys see: ProviderDataGroup for value-keys see: ProviderDataName	Often changing values like latitude, longitude, speed, wiring state, VBus information, etc...
provider.commands	Object.<ProviderCommandType, ProviderCommand>	Collection of commands for this provider.
provider.company	uint64 see: Company.id	The company to which this device belongs.
provider.configuration	uint64 see: ProviderConfig.id see: ProviderConfiguration.id	The provider's current (or pending) configuration profile.
provider.control	ProviderControl	Managing and controlling communication with this provider.
provider.control.commands	Object.<ProviderCommandType, ProviderCommand>	Collection of commands for this provider.
provider.control.company	uint64 see: Company.id	The company to which this device belongs.
provider.control.id	string see: Provider.id maximum-length: 50 minimum-length: 10	Unique identifier of this device.
provider.control.processedUtc	datetime	When the was change procesed.
provider.control.updated		by: login, from: monster
provider.control.v	Array.<uint32>	Object version keys used to validate synchronization for all object properties.
provider.firmware	string maximum-length: 100	The firmware/application version number.
provider.firmwareStatus	ProvisioningStatus	The system's progress of updating the device's firmware/application.
provider.geofenceLast	datetime	A timestamp from when the geofence list was updated by a User or a Provider.
provider.geofenceStatus	ProvisioningStatus	The system's progress of updating the device's on-board geofence definitions.
provider.id	string maximum-length: 50 minimum-length: 10	Unique identifier of this provider.
provider.information	Object.<string, string> for keys see: ProviderDataName	A list of read-only values about the device like IMEI, ESN, firmware version, hardware revision, etc...
provider.kind	ProviderType	The kind of communication protocol this device uses.
provider.lastCheckIn	datetime	A timestamp from when the provider last checked for a new script or new geofences.
provider.lastIP	ipv4	The last IP address of the device.
provider.name	string maximum-length: 100	A nickname given to the device/hardware.
provider.notes	string	Notes!
provider.password	string maximum-length: 50	The password programmed on the device used to ensure the system is the only client authorized to make changes.
provider.phoneNumber	uint64?	The phone number of this device.
provider.pnd	string maximum-length: 50	The short-name of the kind of PND attached to this device. Leave blank if none.
provider.processedUtc	datetime	When the was change procesed.
provider.scriptLast	datetime	A timestamp from when the script status was updated by a User or a Provider.
provider.scriptStatus	ProvisioningStatus	The system's progress of updating the device's programming.
provider.sim	string	ICCID of the SIM card installed in this provider
provider.snf	Object.<string, string>	Store-and-forward information like last sequence number of SnF window
provider.updated		by: login, from: monster
provider.v	Array.<int32> fixed count: 3	Object version keys used to validate synchronization for all object properties.
provider.v[0]	int32	The first element is for the general properties
provider.v[1]	int32	The second element is for the advanced properties
provider.v[2]	int32	The third element is for the control properties
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

getProviderResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"provider": {
		"asset": number,
		"attributes": {
			string: {
				string: {
					"dts": string,
					"unit": string,
					"value": Object
				}
			}
		},
		"commands": {
			string: {
				"created": string,
				"parameters": [
					string
				],
				"processed": string,
				"status": string
			}
		},
		"company": number,
		"configuration": number,
		"control": {
			"commands": {
				string: {
					"created": string,
					"parameters": [
						string
					],
					"processed": string,
					"status": string
				}
			},
			"company": number,
			"id": string,
			"processedUtc": string,
			"updated": {
			},
			"v": [
				number
			]
		},
		"firmware": string,
		"firmwareStatus": string,
		"geofenceLast": string,
		"geofenceStatus": string,
		"id": string,
		"information": {
			string: string
		},
		"kind": string,
		"lastCheckIn": string,
		"lastIP": string,
		"name": string,
		"notes": string,
		"password": string,
		"phoneNumber": number,
		"pnd": string,
		"processedUtc": string,
		"scriptLast": string,
		"scriptStatus": string,
		"sim": string,
		"snf": {
			string: string
		},
		"updated": {
		},
		"v": [
			number
		]
	},
	"reqId": number
}

Possible exceptions

Error Code	Description
3	The request does not contain a provider object, or it is invalid.
3	The provider object does not contain an id, or it is invalid.
5	You do not have permission to view this Provider.
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.
43	The Provider was not found by its unique identifier.

getProviderConfig

Gets details of the specified Provider Config.

Request message description

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

Request message structure

getProviderConfig {
	"includeDeleted": boolean,
	"providerConfig": {
		"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.
providerConfig	ProviderConfig	The requested ProviderConfig.
providerConfig.company	uint64 see: Company.id	The company to which this configuration belongs.
providerConfig.geofences	expression	A search pattern used to filter which Places' geometry are used as geofences. Use null to disable. Use "*" to match all the Places the Provider's Asset can match. Or use "#123456" or "label:term" like other Place search patterns.
providerConfig.id	uint64	Unique identifier of this configuration.
providerConfig.name	string maximum-length: 100	The nickname given to this configuration
providerConfig.notes	string	Simple details about how the providers are expected to behave.
providerConfig.parameters	Object.<string, string>	The list of defined variable name/value pairs that the script requires.
providerConfig.processedUtc	datetime	When the was change procesed.
providerConfig.script	uint64 see: ProviderScript.id	The script which this configuration implements.
providerConfig.updated		by: login, from: monster
providerConfig.v	Array.<uint32>	Object version keys used to validate synchronization for all object properties.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

getProviderConfigResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"providerConfig": {
		"company": number,
		"geofences": string,
		"id": number,
		"name": string,
		"notes": string,
		"parameters": {
			string: string
		},
		"processedUtc": string,
		"script": number,
		"updated": {
		},
		"v": [
			number
		]
	},
	"reqId": number
}

Possible exceptions

Error Code	Description
3	The request does not contain a providerConfig object, or it is invalid.
3	The providerConfig object does not contain an id, or it is invalid.
5	You do not have permission to view this ProviderConfig.
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 ProviderConfig was not found by its unique identifier.

getProviderConfigsList

Gets the list of ProviderConfigs 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

getProviderConfigsList {
	"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 ProviderConfigs belong.
company.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
providerConfigs	Array.<ProviderConfig>	The list of reqested ProviderConfigs.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

getProviderConfigsListResponse {
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"providerConfigs": [
		{
			"company": number,
			"geofences": string,
			"id": number,
			"name": string,
			"notes": string,
			"parameters": {
				string: string
			},
			"processedUtc": string,
			"script": number,
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"reqId": number
}

Possible exceptions

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 ProviderConfigs 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.

getProviderConfigType

Gets details of the specified ProviderConfigurationType.

Request message description

Property	Type	Required	Description
providerConfigurationType	ParamId	always	An object to contain the "id" of the ProviderConfigurationType.
providerConfigurationType.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

getProviderConfigType {
	"providerConfigurationType": {
		"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.
providerConfigurationType Deprecated	ProviderConfigurationType	The requested ProviderConfigurationTypes. Use ProviderScript instead.
providerConfigurationType.geofenceTypes	Array.<PlaceType>	A list of supported types of geofences which can be programmed directly onto the device.
providerConfigurationType.id	uint64	Unique identifier.
providerConfigurationType.maxGeofenceCount	uint32	The maximum number of geofences that can be programmed onto a device. This number changes based on device make and model, and can also change based on the supported geofence types.
providerConfigurationType.minGeofenceCount	uint32	The minimum number of geofences that need to be programmed onto the device. This value is almost always zero.
providerConfigurationType.name	string maximum-length: 100	Name of the configuration type.
providerConfigurationType.notes	string	Notes regarding the use of this configuration.
providerConfigurationType.processedUtc	datetime	When the was change procesed.
providerConfigurationType.providerType	ProviderType	The applicable type of provider for which this configuration type can be created.
providerConfigurationType.scriptOptions	Object.<string, ProviderConfigurationNode>	A tree-structure of configurations required (or optionally available) for programming a device.
providerConfigurationType.updated		by: login, from: monster
providerConfigurationType.v	Array.<uint32>	Object version keys used to validate synchronization for all object properties.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

getProviderConfigTypeResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"providerConfigurationType": {
		"geofenceTypes": [
			string
		],
		"id": number,
		"maxGeofenceCount": number,
		"minGeofenceCount": number,
		"name": string,
		"notes": string,
		"processedUtc": string,
		"providerType": string,
		"scriptOptions": {
			string: {
				"id": string,
				"isAdvanced": boolean,
				"max": Object,
				"min": Object,
				"nodes": {
					string: { /* recursive ProviderConfigurationNode objects */ }
				},
				"notes": string,
				"type": string,
				"unit": string,
				"value": Object
			}
		},
		"updated": {
		},
		"v": [
			number
		]
	},
	"reqId": number
}

Possible exceptions

Error Code	Description
3	The request does not contain a providerConfigurationType object, or it is invalid.
3	The providerConfigurationType object does not contain an id, or it is invalid.
5	You do not have permission to view ProviderConfigurationTypes.
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.
47	The ProviderConfigurationType was not found by its unique identifier.

getProviderConfigTypesList

Lists all the ProviderConfigurationTypes in the system.

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

getProviderConfigTypesList {
	"includeArchive": boolean,
	"includeDeleted": boolean,
	"limit": 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.
providerConfigurationTypes	Array.<ProviderConfigurationType>	The list of requested ProviderConfigurationTypes.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

getProviderConfigTypesListResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"providerConfigurationTypes": [
		{
			"geofenceTypes": [
				string
			],
			"id": number,
			"maxGeofenceCount": number,
			"minGeofenceCount": number,
			"name": string,
			"notes": string,
			"processedUtc": string,
			"providerType": string,
			"scriptOptions": {
				string: {
					"id": string,
					"isAdvanced": boolean,
					"max": Object,
					"min": Object,
					"nodes": {
						string: { /* recursive ProviderConfigurationNode objects */ }
					},
					"notes": string,
					"type": string,
					"unit": string,
					"value": Object
				}
			},
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"reqId": number
}

Possible exceptions

Error Code	Description
2	A communication error occurred. If you receive this error, please contact technical support.
5	You do not have permission to view ProviderConfigurationTypes.
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.

getProviderConfiguration

Gets details of the specified ProviderConfiguration.

Request message description

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

Request message structure

getProviderConfiguration {
	"includeDeleted": boolean,
	"providerConfiguration": {
		"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.
providerConfiguration Deprecated	ProviderConfiguration	The requested ProviderConfiguration. Use ProviderConfig instead.
providerConfiguration.company	uint64 see: Company.id	The company to which this configuration belongs.
providerConfiguration.geofences	Array.<uint64>	List of Places loaded directly onto the provider.
providerConfiguration.id	uint64	Unique identifier of this configuration.
providerConfiguration.name	string maximum-length: 100	The nickname given to this configuration
providerConfiguration.notes	string	Simple details about how the providers are expected to behave.
providerConfiguration.processedUtc	datetime	When the was change procesed.
providerConfiguration.scriptParameters	Object.<string, Object>	The list of defined variables given to the logic type's options pairs for the logic type requires.
providerConfiguration.type	uint64 see: ProviderConfigurationType.id	The logic type which this configuration implements.
providerConfiguration.updated		by: login, from: monster
providerConfiguration.v	Array.<uint32>	Object version keys used to validate synchronization for all object properties.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

getProviderConfigurationResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"providerConfiguration": {
		"company": number,
		"geofences": [
			number
		],
		"id": number,
		"name": string,
		"notes": string,
		"processedUtc": string,
		"scriptParameters": {
			string: Object
		},
		"type": number,
		"updated": {
		},
		"v": [
			number
		]
	},
	"reqId": number
}

Possible exceptions

Error Code	Description
3	The request does not contain a providerConfiguration object, or it is invalid.
3	The providerConfiguration object does not contain an id, or it is invalid.
5	You do not have permission to view this ProviderConfiguration.
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 ProviderConfiguration was not found by its unique identifier.

getProviderConfigurationsList

Gets the list of ProviderConfigurations 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

getProviderConfigurationsList {
	"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.
company.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
providerConfigurations	Array.<ProviderConfiguration>	The list of reqested ProviderConfigurations.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

getProviderConfigurationsListResponse {
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"providerConfigurations": [
		{
			"company": number,
			"geofences": [
				number
			],
			"id": number,
			"name": string,
			"notes": string,
			"processedUtc": string,
			"scriptParameters": {
				string: Object
			},
			"type": number,
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"reqId": number
}

Possible exceptions

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 ProviderConfigurations 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.

getProviderRegistration

Gets details of the specified ProviderRegistration.

Request message description

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

Request message structure

getProviderRegistration {
	"providerRegistration": {
		"code": string
	},
	"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.
providerRegistration	ProviderRegistration	The requested provider.
providerRegistration.asset	uint64? see: Asset.id	The Asset for which this device will provide data.
providerRegistration.code	string fixed length: 6	A unique six digit code.
providerRegistration.company	uint64 see: Company.id	The company to which the device will belong.
providerRegistration.completed	datetime	Date/time stamp of when this registration ended successfully.
providerRegistration.config	uint64 see: ProviderConfig.id see: ProviderConfiguration.id	The predefined configuration this device will use.
providerRegistration.expires	datetime	The expiry date for this registration.
providerRegistration.identifier	string see: Provider.id maximum-length: 50	The unique identifier of the device that completed this registration.
providerRegistration.kind	ProviderType	The kind of protocol this device supports.
providerRegistration.name	string maximum-length: 100	A nickname given to the device once it has been provisioned.
providerRegistration.notes	string	Notes!
providerRegistration.password	string maximum-length: 50	The password programmed on the device used to ensure the system is the only client authorized to make changes.
providerRegistration.phoneNumber	uint64?	The phone number of the device being provisioned. This is set by the user for long-term registrations, or by the client during serial port setup.
providerRegistration.since	datetime	Date/time stamp of when this registration began.
providerRegistration.user	email see: User.login maximum-length: 254	The unique identifier the user who generated this registration.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

getProviderRegistrationResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"providerRegistration": {
		"asset": number,
		"code": string,
		"company": number,
		"completed": string,
		"config": number,
		"expires": string,
		"identifier": string,
		"kind": string,
		"name": string,
		"notes": string,
		"password": string,
		"phoneNumber": number,
		"since": string,
		"user": string
	},
	"reqId": number
}

Possible exceptions

Error Code	Description
3	The request does not contain a providerRegistration object, or it is invalid.
3	The providerRegistration code is not an integer or is less than zero.
5	You do not have access to the ProviderConfig/ProviderConfigurations.
5	You do not have access to view Providers.
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.
86	The code is valid, but the ProviderRegistration was not found.

getProviderRegistrationsList

Gets the list of ProviderRegistrations for the specified Company.

Request message description

Property	Type	Required	Default	Description
company	ParamId	always		An object to contain the "id" of the Companyv.
company.id	uint64	always		Identifier given as input for the command.
highest	int32?	optional		The maximum ProviderRegistration.code when listing from the database.
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	int32?	optional		The minimum ProviderRegistration.code when listing from the database.
reqId	int32?	optional		Identifier used by external system to correlate requests to responses.

Request message structure

getProviderRegistrationsList {
	"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 providers belong.
company.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
providerRegistrations	Array.<ProviderRegistration>	The list of ProviderRegistrations.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

getProviderRegistrationsListResponse {
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"providerRegistrations": [
		{
			"asset": number,
			"code": string,
			"company": number,
			"completed": string,
			"config": number,
			"expires": string,
			"identifier": string,
			"kind": string,
			"name": string,
			"notes": string,
			"password": string,
			"phoneNumber": number,
			"since": string,
			"user": string
		}
	],
	"reqId": number
}

Possible exceptions

Error Code	Description
3	The request does not contain a company object, or it is invalid.
3	The company id is not an integer or is less than zero.
5	You do not have access to the ProviderConfigs/ProviderConfigurations.
5	You do not have access to view Providers.
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 value is valid, but could not be found.

getProviderRegistrationsListByKind

Gets the list of ProviderRegistrations for the specified ProviderType.

Request message description

Property	Type	Required	Default	Description
company	ParamId	always		An object to contain the "id" of the Companyv.
company.id	uint64	always		Identifier given as input for the command.
highest	int32?	optional		The maximum ProviderRegistration.code when listing from the database.
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.
kind	ProviderType?	optional		The type of ProviderRegistrations to list.
limit	uint16?	optional		Maximum number of objects in this response.
lowest	int32?	optional		The minimum ProviderRegistration.code when listing from the database.
reqId	int32?	optional		Identifier used by external system to correlate requests to responses.

Request message structure

getProviderRegistrationsListByKind {
	"company": {
		"id": number
	},
	"highest": number,
	"includeArchive": boolean,
	"includeDeleted": boolean,
	"kind": string,
	"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 providers belong.
company.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
kind	ProviderType?	The type of ProviderRegistrations being listed.
message	string	An English description of the error.
providerRegistrations	Array.<ProviderRegistration>	The list of ProviderRegistrations.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

getProviderRegistrationsListByKindResponse {
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"kind": string,
	"message": string,
	"providerRegistrations": [
		{
			"asset": number,
			"code": string,
			"company": number,
			"completed": string,
			"config": number,
			"expires": string,
			"identifier": string,
			"kind": string,
			"name": string,
			"notes": string,
			"password": string,
			"phoneNumber": number,
			"since": string,
			"user": string
		}
	],
	"reqId": number
}

Possible exceptions

Error Code	Description
3	The request does not contain a company object, or it is invalid.
3	The company id is not an integer or is less than zero.
3	The specified kind is not valid.
5	You do not have access to the ProviderConfigs/ProviderConfigurations.
5	You do not have access to view Providers.
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 value is valid, but could not be found.

getProviderScript

Gets details of the specified ProviderScript.

Request message description

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

Request message structure

getProviderScript {
	"includeDeleted": boolean,
	"providerScript": {
		"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.
providerScript	ProviderScript	The requested ProviderScript.
providerScript.blocks	Array.<ProviderScriptBlock>	Blocks of file data which are (optionally) included in the script data file.
providerScript.company	uint64 see: Company.id	The company to which this configuration belongs.
providerScript.fill	colour maximum-length: 22	The fill/background colour of the icon.
providerScript.global	boolean	Indicates whether this script is available to child companies.
providerScript.graphic	codified maximum-length: 22	The name of the symbol for this script.
providerScript.id	uint64	Unique identifier of this configuration.
providerScript.kind	ProviderType	The type of provider for which this script can be used. Limiting to a specific model from a manufacturer is accomplished through the block conditions.
providerScript.name	string maximum-length: 100	The nickname given to this configuration
providerScript.notes	string	Simple details about how the providers are expected to behave.
providerScript.parameters	Object.<string, ProviderScriptParameter>	Parameter definitions for this script, including type-hints and default values.
providerScript.processedUtc	datetime	When the was change procesed.
providerScript.stroke	colour maximum-length: 22	Outline and graphic colour.
providerScript.updated		by: login, from: monster
providerScript.v	Array.<uint32>	Object version keys used to validate synchronization for all object properties.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

getProviderScriptResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"providerScript": {
		"blocks": [
			{
				"condition": string,
				"content": string,
				"replace": string,
				"validate": string
			}
		],
		"company": number,
		"fill": string,
		"global": boolean,
		"graphic": string,
		"id": number,
		"kind": string,
		"name": string,
		"notes": string,
		"parameters": {
			string: {
				"advanced": boolean,
				"context": string,
				"notes": string,
				"order": number,
				"type": string,
				"value": string
			}
		},
		"processedUtc": string,
		"stroke": string,
		"updated": {
		},
		"v": [
			number
		]
	},
	"reqId": number
}

Possible exceptions

Error Code	Description
3	The request does not contain a providerScript object, or it is invalid.
3	The providerScript object does not contain an id, or it is invalid.
5	You do not have permission to view this ProviderScript.
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.
102	The ProviderScript was not found by its unique identifier.

getProviderScriptsList

Gets the list of ProviderScripts 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	`true`	When true (default) the getter to retrieve the given Company's list of ProviderScripts as well as any publicly available ProviderScripts for the Company's parent(s).

Request message structure

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

Response message description

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

Response message structure

getProviderScriptsListResponse {
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"providerScripts": [
		{
			"blocks": [
				{
					"condition": string,
					"content": string,
					"replace": string,
					"validate": string
				}
			],
			"company": number,
			"fill": string,
			"global": boolean,
			"graphic": string,
			"id": number,
			"kind": string,
			"name": string,
			"notes": string,
			"parameters": {
				string: {
					"advanced": boolean,
					"context": string,
					"notes": string,
					"order": number,
					"type": string,
					"value": string
				}
			},
			"processedUtc": string,
			"stroke": string,
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"reqId": number
}

Possible exceptions

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 ProviderScripts 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.

getProvidersList

Gets the list of Providers 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.
first	string	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.
includeSuspended	boolean	optional	`true`	When true, the command will also return suspended Providers.
last	string	optional
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

getProvidersList {
	"company": {
		"id": number
	},
	"first": string,
	"includeArchive": boolean,
	"includeDeleted": boolean,
	"includeSuspended": boolean,
	"last": string,
	"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 Providers belong.
company.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
providers	Array.<Provider>	The list of requested Providers.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

getProvidersListResponse {
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"providers": [
		{
			"asset": number,
			"attributes": {
				string: {
					string: {
						"dts": string,
						"unit": string,
						"value": Object
					}
				}
			},
			"commands": {
				string: {
					"created": string,
					"parameters": [
						string
					],
					"processed": string,
					"status": string
				}
			},
			"company": number,
			"configuration": number,
			"control": {
				"commands": {
					string: {
						"created": string,
						"parameters": [
							string
						],
						"processed": string,
						"status": string
					}
				},
				"company": number,
				"id": string,
				"processedUtc": string,
				"updated": {
				},
				"v": [
					number
				]
			},
			"firmware": string,
			"firmwareStatus": string,
			"geofenceLast": string,
			"geofenceStatus": string,
			"id": string,
			"information": {
				string: string
			},
			"kind": string,
			"lastCheckIn": string,
			"lastIP": string,
			"name": string,
			"notes": string,
			"password": string,
			"phoneNumber": number,
			"pnd": string,
			"processedUtc": string,
			"scriptLast": string,
			"scriptStatus": string,
			"sim": string,
			"snf": {
				string: string
			},
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"reqId": number
}

Possible exceptions

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 Providers 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.

getProvidersListByConfiguration

Gets the list of Providers for the specified ProviderConfig or ProviderConfiguration.

Request message description

Property	Type	Required	Default	Description
first	string	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.
includeSuspended	boolean	optional	`true`	When true, the command will also return suspended Providers.
last	string	optional
limit	uint16?	optional		Maximum number of objects in this response.
providerConfig	ParamId	always		An object to contain the "id" of the ProviderConfig/ProviderConfiguration.
providerConfig.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

getProvidersListByConfiguration {
	"first": string,
	"includeArchive": boolean,
	"includeDeleted": boolean,
	"includeSuspended": boolean,
	"last": string,
	"limit": number,
	"providerConfig": {
		"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.
providerConfig	RespIdCompany	An object to contain the "id" of the ProviderConfig/ProviderConfiguration to which the array of Providers belong.
providerConfig.company	uint64	Identifier of the Company to which this object belongs.
providerConfig.id	uint64?	Identifier given as input for the command.
providers	Array.<Provider>	The list of requested Providers.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

getProvidersListByConfigurationResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"providerConfig": {
		"company": number,
		"id": number
	},
	"providers": [
		{
			"asset": number,
			"attributes": {
				string: {
					string: {
						"dts": string,
						"unit": string,
						"value": Object
					}
				}
			},
			"commands": {
				string: {
					"created": string,
					"parameters": [
						string
					],
					"processed": string,
					"status": string
				}
			},
			"company": number,
			"configuration": number,
			"control": {
				"commands": {
					string: {
						"created": string,
						"parameters": [
							string
						],
						"processed": string,
						"status": string
					}
				},
				"company": number,
				"id": string,
				"processedUtc": string,
				"updated": {
				},
				"v": [
					number
				]
			},
			"firmware": string,
			"firmwareStatus": string,
			"geofenceLast": string,
			"geofenceStatus": string,
			"id": string,
			"information": {
				string: string
			},
			"kind": string,
			"lastCheckIn": string,
			"lastIP": string,
			"name": string,
			"notes": string,
			"password": string,
			"phoneNumber": number,
			"pnd": string,
			"processedUtc": string,
			"scriptLast": string,
			"scriptStatus": string,
			"sim": string,
			"snf": {
				string: string
			},
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"reqId": number
}

Possible exceptions

Error Code	Description
2	A communication error occurred. If you receive this error, please contact technical support.
3	The request does not contain a providerConfig object, or it is invalid.
3	The providerConfig object does not contain an id, or it is invalid.
5	You do not have permission to view Providers for this ProviderConfig/ProviderConfiguration.
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.
48	Could not find a ProviderConfig or ProviderConfiguration by the given identifier.

mergeProvider

Creates a new, or updates an existing Provider.

Request message description

Property	Type	Required	Description
provider	Object.<string, ?>	always	A simple object to contain the Provider parameters.
provider.asset	uint64?	optional	A reference to the Asset with which to provide events.
provider.config	uint64?	create	Identifier of the ProviderConfig/ProviderConfiguration this Provider will use.
provider.id	string maximum-length: 50 minimum-length: 10	always	Unique identifier of the Provider.
provider.kind	ProviderType?	create	The type of Provider.
provider.name	string maximum-length: 100	create	A name for the Provider.
provider.notes	string	optional	Notes for this Provider.
provider.password	string	optional	The password required to communicate and program this Provider.
provider.phone	uint64?	optional	The phone number this Provider uses (if known).
provider.pnd	string	optional	The name of the Personal Navigation Device connected to this Provider.
provider.v	Array.<int32>	optional
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

Request message structure

mergeProvider {
	"provider": {
		"asset": number,
		"config": number,
		"id": string,
		"kind": string,
		"name": string,
		"notes": string,
		"password": string,
		"phone": number,
		"pnd": 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.
provider	RespIdendifierCompany	An object which contains the "id" and "company" keys when there is no error.
provider.company	uint64	Identifier of the Company to which this object belongs.
provider.id	string	Identifier given as input for the command.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

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

Possible exceptions

Error Code	Description
2	A communication error occurred. If you receive this error, please contact technical support.
3	A name was given, but the value is blank or white-space only.
3	During create: When creating a new Provider, a name was not given.
3	During create: When creating a new Provider, a company was not given.
3	During create: When creating a new Provider, a kind was not given.
3	During create: When creating a new Provider, a configuration was not given.
3	During update: When updating a Provider, the name was given as null or blank.
3	During update: When updating a Provider, the v was not an array, or contained too few numbers.
3	During update: Not enough data was given to perform a change.
3	The kind value was given, but it is not a valid member of the enum. Returns an ErrorDetailEnum as the `errorDetails`.
3	The id was an invalid length. See the errorDetails for length requirements. Returns an ErrorDetailMinMax as the `errorDetails`.
3	The phone value was given, but it is not an integer. Returns an ErrorDetailPhone as the `errorDetails`.
5	You do not have permission to create Providers in the given company.
5	You do not have permission to the Asset for which this Provider is currently providing events.
5	You do not have permission to the Asset specified for this Provider to provide events.
5	You do not have permission to change ProviderConfigs/ProviderConfigurations.
5	During update: The specified ProviderConfig/ProviderConfiguration belongs to a different Company and you do not have permission to delete the Provider from its current Company.
5	During update: The specified ProviderConfig/ProviderConfiguration belongs to a different Company and you do not have permission to create the Provider in the new Company.
6	During update: When updating a Provider, 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	The specified Asset was not found.
43	The Provider you are trying to update was not found.
44	The command values are set to create a new Provider, but a Provider of the given id already exists.
47	The specified ProviderConfigurationType was not found. If you receive this error, please contact technical support.
48	The specified ProviderConfig/ProviderConfiguration was not found.
98	During update: When updating a Provider, the Provider is suspended. Before making changes to a Provider, it must be reactivated.
102	The specified ProviderScript was not found. If you receive this error, please contact technical support.
130	The specified ProviderConfig/ProviderConfiguration if for a different ProviderType.
130	The specified Asset belongs to a different Company.
130	The specified ProviderConfig/ProviderConfiguration belongs to a different Company and the Asset was not null (and not set to null or an asset from the new company).
130	During update: The Provider's provider.kind can not be changed after it is created.

mergeProviderConfig

Creates a new or updates an existing ProviderConfig.

Request message description

Property	Type	Required	Description
providerConfig	Object.<string, ?>	always	A simple object to contain the ProviderConfig parameters.
providerConfig.company	uint64?	create	The Company to which the ProviderConfig belongs.
providerConfig.geofences	expression	optional	A search pattern used to filter which Places' geometry are used as geofences. Use null or blank string to disable. Use "*" to match all the Places the Provider's Asset can match. Or use "#123456" or "label:term" like other Place search patterns.
providerConfig.id	uint64?	update	The unique identifier of the ProviderConfig you want to update.
providerConfig.name	string maximum-length: 100	create	Name for the ProviderConfig.
providerConfig.notes	string	optional	Notes for the ProviderConfig.
providerConfig.parameters	Object.<string, string>	optional	The values needed to implement the script. Each key in this object is the name of a required script variable.
providerConfig.script	uint64?	create	The ProviderScript to the ProviderConfig implements. After creation, this value is read-only.
providerConfig.v	Array.<int32>	optional
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

Request message structure

mergeProviderConfig {
	"providerConfig": {
		"company": number,
		"geofences": string,
		"id": number,
		"name": string,
		"notes": string,
		"parameters": {
			string: string
		},
		"script": number,
		"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.
providerConfig	RespIdScript	An object which contains the "id", "company", and "script" keys when there is no error.
providerConfig.company	uint64	Identifier of the Company to which this object belongs.
providerConfig.id	uint64?	Identifier given as input for the command.
providerConfig.script	uint64	Identifier of the script to which this object belongs.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

mergeProviderConfigResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"providerConfig": {
		"company": number,
		"id": number,
		"script": 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 providerConfig object, or it is invalid.
3	Not enough keys exist in the providerConfig object.
3	During create: When creating a new ProviderConfig, a name was not given, or it is invalid.
3	During create: When creating a new ProviderConfig, a company was not given.
3	During create: When creating a new ProviderConfig, a script was not given.
3	During update: When updating a ProviderConfig, the id was invalid.
3	During update: When updating a ProviderConfig, the name was given as blank.
3	During update: When updating a ProviderConfig, the v was not an array, or contained too few numbers.
3	One of the providerConfig.parameters was invalid. Returns an ErrorDetailBadKeys as the `errorDetails`.
3	One of the providerConfig.parameters keys was blank or white-space. Returns an ErrorDetailInput as the `errorDetails`.
5	You do not have permission to create a new ProviderConfig.
5	You do not have permission to update this ProviderConfig.
6	During update: When updating a ProviderConfig, 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.
48	During update: The ProviderConfig was not found by its unique identifier.
102	The ProviderScript was not found by its unique identifier.
102	The ProviderScript was found, but does not belong in the target company's tree.
130	There is one or more missing or invalid providerConfig.parameters required by the ProviderScript.
130	During update: When updating a ProviderConfig, the providerConfig.script can not be changed.
130	During update: When updating a ProviderConfig, the providerConfig.company can not be changed.

mergeProviderConfiguration

Creates a new or updates an existing ProviderConfiguration.

Request message description

Property	Type	Required	Description
providerConfiguration	Object.<string, ?>	always	A simple object to contain the ProviderConfiguration parameters.
providerConfiguration.company	uint64?	create	The Company to which the ProviderConfiguration belongs.
providerConfiguration.geofences	Array.<uint64> for values see: Place.id	optional	A list of Places whose shape is programmed directly onto Providers to raise instant boundary events.
providerConfiguration.id	uint64?	update	The unique identifier of the ProviderConfiguration you want to update.
providerConfiguration.name	string maximum-length: 100	create	Name for the ProviderConfiguration.
providerConfiguration.notes	string	optional	Notes for the ProviderConfiguration.
providerConfiguration.scriptParameters	Object.<string, Object>	optional	The values needed to implement the ProviderConfigurationType. Each key in this object is the identifier of a required ProviderConfigurationNode. This command does not support patch semantics; all keys must be sent if any are sent.
providerConfiguration.type	uint64?	create	The ProviderConfigurationType that the ProviderConfiguration implements. After creation, this value is read-only.
providerConfiguration.v	Array.<int32>	optional
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

Request message structure

mergeProviderConfiguration {
	"providerConfiguration": {
		"company": number,
		"geofences": [
			number
		],
		"id": number,
		"name": string,
		"notes": string,
		"scriptParameters": {
			string: Object
		},
		"type": number,
		"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.
providerConfiguration	RespIdScript	An object which contains the "id", "company", and "script" keys when there is no error.
providerConfiguration.company	uint64	Identifier of the Company to which this object belongs.
providerConfiguration.id	uint64?	Identifier given as input for the command.
providerConfiguration.script	uint64	Identifier of the script to which this object belongs.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

mergeProviderConfigurationResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"providerConfiguration": {
		"company": number,
		"id": number,
		"script": 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 providerConfiguration object, or it is invalid.
3	Not enough keys exist in the providerConfiguration object.
3	During create: When creating a new ProviderConfiguration, a name was not given, or it is invalid.
3	During create: When creating a new ProviderConfiguration, a company was not given.
3	During create: When creating a new ProviderConfiguration, a type was not given.
3	During update: When updating a ProviderConfiguration, the id was invalid.
3	During update: When updating a ProviderConfiguration, the name was given as blank.
3	During update: When updating a ProviderConfiguration, the v was not an array, or contained too few numbers.
3	One of the providerConfiguration.scriptParameters was invalid. Returns an ErrorDetailBadKeys as the `errorDetails`.
3	There is one or more missing or invalid providerConfiguration.scriptParameters required by the ProviderConfigurationType. Returns an ErrorDetailBadKeys as the `errorDetails`.
3	One or more of the providerConfiguration.geofences Places were not a supported shape. Returns an ErrorDetailExternals as the `errorDetails`.
3	One of the providerConfiguration.scriptParameters keys was blank or white-space. Returns an ErrorDetailInput as the `errorDetails`.
3	One of the providerConfiguration.geofences values was not a valid number. Returns an ErrorDetailInput as the `errorDetails`.
5	You do not have permission to create a new ProviderConfiguration.
5	You do not have permission to update this ProviderConfiguration.
5	You do not have permission to one or more Places specified as a providerConfiguration.geofences value.
6	During update: When updating a ProviderConfiguration, 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.
42	One or more of the providerConfiguration.geofences Places were not found by its unique identifier.
47	During create: The ProviderConfigurationType was not found by its unique identifier.
48	During update: The ProviderConfiguration was not found by its unique identifier.
51	One or more of the providerConfiguration.scriptParameters or providerConfiguration.geofences values was invalid. Returns an ErrorDetailExternals as the `errorDetails`.
130	During update: When updating a ProviderConfiguration, the providerConfiguration.company can not be changed.
130	During update: When updating a ProviderConfiguration, the providerConfiguration.type can not be changed.

mergeProviderRegistration

Creates a new ProviderRegistration for a provider pending configuration.

Request message description

Property	Type	Required	Description
providerRegistration	Object.<string, ?>	always	A simple object to contain the ProviderRegistration parameters.
providerRegistration.asset	uint64?	optional	An optional Asset to which the new Provider will be assigned.
providerRegistration.config	uint64	create	The identifier of the ProviderConfig/ProviderConfiguration that will be loaded onto the new Provider.
providerRegistration.identifier	string see: Provider.id maximum-length: 50	optional	Identifier of the Provider to setup. This is helpful for long-term deployments, but will be overwritten during provisioning.
providerRegistration.lifetime	timespan	optional	The lifetime of the ProviderRegistration. The default value (if not specified) is 10 minutes. It can be specified as up to 2 months to allow for longer deployments.
providerRegistration.name	string maximum-length: 100	optional	A nickname given to the Provider once it has been provisioned.
providerRegistration.notes	string	optional	Notes about the Provider for after it's been programmed.
providerRegistration.password	string maximum-length: 50	optional	The password programmed on the Provider used to ensure the system is the only client authorized to make changes.
providerRegistration.phone	uint64?	optional	If known beforehand, a phone number can be specified for new Providers.
providerRegistration.v	Array.<int32>	optional
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

Request message structure

mergeProviderRegistration {
	"providerRegistration": {
		"asset": number,
		"config": number,
		"identifier": string,
		"lifetime": string,
		"name": string,
		"notes": string,
		"password": string,
		"phone": number,
		"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.
providerRegistration	ProviderRegistration	The complete ProviderRegistration object.
providerRegistration.asset	uint64? see: Asset.id	The Asset for which this device will provide data.
providerRegistration.code	string fixed length: 6	A unique six digit code.
providerRegistration.company	uint64 see: Company.id	The company to which the device will belong.
providerRegistration.completed	datetime	Date/time stamp of when this registration ended successfully.
providerRegistration.config	uint64 see: ProviderConfig.id see: ProviderConfiguration.id	The predefined configuration this device will use.
providerRegistration.expires	datetime	The expiry date for this registration.
providerRegistration.identifier	string see: Provider.id maximum-length: 50	The unique identifier of the device that completed this registration.
providerRegistration.kind	ProviderType	The kind of protocol this device supports.
providerRegistration.name	string maximum-length: 100	A nickname given to the device once it has been provisioned.
providerRegistration.notes	string	Notes!
providerRegistration.password	string maximum-length: 50	The password programmed on the device used to ensure the system is the only client authorized to make changes.
providerRegistration.phoneNumber	uint64?	The phone number of the device being provisioned. This is set by the user for long-term registrations, or by the client during serial port setup.
providerRegistration.since	datetime	Date/time stamp of when this registration began.
providerRegistration.user	email see: User.login maximum-length: 254	The unique identifier the user who generated this registration.
registration Deprecated	ProviderRegistration	Use providerRegistration instead..
registration.asset	uint64? see: Asset.id	The Asset for which this device will provide data.
registration.code	string fixed length: 6	A unique six digit code.
registration.company	uint64 see: Company.id	The company to which the device will belong.
registration.completed	datetime	Date/time stamp of when this registration ended successfully.
registration.config	uint64 see: ProviderConfig.id see: ProviderConfiguration.id	The predefined configuration this device will use.
registration.expires	datetime	The expiry date for this registration.
registration.identifier	string see: Provider.id maximum-length: 50	The unique identifier of the device that completed this registration.
registration.kind	ProviderType	The kind of protocol this device supports.
registration.name	string maximum-length: 100	A nickname given to the device once it has been provisioned.
registration.notes	string	Notes!
registration.password	string maximum-length: 50	The password programmed on the device used to ensure the system is the only client authorized to make changes.
registration.phoneNumber	uint64?	The phone number of the device being provisioned. This is set by the user for long-term registrations, or by the client during serial port setup.
registration.since	datetime	Date/time stamp of when this registration began.
registration.user	email see: User.login maximum-length: 254	The unique identifier the user who generated this registration.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

mergeProviderRegistrationResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"providerRegistration": {
		"asset": number,
		"code": string,
		"company": number,
		"completed": string,
		"config": number,
		"expires": string,
		"identifier": string,
		"kind": string,
		"name": string,
		"notes": string,
		"password": string,
		"phoneNumber": number,
		"since": string,
		"user": string
	},
	"registration": {
		"asset": number,
		"code": string,
		"company": number,
		"completed": string,
		"config": number,
		"expires": string,
		"identifier": string,
		"kind": string,
		"name": string,
		"notes": string,
		"password": string,
		"phoneNumber": number,
		"since": string,
		"user": string
	},
	"reqId": number
}

Possible exceptions

Error Code	Description
2	The service was not abe to generate a unique code. If you receive this error, please contact technical support.
2	A communication error occurred. If you receive this error, please contact technical support.
3	The request does not contain a providerRegistration object, or it is invalid.
3	The providerRegistration.config value is not an integer.
3	The providerRegistration.asset value was given, but it is not an integer.
3	The lifetime value was given and valid, but was too long of a time-span. Returns an ErrorDetailInput as the `errorDetails`.
3	The phone value was given, but it is not an integer. Returns an ErrorDetailPhone as the `errorDetails`.
5	You do not have access to the ProviderConfigs/ProviderConfigurations.
5	You do not have access to create new Provider.
5	You do not have access to the Asset being associated.
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 specified Asset was not found.
47	The specified ProviderConfiguration is invalid. If you receive this error, please contact technical support.
48	The specified ProviderConfig/ProviderConfiguration was not found.
102	The specified ProviderConfig is invalid. If you receive this error, please contact technical support.
130	The specified Asset was found, but was not in the same Company as the given ProviderConfig/ProviderConfiguration.

mergeProviderScript

Creates a new or updates an existing ProviderScript.

Request message description

Property	Type	Required	Description
providerScript	Object.<string, ?>	always	A simple object to contain the ProviderScript parameters.
providerScript.blocks	Array.<ProviderScriptBlock> minimum-count of values: 1	create	Blocks of file data which are (optionally) included in the ProviderScript data file.
providerScript.company	uint64?	create	The Company to which this ProviderScript belongs. After creation, this value is read-only.
providerScript.fill	string	optional	Background and fill colour in the UI.
providerScript.global	boolean	optional	Indicates whether this ProviderScript is available to child companies.
providerScript.graphic	string	optional	The name of the symbol shown in the UI.
providerScript.id	uint64?	update	The unique identifier of the ProviderScript you want to update.
providerScript.kind	ProviderType?	create	The type of provider for which this ProviderScript can be used. Limiting to a specific model from a manufacturer is accomplished through the block conditions.
providerScript.name	string maximum-length: 100	optional	Name for the ProviderScript.
providerScript.notes	string	optional	Notes for the ProviderScript.
providerScript.parameters	Object.<string, ProviderScriptParameter>	optional	Parameter definitions for this ProviderScript, including type-hints and default values.
providerScript.stroke	string	optional	Text and outline colour in the UI.
providerScript.v	Array.<int32>	optional
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

Request message structure

mergeProviderScript {
	"providerScript": {
		"blocks": [
			{
				"condition": string,
				"content": string,
				"replace": string,
				"validate": string
			}
		],
		"company": number,
		"fill": string,
		"global": boolean,
		"graphic": string,
		"id": number,
		"kind": string,
		"name": string,
		"notes": string,
		"parameters": {
			string: {
				"advanced": boolean,
				"context": string,
				"notes": string,
				"order": number,
				"type": string,
				"value": string
			}
		},
		"stroke": string,
		"v": [
			number
		]
	},
	"reqId": number
}

Response 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.
providerScript	RespIdCompany	An object which contains the "id" and "company" keys when there is no error.
providerScript.company	uint64	Identifier of the Company to which this object belongs.
providerScript.id	uint64?	Identifier given as input for the command.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

mergeProviderScriptResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"providerScript": {
		"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.
3	The request does not contain a providerScript object, or it is invalid.
3	Not enough keys exist in the providerScript object.
3	The given kind was not valid ProviderType.
3	During create: When creating a new ProviderScript, a name was not given, or it is invalid.
3	During create: When creating a new ProviderScript, a company was not given.
3	During create: When creating a new ProviderScript, a kind was not given, or it is invalid.
3	During create: When creating a new ProviderScript, at least one block must be given.
3	During update: When updating a ProviderScript, the id was invalid.
3	During update: When updating a ProviderScript, the name was given as blank.
3	During update: When updating a ProviderScript, the v was not an array, or contained too few numbers.
3	One of the providerScript.blocks was invalid. Returns an ErrorDetailInput as the `errorDetails`.
3	One of the providerScript.blocks `replace` value was not a valid regular expression. Returns an ErrorDetailInput as the `errorDetails`.
3	One of the providerScript.parameters was invalid. Returns an ErrorDetailInput as the `errorDetails`.
3	One of the providerScript.parameters keys was blank or white-space. Returns an ErrorDetailInput as the `errorDetails`.
5	You do not have permission to create a new ProviderScript.
5	You do not have permission to update this ProviderScript.
6	During update: When updating a ProviderScript, 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.
102	During update: The ProviderScript was not found by its unique identifier.
104	During update: When updating a ProviderScript which is marked as global, but is being set as private, but is implemented by ProviderConfigs from child companies. Returns an ErrorDetailCount as the `errorDetails`.
130	During update: When updating a ProviderScript, the providerScript.company can not be changed.
130	During update: When updating a ProviderScript, the providerScript.kind can not be changed.
130	There is one or more missing parameters identified as variables in the providerScript.blocks. Returns an ErrorDetailBadKeys as the `errorDetails`.

removeProvider

Deletes the specified Provider from the system.

Request message description

Property	Type	Required	Description
provider	ParamIdentifier	always	An object to contain the "id" of the Provider.
provider.id	string	always	The Provider's identifier.
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

Request message structure

removeProvider {
	"provider": {
		"id": string
	},
	"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.
provider	RespIdendifierDeleted	An object which contains the Provider's id, owning Company id, and deleted status.
provider.company	uint64	Identifier of the Company to which this object belongs.
provider.deleted	boolean	Flag showing if the object is deleted.
provider.id	string	Identifier given as input for the command.
provider.v	Array.<uint32>
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

removeProviderResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"provider": {
		"company": number,
		"deleted": boolean,
		"id": string,
		"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 provider object, or it is invalid.
3	The provider object does not contain an id, or it is invalid.
5	You do not have permission to delete this Provider.
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.
43	The Provider was not found by its unique identifier.

removeProviderConfig

Deletes a ProviderConfig.

Request message description

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

Request message structure

removeProviderConfig {
	"providerConfig": {
		"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.
providerConfig	RespDeleted	An object which contains the ProviderConfig's id, owning Company id, and deleted status.
providerConfig.company	uint64	Identifier of the Company to which this object belongs.
providerConfig.deleted	boolean	Flag showing if the object is deleted.
providerConfig.id	uint64?	Identifier given as input for the command.
providerConfig.v	Array.<uint32>
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

removeProviderConfigResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"providerConfig": {
		"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 providerConfig object, or it is invalid.
3	The providerConfig object does not contain an id, or it is invalid.
5	You do not have permission to delete this ProviderConfig.
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.
48	The ProviderConfig was not found by its unique identifier.

removeProviderConfiguration

Deletes a ProviderConfiguration.

Request message description

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

Request message structure

removeProviderConfiguration {
	"providerConfiguration": {
		"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.
providerConfiguration	RespDeleted	An object which contains the ProviderConfiguration's id, owning Company id, and deleted status.
providerConfiguration.company	uint64	Identifier of the Company to which this object belongs.
providerConfiguration.deleted	boolean	Flag showing if the object is deleted.
providerConfiguration.id	uint64?	Identifier given as input for the command.
providerConfiguration.v	Array.<uint32>
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

removeProviderConfigurationResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"providerConfiguration": {
		"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 providerConfiguration object, or it is invalid.
3	The providerConfiguration object does not contain an id, or it is invalid.
5	You do not have permission to delete this ProviderConfiguration.
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.
48	The ProviderConfiguration was not found by its unique identifier.

removeProviderRegistration

Gets details of the specified ProviderRegistration.

Request message description

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

Request message structure

removeProviderRegistration {
	"providerRegistration": {
		"code": string
	},
	"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.
providerRegistration	ProviderRegistration	The requested provider.
providerRegistration.asset	uint64? see: Asset.id	The Asset for which this device will provide data.
providerRegistration.code	string fixed length: 6	A unique six digit code.
providerRegistration.company	uint64 see: Company.id	The company to which the device will belong.
providerRegistration.completed	datetime	Date/time stamp of when this registration ended successfully.
providerRegistration.config	uint64 see: ProviderConfig.id see: ProviderConfiguration.id	The predefined configuration this device will use.
providerRegistration.expires	datetime	The expiry date for this registration.
providerRegistration.identifier	string see: Provider.id maximum-length: 50	The unique identifier of the device that completed this registration.
providerRegistration.kind	ProviderType	The kind of protocol this device supports.
providerRegistration.name	string maximum-length: 100	A nickname given to the device once it has been provisioned.
providerRegistration.notes	string	Notes!
providerRegistration.password	string maximum-length: 50	The password programmed on the device used to ensure the system is the only client authorized to make changes.
providerRegistration.phoneNumber	uint64?	The phone number of the device being provisioned. This is set by the user for long-term registrations, or by the client during serial port setup.
providerRegistration.since	datetime	Date/time stamp of when this registration began.
providerRegistration.user	email see: User.login maximum-length: 254	The unique identifier the user who generated this registration.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

removeProviderRegistrationResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"providerRegistration": {
		"asset": number,
		"code": string,
		"company": number,
		"completed": string,
		"config": number,
		"expires": string,
		"identifier": string,
		"kind": string,
		"name": string,
		"notes": string,
		"password": string,
		"phoneNumber": number,
		"since": string,
		"user": string
	},
	"reqId": number
}

Possible exceptions

Error Code	Description
2	A communication error occurred. If you receive this error, please contact technical support.
3	The request does not contain a providerRegistration object, or it is invalid.
3	The providerRegistration code is not an integer or is less than zero.
5	You do not have access to the ProviderConfig/ProviderConfigurations.
5	You do not have access to create new Providers.
5	You do not have access to 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.
86	The code is valid, but the ProviderRegistration was not found, or has already been completed.

removeProviderScript

Deletes an existing ProviderScript.

Request message description

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

Request message structure

removeProviderScript {
	"providerScript": {
		"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.
providerScript	RespDeleted	An object which contains the ProviderScript's id, owning company id, and deleted status.
providerScript.company	uint64	Identifier of the Company to which this object belongs.
providerScript.deleted	boolean	Flag showing if the object is deleted.
providerScript.id	uint64?	Identifier given as input for the command.
providerScript.v	Array.<uint32>
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

removeProviderScriptResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"providerScript": {
		"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 providerScript object, or it is invalid.
3	The providerScript object does not contain an id, or it is invalid.
5	You do not have permission to delete this ProviderScript.
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.
102	The ProviderScript was not found by its unique identifier.
104	This ProviderScript is still being used by one of more ProviderConfigs. Returns an ErrorDetailCount as the `errorDetails`.

restoreProvider

Restores a deleted Provider.

Request message description

Property	Type	Required	Description
provider	ParamIdentifier	always	An object to contain the "id" of the Provider.
provider.id	string	always	The Provider's identifier.
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

Request message structure

restoreProvider {
	"provider": {
		"id": string
	},
	"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.
provider	RespIdendifierDeleted	An object which contains the Provider's id, owning Company id, and deleted status.
provider.company	uint64	Identifier of the Company to which this object belongs.
provider.deleted	boolean	Flag showing if the object is deleted.
provider.id	string	Identifier given as input for the command.
provider.v	Array.<uint32>
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

restoreProviderResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"provider": {
		"company": number,
		"deleted": boolean,
		"id": string,
		"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 provider object, or it is invalid.
3	The provider object does not contain an id, or it is invalid.
5	You do not have permission to restore this Provider.
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.
43	The Provider was not found by its unique identifier.
44	The Provider was found, but is not marked as deleted.

restoreProviderConfig

Restores a deleted ProviderConfig.

Request message description

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

Request message structure

restoreProviderConfig {
	"providerConfig": {
		"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.
providerConfig	RespDeleted	An object which contains the ProviderConfig's id, owning Company id, and deleted status.
providerConfig.company	uint64	Identifier of the Company to which this object belongs.
providerConfig.deleted	boolean	Flag showing if the object is deleted.
providerConfig.id	uint64?	Identifier given as input for the command.
providerConfig.v	Array.<uint32>
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

restoreProviderConfigResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"providerConfig": {
		"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 providerConfig object, or it is invalid.
3	The providerConfig object does not contain an id, or it is invalid.
5	You do not have permission to restore this ProviderConfig.
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.
48	The ProviderConfig was not found by its unique identifier.
49	The ProviderConfig was found, but is not marked as deleted.

restoreProviderConfiguration

Restores a deleted ProviderConfiguration.

Request message description

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

Request message structure

restoreProviderConfiguration {
	"providerConfiguration": {
		"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.
providerConfiguration	RespDeleted	An object which contains the ProviderConfiguration's id, owning Company id, and deleted status.
providerConfiguration.company	uint64	Identifier of the Company to which this object belongs.
providerConfiguration.deleted	boolean	Flag showing if the object is deleted.
providerConfiguration.id	uint64?	Identifier given as input for the command.
providerConfiguration.v	Array.<uint32>
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

restoreProviderConfigurationResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"providerConfiguration": {
		"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 providerConfiguration object, or it is invalid.
3	The providerConfiguration object does not contain an id, or it is invalid.
5	You do not have permission to restore this ProviderConfiguration.
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.
48	The ProviderConfiguration was not found by its unique identifier.
49	The ProviderConfiguration was found, but is not marked as deleted.

restoreProviderScript

Restores the specified ProviderScript.

Request message description

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

Request message structure

restoreProviderScript {
	"providerScript": {
		"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.
providerScript	RespDeleted	An object which contains the ProviderScript's id, owning company id, and deleted status.
providerScript.company	uint64	Identifier of the Company to which this object belongs.
providerScript.deleted	boolean	Flag showing if the object is deleted.
providerScript.id	uint64?	Identifier given as input for the command.
providerScript.v	Array.<uint32>
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

restoreProviderScriptResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"providerScript": {
		"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 providerScript object, or it is invalid.
3	The providerScript object does not contain an id, or it is invalid.
5	You do not have permission to restore this ProviderScript.
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.
102	The ProviderScript was not found by its unique identifier.
103	The ProviderScript was found, but is not marked as deleted.

reviveProvider

Revives (disables suspension on) an existing Provider.

Request message description

Property	Type	Required	Description
provider	ParamIdentifier	always	An object to contain the "id" of the Provider.
provider.id	string	always	The Provider's identifier.
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

Request message structure

reviveProvider {
	"provider": {
		"id": string
	},
	"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.
provider	RespIdendifierSuspended	An object which contains the Provider's unique identifier and suspended status.
provider.company	uint64	Identifier of the Company to which this object belongs.
provider.id	string	Identifier given as input for the command.
provider.suspended	boolean	Flag showing if the object is suspended.
provider.v	Array.<uint32>
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

reviveProviderResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"provider": {
		"company": number,
		"id": string,
		"suspended": boolean,
		"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 provider object, or it is invalid.
3	The provider object does not contain an id, or it is invalid.
5	You do not have permission to revive this Provider.
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.
43	The Provider was not found by its unique identifier.
99	The Provider was found, but is not marked as suspended.

suspendProvider

Suspends an existing Provider.

Request message description

Property	Type	Required	Description
provider	ParamIdentifier	always	An object to contain the "id" of the Provider.
provider.id	string	always	The Provider's identifier.
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

Request message structure

suspendProvider {
	"provider": {
		"id": string
	},
	"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.
provider	RespIdendifierSuspended	An object which contains the Provider's unique identifier and suspended status.
provider.company	uint64	Identifier of the Company to which this object belongs.
provider.id	string	Identifier given as input for the command.
provider.suspended	boolean	Flag showing if the object is suspended.
provider.v	Array.<uint32>
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

suspendProviderResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"provider": {
		"company": number,
		"id": string,
		"suspended": boolean,
		"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 provider object, or it is invalid.
3	The provider object does not contain an id, or it is invalid.
5	You do not have permission to suspended this Provider.
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.
43	The Provider was not found by its unique identifier.
98	The Provider was not found, but it is already marked as suspended.
99	The Provider was previously revived within the minimum period. Returns an ErrorDetailLocked as the `errorDetails`.

Reports

getReportResult

Gets details of the specified ReportResult. Optionally, can also retrieve the report summary and breakdown. The WebSocket does not support serializing the ReportResult.summary or ReportResult.breakdown. Instead, please use the RESTful or Reports service.

Request message description

Property	Type	Required	Default	Description
breakdown	boolean	optional		When true, will also retrieve all the ReportBreakdowns (when used through an applicable REST service).
includeDeleted	boolean	optional	`false`	When true, the command will also return a deleted ReportResult.
reportResult	ParamId	always		An object to contain the "id" of the ReportResult.
reportResult.id	uint64	always		Identifier given as input for the command.
reqId	int32?	optional		Identifier used by external system to correlate requests to responses.
summary	boolean	optional		When true, will also retrieve all the ReportSummarys (when used through an applicable REST service).

Request message structure

getReportResult {
	"breakdown": boolean,
	"includeDeleted": boolean,
	"reportResult": {
		"id": number
	},
	"reqId": number,
	"summary": boolean
}

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.
reportResult	ReportResult	The requested ReportResult.
reportResult.archive	boolean	Preserve these results for later review. Results are regularly culled from the system.
reportResult.bounds	LatLngBounds	After processing, the boundary of the results are given so that a map can be focused on that area.
reportResult.bounds.east	double	Eastern longitude
reportResult.bounds.north	double	Northern latitude
reportResult.bounds.south	double	Southern latitude
reportResult.bounds.west	double	Western longitude
reportResult.company	uint64 see: Company.id	The company to which this report belongs
reportResult.completed	datetime	The date/time this result was finished processing.
reportResult.created	datetime	The date/time this result was requested.
reportResult.error	string see: ReportStatus maximum-length: 250	A field which contains report error details if the ReportResult.status is ReportStatus.failed.
reportResult.filtered	Array.<uint64>	When the report runs, a list of filtered places is calculated based on the ReportOption's place filtering expression.
reportResult.id	uint64	Unique identifier
reportResult.name	string maximum-length: 100	Name of this report.
reportResult.notes	string	Notes about this report.
reportResult.options	ReportOptions	Specified parameters for the report logic, targeted Assets, and filtering Places.
reportResult.options.filtering	ReportFilterMode	The mechanism to use for filtering based on places and regions.
reportResult.options.parameters	Array.<ReportParameter>	A list of parameters to better shape the results.
reportResult.options.places	expression	A targeting expression for limiting results which only include data from Assets interacting with the targeted Places.
reportResult.options.regions	Array.<string>	A list of provinces and states, where only assets within those regions will be included in the results.
reportResult.options.scorecardRules	ReportScorecardRules	Rules used to generate scorecard for this report.
reportResult.options.scorecardRules.baseScore	double	Base score for the scorecard.
reportResult.options.scorecardRules.parameters	Array.<ReportScorecardParameter>	Infraction parameters used to generate the final score
reportResult.options.targets	expression	A targeting expression for including/excluding Assets.
reportResult.processedUtc	datetime	When the was change procesed.
reportResult.progress	byte	The progress in processing/saving this result is a number between 0 and 100.
reportResult.runBy	email see: User.login maximum-length: 254	The login of the user that ran this report.
reportResult.schedule	uint64? see: ReportSchedule.id	A reference to the schedule used to create this result. This field is optional as not all results are created on a schedule.
reportResult.scorecards	Array.<ReportScorecard>	Scorecards for all the targeted assets based on the scorecard rules.
reportResult.status	ReportStatus	The processing status of this report.
reportResult.targeted	Array.<uint64>	When the report runs, a list of targeted assets is calculated based on the ReportOption's targeting expression.
reportResult.template	uint64? see: ReportTemplate.id	A reference to the Template used to create this result. This field is optional because templates are not necessarily required; they just make life a lot easier.
reportResult.timezone	codified see: Timezone.code	The timezone code used to adjust dates/times used in processing and saving this report.
reportResult.totals	Array.<ReportTotal>	After processing, the report totals the values from all summary instances for a quick overview of the kind of results generated.
reportResult.type	ReportType	Refers to the type of logic used by this report.
reportResult.updated		by: login, from: monster
reportResult.v	Array.<uint32>	Object version keys used to validate synchronization for all object properties.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

getReportResultResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reportResult": {
		"archive": boolean,
		"bounds": {
			"east": number,
			"north": number,
			"south": number,
			"west": number
		},
		"company": number,
		"completed": string,
		"created": string,
		"error": string,
		"filtered": [
			number
		],
		"id": number,
		"name": string,
		"notes": string,
		"options": {
			"filtering": string,
			"parameters": [
				{
					"type": string,
					"value": string
				}
			],
			"places": string,
			"regions": [
				string
			],
			"scorecardRules": {
				"baseScore": number,
				"parameters": [
					{
						"condition": string,
						"duration": string,
						"points": number
					}
				]
			},
			"targets": string
		},
		"processedUtc": string,
		"progress": number,
		"runBy": string,
		"schedule": number,
		"scorecards": [
			{
				"asset": number,
				"rulePoints": {
					string: number
				},
				"score": number
			}
		],
		"status": string,
		"targeted": [
			number
		],
		"template": number,
		"timezone": string,
		"totals": [
			{
				"asset": number,
				"distance": number,
				"duration": string,
				"stateDetail": string,
				"summaryCount": number,
				"value": number,
				"valueType": string
			}
		],
		"type": string,
		"updated": {
		},
		"v": [
			number
		]
	},
	"reqId": number
}

Possible exceptions

Error Code	Description
2	A communication error occurred. If you receive this error, please contact technical support.
3	The request does not contain a reportResult object, or it is invalid.
3	The reportResult object does not contain an id, or it is invalid.
5	You do not have permission to view ReportResults.
5	You do not have permission to any of the Assets targetted by this ReportResult.
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 to which the ReportResult belongs was not found.
67	The ReportResult you are trying to retrieve was not found.
95	When trynig to get summary and/or breakdown, the ReportResult has not finished running.

getReportResultsList

Gets the list of ReportResult 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

getReportResultsList {
	"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 ReportResults belong.
company.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reportResults	Array.<ReportResult>	The list of requested ReportResults.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

getReportResultsListResponse {
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reportResults": [
		{
			"archive": boolean,
			"bounds": {
				"east": number,
				"north": number,
				"south": number,
				"west": number
			},
			"company": number,
			"completed": string,
			"created": string,
			"error": string,
			"filtered": [
				number
			],
			"id": number,
			"name": string,
			"notes": string,
			"options": {
				"filtering": string,
				"parameters": [
					{
						"type": string,
						"value": string
					}
				],
				"places": string,
				"regions": [
					string
				],
				"scorecardRules": {
					"baseScore": number,
					"parameters": [
						{
							"condition": string,
							"duration": string,
							"points": number
						}
					]
				},
				"targets": string
			},
			"processedUtc": string,
			"progress": number,
			"runBy": string,
			"schedule": number,
			"scorecards": [
				{
					"asset": number,
					"rulePoints": {
						string: number
					},
					"score": number
				}
			],
			"status": string,
			"targeted": [
				number
			],
			"template": number,
			"timezone": string,
			"totals": [
				{
					"asset": number,
					"distance": number,
					"duration": string,
					"stateDetail": string,
					"summaryCount": number,
					"value": number,
					"valueType": string
				}
			],
			"type": string,
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"reqId": number
}

Possible exceptions

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 ReportResult.
5	You do not have permission to any of the Assets in the 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 whose ReportResults you are trying to list was not found.

getReportResultsListByTemplate

Gets the list of ReportResult for the specified ReportTemplate.

Request message description

Property	Type	Required	Default	Description
after	datetime	optional
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.
reportTemplate	ParamId	always		An object to contain the "id" of the reportTemplate.
reportTemplate.id	uint64	always		Identifier given as input for the command.
reqId	int32?	optional		Identifier used by external system to correlate requests to responses.

Request message structure

getReportResultsListByTemplate {
	"after": string,
	"before": string,
	"includeArchive": boolean,
	"includeDeleted": boolean,
	"limit": number,
	"reportTemplate": {
		"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.
reportResults	Array.<ReportResult>	The list of requested ReportResults.
reportTemplate	RespIdCompany	An object to contain the "id" of the ReportTemplate to which the array of ReportResults belong.
reportTemplate.company	uint64	Identifier of the Company to which this object belongs.
reportTemplate.id	uint64?	Identifier given as input for the command.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

getReportResultsListByTemplateResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reportResults": [
		{
			"archive": boolean,
			"bounds": {
				"east": number,
				"north": number,
				"south": number,
				"west": number
			},
			"company": number,
			"completed": string,
			"created": string,
			"error": string,
			"filtered": [
				number
			],
			"id": number,
			"name": string,
			"notes": string,
			"options": {
				"filtering": string,
				"parameters": [
					{
						"type": string,
						"value": string
					}
				],
				"places": string,
				"regions": [
					string
				],
				"scorecardRules": {
					"baseScore": number,
					"parameters": [
						{
							"condition": string,
							"duration": string,
							"points": number
						}
					]
				},
				"targets": string
			},
			"processedUtc": string,
			"progress": number,
			"runBy": string,
			"schedule": number,
			"scorecards": [
				{
					"asset": number,
					"rulePoints": {
						string: number
					},
					"score": number
				}
			],
			"status": string,
			"targeted": [
				number
			],
			"template": number,
			"timezone": string,
			"totals": [
				{
					"asset": number,
					"distance": number,
					"duration": string,
					"stateDetail": string,
					"summaryCount": number,
					"value": number,
					"valueType": string
				}
			],
			"type": string,
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"reportTemplate": {
		"company": number,
		"id": number
	},
	"reqId": number
}

Possible exceptions

Error Code	Description
2	A communication error occurred. If you receive this error, please contact technical support.
3	The request does not contain a reportTemplate object, or it is invalid.
3	The reportTemplate object does not contain an id, or it is invalid.
5	You do not have permission to view ReportResults.
5	You do not have permission to any of the Assets in the 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 whose ReportResults you are trying to list was not found.
52	The ReportTemplate whose ReportResults you are trying to list was not found.

getReportSchedule

Gets details of the specified ReportSchedule.

Request message description

Property	Type	Required	Default	Description
includeDeleted	boolean	optional	`false`	When true, the command will also return a deleted ReportSchedule.
reportSchedule	ParamId	always		An object to contain the "id" of the ReportSchedule.
reportSchedule.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

getReportSchedule {
	"includeDeleted": boolean,
	"reportSchedule": {
		"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.
reportSchedule	ReportSchedule	The requested ReportSchedule.
reportSchedule.company	uint64 see: Company.id	The company to which this report belongs
reportSchedule.enabled	boolean	Indicates whether this schedule is allowed to run.
reportSchedule.id	uint64	Unique identifier
reportSchedule.name	string maximum-length: 100	Name of this report.
reportSchedule.notes	string	Notes about this report.
reportSchedule.notify	ReportNotifications	A list of users and a targeting expression for assets which receive report results notifications.
reportSchedule.notify.assets	expression	A targeting expression to identify which assets receive the report results. The results emailed to each asset will only be for themselves, not all assets. To receive the emailed results, the Asset must have a Asset.messagingAddress, or for a Person type asset, their Contact.emails["Email"].
reportSchedule.notify.users	Array.<email> for values see: UserGeneral.login maximum-length of values: 50	List of users to send emailed report. Each email will only contain the results for the assets each user is allowed to view.
reportSchedule.options	ReportOptions	Specified parameters for the report logic, targeted Assets, and filtering Places.
reportSchedule.options.filtering	ReportFilterMode	The mechanism to use for filtering based on places and regions.
reportSchedule.options.parameters	Array.<ReportParameter>	A list of parameters to better shape the results.
reportSchedule.options.places	expression	A targeting expression for limiting results which only include data from Assets interacting with the targeted Places.
reportSchedule.options.regions	Array.<string>	A list of provinces and states, where only assets within those regions will be included in the results.
reportSchedule.options.scorecardRules	ReportScorecardRules	Rules used to generate scorecard for this report.
reportSchedule.options.scorecardRules.baseScore	double	Base score for the scorecard.
reportSchedule.options.scorecardRules.parameters	Array.<ReportScorecardParameter>	Infraction parameters used to generate the final score
reportSchedule.options.targets	expression	A targeting expression for including/excluding Assets.
reportSchedule.owner	email see: User.login maximum-length: 254	Login of the user who has ownership of this report schedule.
reportSchedule.processedUtc	datetime	When the was change procesed.
reportSchedule.repetition	ReportRecurrence	The recurring schedule to generate report results.
reportSchedule.repetition.end	datetime	The optional time when the schedule stops recurring in local-time (not UTC).
reportSchedule.repetition.iterations	uint16	The number of times this schedule has been invoked to generate results.
reportSchedule.repetition.kind	ReportRecurrenceType	How often the report is automatically run. Daily, weekly, monthly, etc...
reportSchedule.repetition.lastEndDate	datetime	The date/time stamp from the last result used to inform the nextStartDate and nextEndDate properties. This value is null when the schedule has not yet run once.
reportSchedule.repetition.lastResult	uint64?	The unique identifier of the last ReportResult generated by this schedule.
reportSchedule.repetition.lastStartDate	datetime	The date/time stamp from the last result used to inform the nextStartDate and nextEndDate properties. This value is null when the schedule has not yet run once.
reportSchedule.repetition.nextEndDate	datetime	This date/time is used as the endDate ReportParameter for the next iteration of this recurring report. This value is null when the schedule is calculated to stop recurring.
reportSchedule.repetition.nextStartDate	datetime	This date/time is used as the startDate ReportParameter for the next iteration of this recurring report. This value is null when the schedule is calculated to stop recurring.
reportSchedule.repetition.start	datetime	When the schedule is to begin recurring in local-time (not UTC).
reportSchedule.repetition.timezone Deprecated	codified see: Timezone.code	The local timezone used to calculate recurring date/time ranges. Use owner.timezone instead.
reportSchedule.repetition.weekday	byte	Used only for weekly schedules, it's a number between 0 and 6 representing the day of the week, with Sunday being the first day of the week.
reportSchedule.repetition.weekdays	Array.<boolean> fixed count: 7	Used only for daily schedules, this 7 item, boolean array, determines if the schedule should recur on that day of the week.
reportSchedule.template	uint64 see: ReportTemplate.id	A reference to the Template used to create this result.
reportSchedule.updated		by: login, from: monster
reportSchedule.v	Array.<uint32>	Object version keys used to validate synchronization for all object properties.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

getReportScheduleResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reportSchedule": {
		"company": number,
		"enabled": boolean,
		"id": number,
		"name": string,
		"notes": string,
		"notify": {
			"assets": string,
			"users": [
				string
			]
		},
		"options": {
			"filtering": string,
			"parameters": [
				{
					"type": string,
					"value": string
				}
			],
			"places": string,
			"regions": [
				string
			],
			"scorecardRules": {
				"baseScore": number,
				"parameters": [
					{
						"condition": string,
						"duration": string,
						"points": number
					}
				]
			},
			"targets": string
		},
		"owner": string,
		"processedUtc": string,
		"repetition": {
			"end": string,
			"iterations": number,
			"kind": string,
			"lastEndDate": string,
			"lastResult": number,
			"lastStartDate": string,
			"nextEndDate": string,
			"nextStartDate": string,
			"start": string,
			"timezone": string,
			"weekday": number,
			"weekdays": [
				boolean
			]
		},
		"template": number,
		"updated": {
		},
		"v": [
			number
		]
	},
	"reqId": number
}

Possible exceptions

Error Code	Description
3	The request does not contain a reportSchedule object, or it is invalid.
3	The reportSchedule object does not contain an id, or it is invalid.
5	You do not have permission to view ReportSchedules.
5	You do not have permission to any of the Assets targetted by this ReportSchedule (or ReportTemplate).
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 to which the report belongs was not found.
52	The ReportTemplate to which the ReportSchedule refers was not found.
93	The ReportSchedule you are trying to retrieve was not found.

getReportSchedulesList

Gets the list of ReportSchedules for the specified Company.

Request message description

Property	Type	Required	Default	Description
company	ParamId	always
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

getReportSchedulesList {
	"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 which contains only one key "id" when there is no error. The "id" key is the unique identifier of the company to which the array of objects relate.
company.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reportSchedules	Array.<ReportSchedule>	The list of schedules.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

getReportSchedulesListResponse {
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reportSchedules": [
		{
			"company": number,
			"enabled": boolean,
			"id": number,
			"name": string,
			"notes": string,
			"notify": {
				"assets": string,
				"users": [
					string
				]
			},
			"options": {
				"filtering": string,
				"parameters": [
					{
						"type": string,
						"value": string
					}
				],
				"places": string,
				"regions": [
					string
				],
				"scorecardRules": {
					"baseScore": number,
					"parameters": [
						{
							"condition": string,
							"duration": string,
							"points": number
						}
					]
				},
				"targets": string
			},
			"owner": string,
			"processedUtc": string,
			"repetition": {
				"end": string,
				"iterations": number,
				"kind": string,
				"lastEndDate": string,
				"lastResult": number,
				"lastStartDate": string,
				"nextEndDate": string,
				"nextStartDate": string,
				"start": string,
				"timezone": string,
				"weekday": number,
				"weekdays": [
					boolean
				]
			},
			"template": number,
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"reqId": number
}

Possible exceptions

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 ReportSchedules.
5	You do not have permission to view Asset history.
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 whose ReportSchedules you are trying to list was not found.

getReportSchedulesListByTemplate

Gets the list of ReportSchedules for the specified ReportTemplate.

Request message description

Property	Type	Required	Default	Description
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
reportTemplate	ParamId	always
reportTemplate.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

getReportSchedulesListByTemplate {
	"highest": number,
	"includeArchive": boolean,
	"includeDeleted": boolean,
	"limit": number,
	"lowest": number,
	"reportTemplate": {
		"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.
reportSchedules	Array.<ReportSchedule>	The list of schedules.
reportTemplate	RespIdCompany	An object which contains only one key "id" when there is no error. The "id" key is the unique identifier of the company to which the array of objects relate.
reportTemplate.company	uint64	Identifier of the Company to which this object belongs.
reportTemplate.id	uint64?	Identifier given as input for the command.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

getReportSchedulesListByTemplateResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reportSchedules": [
		{
			"company": number,
			"enabled": boolean,
			"id": number,
			"name": string,
			"notes": string,
			"notify": {
				"assets": string,
				"users": [
					string
				]
			},
			"options": {
				"filtering": string,
				"parameters": [
					{
						"type": string,
						"value": string
					}
				],
				"places": string,
				"regions": [
					string
				],
				"scorecardRules": {
					"baseScore": number,
					"parameters": [
						{
							"condition": string,
							"duration": string,
							"points": number
						}
					]
				},
				"targets": string
			},
			"owner": string,
			"processedUtc": string,
			"repetition": {
				"end": string,
				"iterations": number,
				"kind": string,
				"lastEndDate": string,
				"lastResult": number,
				"lastStartDate": string,
				"nextEndDate": string,
				"nextStartDate": string,
				"start": string,
				"timezone": string,
				"weekday": number,
				"weekdays": [
					boolean
				]
			},
			"template": number,
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"reportTemplate": {
		"company": number,
		"id": number
	},
	"reqId": number
}

Possible exceptions

Error Code	Description
3	The request does not contain a reportTemplate object, or it is invalid.
3	The reportTemplate object does not contain an id, or it is invalid.
5	You do not have permission to view ReportTemplates.
5	You do not have permission to view ReportSchedules.
5	You do not have permission to view Asset history.
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 whose ReportSchedules you are trying to list was not found.
52	The ReportTemplate whose ReportSchedules you are trying to list was not found.

getReportTemplate

Gets details of the specified ReportTemplate.

Request message description

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

Request message structure

getReportTemplate {
	"includeDeleted": boolean,
	"reportTemplate": {
		"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.
reportTemplate	ReportTemplate	The requested ReportTemplate.
reportTemplate.company	uint64 see: Company.id	The company to which this report belongs
reportTemplate.fill	colour maximum-length: 22	The fill/background colour of the icon.
reportTemplate.graphic	codified maximum-length: 22	The name of the symbol for this report.
reportTemplate.id	uint64	Unique identifier
reportTemplate.name	string maximum-length: 100	Name of this report.
reportTemplate.notes	string	Notes about this report.
reportTemplate.options	ReportOptions	Specified parameters for the report logic, targeted Assets, and filtering Places.
reportTemplate.options.filtering	ReportFilterMode	The mechanism to use for filtering based on places and regions.
reportTemplate.options.parameters	Array.<ReportParameter>	A list of parameters to better shape the results.
reportTemplate.options.places	expression	A targeting expression for limiting results which only include data from Assets interacting with the targeted Places.
reportTemplate.options.regions	Array.<string>	A list of provinces and states, where only assets within those regions will be included in the results.
reportTemplate.options.scorecardRules	ReportScorecardRules	Rules used to generate scorecard for this report.
reportTemplate.options.scorecardRules.baseScore	double	Base score for the scorecard.
reportTemplate.options.scorecardRules.parameters	Array.<ReportScorecardParameter>	Infraction parameters used to generate the final score
reportTemplate.options.targets	expression	A targeting expression for including/excluding Assets.
reportTemplate.processedUtc	datetime	When the was change procesed.
reportTemplate.stroke	colour maximum-length: 22	Outline and graphic colour.
reportTemplate.type	ReportType	Refers to the type of logic used by this report.
reportTemplate.updated		by: login, from: monster
reportTemplate.v	Array.<uint32>	Object version keys used to validate synchronization for all object properties.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

getReportTemplateResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reportTemplate": {
		"company": number,
		"fill": string,
		"graphic": string,
		"id": number,
		"name": string,
		"notes": string,
		"options": {
			"filtering": string,
			"parameters": [
				{
					"type": string,
					"value": string
				}
			],
			"places": string,
			"regions": [
				string
			],
			"scorecardRules": {
				"baseScore": number,
				"parameters": [
					{
						"condition": string,
						"duration": string,
						"points": number
					}
				]
			},
			"targets": string
		},
		"processedUtc": string,
		"stroke": string,
		"type": string,
		"updated": {
		},
		"v": [
			number
		]
	},
	"reqId": number
}

Possible exceptions

Error Code	Description
3	The request does not contain a reportTemplate object, or it is invalid.
3	The reportTemplate object does not contain an id, or it is invalid.
5	You do not have permission to view ReportTemplates.
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.
52	The ReportTemplate you are trying to retrieve was not found.

getReportTemplatesList

Gets the list of ReportTemplate 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

getReportTemplatesList {
	"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 ReportTemplates belong.
company.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reportTemplates	Array.<ReportTemplate>	The list of requested ReportTemplates.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

getReportTemplatesListResponse {
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reportTemplates": [
		{
			"company": number,
			"fill": string,
			"graphic": string,
			"id": number,
			"name": string,
			"notes": string,
			"options": {
				"filtering": string,
				"parameters": [
					{
						"type": string,
						"value": string
					}
				],
				"places": string,
				"regions": [
					string
				],
				"scorecardRules": {
					"baseScore": number,
					"parameters": [
						{
							"condition": string,
							"duration": string,
							"points": number
						}
					]
				},
				"targets": string
			},
			"processedUtc": string,
			"stroke": string,
			"type": string,
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"reqId": number
}

Possible exceptions

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 ReportTemplates.
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.

mergeReportResult

Creates a new ReportResult that will run automatically, or updates an existing ReportResult.

Request message description

Property	Type	Required	Description
reportResult	Object.<string, ?>	always	A simple object to contain the ReportResult parameters.
reportResult.archive	boolean	optional	Indicates whether this report should be archived. Archived report ReportResult are stored for six months. Non-archive reports are purged after 24 hours.
reportResult.company	uint64?	create (complex)	The Company to which these report ReportResult belongs.
reportResult.id	uint64?	update	The unique identifier of the ReportResult you want to update.
reportResult.name	string maximum-length: 100	create	Name for the report ReportResult.
reportResult.notes	string	optional	Notes for these report ReportResult.
reportResult.options	Object.<string, ?>	create (complex)	Specified parameters for the report logic, targeted Assets, and filtering Places and/or regions.
reportResult.options.filtering	ReportFilterMode?	optional	The mechanism to use for filtering based on Places and regions.
reportResult.options.parameters	Array.<ReportParameter>	optional	A list of parameters to better shape the ReportResult.
reportResult.options.places	expression	optional	A targeting expression for limiting results which only include data from Assets interacting with the targeted Places.
reportResult.options.regions	Array.<string>	optional	A list of provinces and states, where only Assets within those regions will be included in the ReportResult.
reportResult.options.scorecardRules	Object.<string, ?>	always	Rules used to generate ReportScorecard for the ReportResult.
reportResult.options.scorecardRules.baseScore	double	optional	Base score for the ReportScorecard.
reportResult.options.scorecardRules.parameters	Array.<ReportScorecardParameter>	optional	Infraction parameters used to generate the final ReportScorecard.score.
reportResult.options.targets	expression	optional	A targeting expression for including/excluding Assets.
reportResult.template	uint64?	create (simple)	Identifier of the ReportTemplate used to help create these ReportResult.
reportResult.timezone	codified see: Timezone.code	create	The Timezone.code of the local timezone used to calculate times.
reportResult.type	ReportType?	create (complex)	The kind of logic used to build the report ReportResult.
reportResult.v	Array.<int32>	optional
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

Request message structure

mergeReportResult {
	"reportResult": {
		"archive": boolean,
		"company": number,
		"id": number,
		"name": string,
		"notes": string,
		"options": {
			"filtering": string,
			"parameters": [
				{
					"type": string,
					"value": string
				}
			],
			"places": string,
			"regions": [
				string
			],
			"scorecardRules": {
				"baseScore": number,
				"parameters": [
					{
						"condition": string,
						"duration": string,
						"points": number
					}
				]
			},
			"targets": string
		},
		"template": number,
		"timezone": string,
		"type": string,
		"v": [
			number
		]
	},
	"reqId": number
}

Response 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.
reportResult	RespIdCompanyTemplate	An object which contains the "id", "company", and "template" keys.
reportResult.company	uint64	Identifier of the Company to which this object belongs.
reportResult.id	uint64?	Identifier given as input for the command.
reportResult.template	uint64?	Identifier of the ReportTemplate the report object implements.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

mergeReportResultResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reportResult": {
		"company": number,
		"id": number,
		"template": number
	},
	"reqId": number
}

Possible exceptions

Error Code	Description
2	A communication error occurred. If you receive this error, please contact technical support.
2	During update: When updating a ReportResult, you cannot change options after ReportResult begins running. If you receive this error, please contact technical support.
2	During update: When updating a ReportResult, you cannot change timezone after ReportResult begins running. If you receive this error, please contact technical support.
3	The request does not contain a reportResult object, or it is invalid.
3	No valid changes would be performed.
3	During create: When creating a new ReportResult, a timezone was not given.
3	During create: When creating a new ReportResult, a company or template was not given.
3	During create: When creating a new ReportResult, a type or template was not given.
3	During create: When creating a new ReportResult, a name or template was not given.
3	During create: When creating a new ReportResult, the options or template was not given.
3	During create: When creating a new ReportResult, given template does not match the given company.
3	During update: When updating a ReportResult, the v was not an array, or contained too few numbers.
3	During update: When updating a ReportResult, the name was given as null or blank.
5	There are no targeted assets, so the report would not run.
5	During create: You do not have permission to create new ReportResult.
5	During update: You do not have permission to update ReportResult.
6	During update: When updating a ReportResult, 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	The Company being targetted is not found.
52	During create: When creating a new ReportResult, the given ReportTemplate was not found.
67	During update: The ReportResult you are trying to update was not found.
130	During create: When creating a new ReportResult, and no reportResult.options.targets are given, and the ReportTemplate also has no targets.
130	During create: The specified reportResult.company was found, but was not in the same Company as the given ReportTemplate.
130	During update: When updating a ReportResult, the reportResult.company can not be changed.

mergeReportSchedule

Creates a new, or updates an existing ReportSchedule.

Request message description

Property	Type	Required	Description
reportSchedule	Object.<string, ?>	always	A simple object to contain the ReportSchedule parameters.
reportSchedule.enabled	boolean	optional	Indicates whether this schedule is allowed to run.
reportSchedule.id	uint64?	update	The unique identifier of the ReportSchedule you want to update.
reportSchedule.name	string maximum-length: 100	create	Name for the ReportSchedule.
reportSchedule.notes	string	optional	Notes for the ReportSchedule.
reportSchedule.notify	Object.<string, ?>	always	A list of users and a targeting expression for Assets which receive report results notifications.
reportSchedule.notify.assets	expression maximum-length: 255	optional	A targeting expression to identify which Assets receive the ReportResult.
reportSchedule.notify.users	Array.<email> maximum-count: 50	optional	List of Users to send emailed report. Each email will only contain the ReportResult for the Assets each User is allowed to view.
reportSchedule.options	Object.<string, ?>	always	Specified parameters for the report logic, targeted Assets, and filtering Places.
reportSchedule.options.filtering	ReportFilterMode?	optional	The mechanism to use for filtering based on Places and regions.
reportSchedule.options.parameters	Array.<ReportParameter>	optional	A list of parameters to better shape the ReportResult.
reportSchedule.options.places	expression	optional	A targeting expression for limiting results which only include data from Assets interacting with the targeted Places.
reportSchedule.options.regions	Array.<string>	optional	A list of provinces and states, where only Assets within those regions will be included in the ReportResult.
reportSchedule.options.scorecardRules	Object.<string, ?>	always	Rules used to generate ReportScorecard for the ReportResult.
reportSchedule.options.scorecardRules.baseScore	double	optional	Base score for the ReportScorecard.
reportSchedule.options.scorecardRules.parameters	Array.<ReportScorecardParameter>	optional	Infraction parameters used to generate the final ReportScorecard.score.
reportSchedule.options.targets	expression	optional	A targeting expression for including/excluding Assets.
reportSchedule.owner	email	create	The user which owns the schedule. When report results are created, they will be created with this user's Asset permissions.
reportSchedule.repetition	Object.<string, ?>	create	The recurring schedule to generate report results.
reportSchedule.repetition.end	datetime	optional	The optional time when the ReportSchedule stops recurring in local-time (not UTC).
reportSchedule.repetition.kind	ReportRecurrenceType?	optional	How often the report is automatically run. Daily, weekly, monthly, etc...
reportSchedule.repetition.start	datetime	optional	When the ReportSchedule is to begin recurring in local-time (not UTC).
reportSchedule.repetition.weekday	byte?	optional	Used only for weekly schedules, it's a number between 0 and 6 representing the day of the week, with Sunday being the first day of the week.
reportSchedule.repetition.weekdays	Array.<boolean>	optional	Used only for daily schedules, this 7 item, boolean array, determines if the ReportSchedule should recur on that day of the week.
reportSchedule.template	uint64?	create	Identifier of the ReportTemplate used to help create results.
reportSchedule.v	Array.<int32>	optional
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

Request message structure

mergeReportSchedule {
	"reportSchedule": {
		"enabled": boolean,
		"id": number,
		"name": string,
		"notes": string,
		"notify": {
			"assets": string,
			"users": [
				string
			]
		},
		"options": {
			"filtering": string,
			"parameters": [
				{
					"type": string,
					"value": string
				}
			],
			"places": string,
			"regions": [
				string
			],
			"scorecardRules": {
				"baseScore": number,
				"parameters": [
					{
						"condition": string,
						"duration": string,
						"points": number
					}
				]
			},
			"targets": string
		},
		"owner": string,
		"repetition": {
			"end": string,
			"kind": string,
			"start": string,
			"weekday": number,
			"weekdays": [
				boolean
			]
		},
		"template": number,
		"v": [
			number
		]
	},
	"reqId": number
}

Response 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.
reportSchedule	RespIdCompanyTemplate	An object which contains the "id", "company", and "template" keys.
reportSchedule.company	uint64	Identifier of the Company to which this object belongs.
reportSchedule.id	uint64?	Identifier given as input for the command.
reportSchedule.template	uint64?	Identifier of the ReportTemplate the report object implements.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

mergeReportScheduleResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reportSchedule": {
		"company": number,
		"id": number,
		"template": 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 reportSchedule object, or it is invalid.
3	No valid changes would be performed.
3	The reportSchedule.owner value is not a valid email address or SelfMachine.key.
3	The reportSchedule.repetition.kind is not a valid value.
3	The reportSchedule.repetition.weekdays is not a valid value.
3	The reportSchedule.repetition.weekday is not a valid value.
3	One or more of the reportSchedule.options.parameters was not a valid.
3	One or more of the reportSchedule.options parameters' type was not a valid.
3	One or more of the reportSchedule.options.scorecardRules.parameters was not a valid.
3	One or more of the reportSchedule.options.scorecardRules.parameters' ReportScorecardParameter.conditions was not a valid.
3	One or more of the reportSchedule.options.scorecardRules.parameters' ReportScorecardParameter.durations was not a valid.
3	One or more of the reportSchedule.options.scorecardRules.parameters' ReportScorecardParameter.points was not a valid.
3	During create: When creating a new ReportSchedule, a template was not given.
3	During create: When creating a new ReportSchedule, a name or template was not given.
3	During create: When creating a new ReportSchedule, the given repetition pattern parameters were incomplete.
3	During update: When updating a ReportSchedule, the v was not an array, or contained too few numbers.
3	During update: When updating a ReportSchedule, the name was given as null or blank.
3	The options filtering specified was not a valid. Returns an ErrorDetailEnum as the `errorDetails`.
3	One or more of the options parameters type was specified more than once. Returns an ErrorDetailInput 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.
16	You cannot execute this command because your password has expired.
54	During update: When updating the ReportSchedule.owner, and it is a User, and cannot be found.
54	During update: When updating the ReportSchedule.repetition, and the ReportSchedule.owner is a User, and cannot be found.
127	During update: When updating the ReportSchedule.owner, and it is a Machine, and cannot be found.
127	During update: When updating the ReportSchedule.repetition, and the ReportSchedule.owner is a Machine, and cannot be found.
130	During update: When updating a ReportSchedule, the reportSchedule.template can not be changed.

mergeReportTemplate

Creates a new or, updates an existing ReportTemplate.

Request message description

Property	Type	Required	Description
reportTemplate	Object.<string, ?>	always	A simple object to contain the ReportTemplate parameters.
reportTemplate.company	uint64?	create	The Company to which this ReportTemplate belongs.
reportTemplate.fill	string	optional	Background and fill colour in the UI.
reportTemplate.graphic	string	optional	The name of the symbol shown in the UI.
reportTemplate.id	uint64?	update	The unique identifier of the ReportTemplate you want to update.
reportTemplate.name	string maximum-length: 100	create	Name for the ReportTemplate.
reportTemplate.notes	string	optional	Notes about the ReportTemplate.
reportTemplate.options	Object.<string, ?>	always	Specified parameters for the report logic, targeted Assets, and filtering Places and/or regions.
reportTemplate.options.filtering	ReportFilterMode?	optional	The mechanism to use for filtering based on Places and regions.
reportTemplate.options.parameters	Array.<ReportParameter>	optional	A list of parameters to better shape the ReportResult.
reportTemplate.options.places	expression	optional	A targeting expression for limiting results which only include data from Assets interacting with the targeted Places.
reportTemplate.options.regions	Array.<string>	optional	A list of provinces and states, where only Assets within those regions will be included in the ReportResult.
reportTemplate.options.scorecardRules	Object.<string, ?>	always	Rules used to generate ReportScorecard for the ReportResult.
reportTemplate.options.scorecardRules.baseScore	double	optional	Base score for the ReportScorecard.
reportTemplate.options.scorecardRules.parameters	Array.<ReportScorecardParameter>	optional	Infraction parameters used to generate the final ReportScorecard.score.
reportTemplate.options.targets	expression	optional	A targeting expression for including/excluding Assets.
reportTemplate.stroke	string	optional	Text and outline colour in the UI.
reportTemplate.type	ReportType?	create	The kind of logic used to build the report results.
reportTemplate.v	Array.<int32>	optional
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

Request message structure

mergeReportTemplate {
	"reportTemplate": {
		"company": number,
		"fill": string,
		"graphic": string,
		"id": number,
		"name": string,
		"notes": string,
		"options": {
			"filtering": string,
			"parameters": [
				{
					"type": string,
					"value": string
				}
			],
			"places": string,
			"regions": [
				string
			],
			"scorecardRules": {
				"baseScore": number,
				"parameters": [
					{
						"condition": string,
						"duration": string,
						"points": number
					}
				]
			},
			"targets": string
		},
		"stroke": string,
		"type": string,
		"v": [
			number
		]
	},
	"reqId": number
}

Response 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.
reportTemplate	RespIdCompany	An object which contains the "id" and "company" keys when there is no error.
reportTemplate.company	uint64	Identifier of the Company to which this object belongs.
reportTemplate.id	uint64?	Identifier given as input for the command.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

mergeReportTemplateResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reportTemplate": {
		"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.
3	The request does not contain a reportTemplate object, or it is invalid.
3	Not enough keys exist in the reportTemplate object.
3	During create: When creating a new ReportTemplate, the name was given, but is blank or null.
3	During create: When creating a new ReportTemplate, a company was not given.
3	During create: When creating a new ReportTemplate, the type was not given.
3	During create: When creating a new ReportTemplate, the type was given, but is invalid.
3	During update: When updating a ReportTemplate, the id was invalid.
3	During update: When updating a ReportTemplate, the v was not an array, or contained too few numbers.
5	You do not have permission to either create a new ReportTemplate.
5	You do not have permission to either update ReportTemplates.
6	During update: When updating a ReportTemplate, 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.
52	During update: The ReportTemplate you are trying to update was not found.
130	During update: When updating a ReportTemplate, the reportTemplate.company can not be changed.
130	During update: When updating a ReportTemplate, the reportTemplate.type can not be changed.

removeReportResult

Deletes the specified ReportResult.

Request message description

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

Request message structure

removeReportResult {
	"reportResult": {
		"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.
reportResult	RespDeleted	An object which contains the ReportResult's id, owning Company id, and deleted status.
reportResult.company	uint64	Identifier of the Company to which this object belongs.
reportResult.deleted	boolean	Flag showing if the object is deleted.
reportResult.id	uint64?	Identifier given as input for the command.
reportResult.v	Array.<uint32>
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

removeReportResultResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reportResult": {
		"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 reportResult object, or it is invalid.
3	The reportResult object does not contain an id, or it is invalid.
5	You do not have permission to delete ReportResults.
5	You do not have permission to view all of the Assets targetted by this ReportResult.
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 to which the ReportResult belongs was not found.
67	The ReportResult you are trying to delete was not found.

removeReportSchedule

Deletes the specified ReportSchedule.

Request message description

Property	Type	Required	Description
reportSchedule	ParamId	always	An object to contain the "id" of the ReportSchedule.
reportSchedule.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

removeReportSchedule {
	"reportSchedule": {
		"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.
reportSchedule	RespDeleted	An object which contains the ReportSchedule's id, owning Company id, and deleted status.
reportSchedule.company	uint64	Identifier of the Company to which this object belongs.
reportSchedule.deleted	boolean	Flag showing if the object is deleted.
reportSchedule.id	uint64?	Identifier given as input for the command.
reportSchedule.v	Array.<uint32>
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

removeReportScheduleResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reportSchedule": {
		"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 reportSchedule object, or it is invalid.
3	The reportSchedule object does not contain an id, or it is invalid.
5	You do not have permission to view ReportSchedules.
5	You do not have permission to all of the Assets targetted by this ReportSchedule (or ReportTemplate).
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 to which the ReportSchedule belongs was not found.
52	The ReportTemplate to which the ReportSchedule refers was not found.
93	The ReportSchedule you are trying to retrieve was not found.

removeReportTemplate

Removes the specified ReportTemplate.

Request message description

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

Request message structure

removeReportTemplate {
	"reportTemplate": {
		"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.
reportTemplate	RespDeleted	An object which contains the ReportTemplate's id, owning Company id, and deleted status.
reportTemplate.company	uint64	Identifier of the Company to which this object belongs.
reportTemplate.deleted	boolean	Flag showing if the object is deleted.
reportTemplate.id	uint64?	Identifier given as input for the command.
reportTemplate.v	Array.<uint32>
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

removeReportTemplateResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reportTemplate": {
		"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 reportTemplate object, or it is invalid.
3	The reportTemplate object does not contain an id, or it is invalid.
5	You do not have permission to delete ReportTemplates.
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.
52	The ReportTemplate you are trying to delete was not found.

restoreReportResult

Restores a deleted ReportResult.

Request message description

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

Request message structure

restoreReportResult {
	"reportResult": {
		"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.
reportResult	RespDeleted	An object which contains the ReportResult's id, owning Company id, and deleted status.
reportResult.company	uint64	Identifier of the Company to which this object belongs.
reportResult.deleted	boolean	Flag showing if the object is deleted.
reportResult.id	uint64?	Identifier given as input for the command.
reportResult.v	Array.<uint32>
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

restoreReportResultResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reportResult": {
		"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 reportResult object, or it is invalid.
3	The reportResult object does not contain an id, or it is invalid.
5	You do not have permission to restore ReportResults.
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.
67	The ReportResult you are trying to restore was not found.
75	The ReportResult you are trying to restore is not deleted.

restoreReportSchedule

Restores a deleted ReportSchedule.

Request message description

Property	Type	Required	Description
reportSchedule	ParamId	always	An object to contain the "id" of the ReportSchedule.
reportSchedule.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

restoreReportSchedule {
	"reportSchedule": {
		"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.
reportSchedule	RespDeleted	An object which contains the ReportSchedule's id, owning Company id, and deleted status.
reportSchedule.company	uint64	Identifier of the Company to which this object belongs.
reportSchedule.deleted	boolean	Flag showing if the object is deleted.
reportSchedule.id	uint64?	Identifier given as input for the command.
reportSchedule.v	Array.<uint32>
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

restoreReportScheduleResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reportSchedule": {
		"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 reportSchedule object, or it is invalid.
3	The reportSchedule object does not contain an id, or it is invalid.
5	You do not have permission to restore ReportSchedules.
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.
93	The ReportSchedule you are trying to restore was not found.
94	The ReportSchedule you are trying to restore is not deleted.

restoreReportTemplate

Restores a deleted ReportTemplate to its previous version.

Request message description

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

Request message structure

restoreReportTemplate {
	"reportTemplate": {
		"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.
reportTemplate	RespDeleted	An object which contains the ReportTemplate's id, owning Company id, and deleted status.
reportTemplate.company	uint64	Identifier of the Company to which this object belongs.
reportTemplate.deleted	boolean	Flag showing if the object is deleted.
reportTemplate.id	uint64?	Identifier given as input for the command.
reportTemplate.v	Array.<uint32>
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

restoreReportTemplateResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reportTemplate": {
		"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 reportTemplate object, or it is invalid.
3	The reportTemplate object does not contain an id, or it is invalid.
5	You do not have permission to delete ReportTemplates.
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.
52	The ReportTemplate you are trying to restore was not found.
53	The ReportTemplate you are trying to restore was not found, but is not deleted.

Self

getSessionDetails

Gets details of the current session (yourself) and User.

Request message description

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

Request message structure

getSessionDetails {
	"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.
expiry	datetime	The timestamp of when this session expires.
ghostId	string	Your session identifier.
machine	SelfMachine	This Machine's details (if the service is being used by a Machine). If this value is not present, then the session is not a machine account.
machine.company	uint64 see: Company.id	The company to which this user belongs.
machine.enabled	boolean	Indicates whether system access is disable.
machine.formats	Object.<codified, datetimetemplate> maximum-length of values: 20	The format strings defining the preferred way to display ambiguous values.
machine.groups	Array.<UserGroup>	The list of UserGroup to which this User belongs.
machine.insecure	boolean	When true, no access restrictions (machine.secret, machine.referrers, or machine.ipRanges) are enforced.
machine.ipRanges	Array.<ipv4> maximum-length of values: 19	Restrict service access to only the provided IP ranges. Currently we only support IPv4 ranges using CIDR slash-notation.
machine.key	string maximum-length: 50	The unique idenifier used to access the system.
machine.language	codified maximum-length: 5 minimum-length: 2	Preferred region/language for the UI and notifications. Valid formats use <ISO 639-1><dash><ISO 3166-2> such as "fr-CA" or "en-US".
machine.measurements	Object.<codified, SystemsOfUnits>	Preferred way of displaying ambiguous numbers in the context of measurements.
machine.nickname	string maximum-length: 100	Human friendly name for these credentials
machine.notAfter	datetime	An optional timestamp that restricts this machine account from being used after the given date.
machine.notBefore	datetime	An optional timestamp that restricts this machine account from being used before the given date.
machine.notes	string maximum-length: 8000	Notes about this machine.
machine.options	Object.<codified, string> maximum-length of values: 20	Additional options which do not fit in with the formats or measurements preferences.
machine.permissions	Array.<Permission>	Permission rules which override the group rules.
machine.processedUtc	datetime	When the was change procesed.
machine.referrers	Array.<url> maximum-length of values: 254	Optional list of your managed domains from which this machine account can be used.
machine.secret	string maximum-length: 1000	A token used to encode or validate requests.
machine.services	Array.<url> maximum-length of values: 254	List of system service URIs that this machine account is permitted to access.
machine.timezone	codified see: Timezone.code	The service account's local timezone.
machine.updated		by: login, from: monster
machine.v	Array.<uint32>
message	string	An English description of the error.
passwordPolicy	PasswordPolicy	This User's Company.passwordPolicy.
passwordPolicy.expireMode	PasswordExpiryMode	Defines how passwords expire.
passwordPolicy.expireThreshold	byte	The threshold for expiry.
passwordPolicy.includeLetters	boolean	Do passwords require alphabetical characters.
passwordPolicy.includeNumbers	boolean	Do passwords require numeric characters.
passwordPolicy.includeSpecial	boolean	Do passwords require non-alphanumeric characters.
passwordPolicy.includeUpperLower	boolean	Do passwords require upper-case and lower-case letters.
passwordPolicy.minimumLength	byte	The minimum number of characters required.
reqId	int32?	Identifier used by external system to correlate requests to responses.
serverTime	datetime	The UTC date/time of the server hosting the connection.
sessionPolicy	SessionPolicy	This User's Company.sessionPolicy.
sessionPolicy.applications	Array.<string>	The list of applications users are allowed to use to create sessions.
sessionPolicy.expireTimeout	uint16	The lifetime duration of a session in minutes.
sessionPolicy.idleAllowed	boolean	Defines whether a session should be automatically killed when the connection breaks.
sessionPolicy.ipv4Ranges	Array.<ipv4> maximum-length of values: 19	Restrict session creation to only the provided IPv4 ranges (using CIDR slash-notation). Leave blank for Internet access.
sessionPolicy.maxSessions	byte	The maximum number of sessions allowed per user.
sessionPolicy.multiUser	SessionMultiUser	Defines the behaviour of the system when a user creates multiple sessions.
user	SelfUser	This session's User details (if the service is being used by a User). If this value is not present, then the session is not yet authenticated.
user.company	uint64 see: Company.id	The company to which this user belongs.
user.contact	Contact	Associated contact information for this user.
user.contact.addresses	Object.<string, string>	Mailing addresses. Use the object key like a name of the address. Example keys: Home, Work, Park, etc.
user.contact.company	uint64 see: Company.id	The company to which this contact belongs
user.contact.dates	Object.<string, datetime>	Date information. Use the object key like a name of the date. Example keys: Birthday, Started Date, Retired On, etc.
user.contact.emails	Object.<string, email> maximum-length of values: 254	Email addresses. Use the object key like a name of the address. Example keys: Home, Work, Support, Old, etc.
user.contact.id	uint64	Unique identifier of this contact.
user.contact.name	string maximum-length: 100	The person's name
user.contact.notes	string	Notes about this person.
user.contact.options	Object.<string, string>	Uncategorized information. Use the object keys and values however you'd like.
user.contact.otherNames	Object.<string, string> maximum-length of values: 254	A collection of other names this person might go by. Use the object key like a name identifier. Example keys: Initials, Nickname, Maiden Name, etc.
user.contact.phones	Object.<string, phone>	Phone numbers. Use the object key like a name of the phone number. Example keys: Mobile, Fax, Home, Office, etc.
user.contact.pictures	Array.<uint64> for values see: Picture.id	Pictures of this Contact.
user.contact.processedUtc	datetime	When the was change procesed.
user.contact.roles	Array.<string>	A list of roles they play in the Company.
user.contact.updated		by: login, from: monster
user.contact.urls	Object.<string, url> maximum-length of values: 254	Websites and other online resources. Use the object key like a name of the address. Example keys: Downloads, Support, FTP, etc.
user.contact.v	Array.<uint32>	Object version keys used to validate synchronization for all object properties.
user.enabled	boolean	Indicates whether system access is disabled.
user.formats	Object.<codified, datetimetemplate> maximum-length of values: 20	The format strings defining the preferred way to display ambiguous values.
user.groups	Array.<UserGroup>	The list of UserGroups to which this User belongs.
user.language	codified maximum-length: 5 minimum-length: 2	Preferred region/language for the UI and notifications. Valid formats use <ISO 639-1><dash><ISO 3166-2> such as "fr-CA" or "en-US".
user.login	email see: User.login maximum-length: 254 minimum-length: 6	The unique public email address used to access the system.
user.measurements	Object.<codified, SystemsOfUnits>	Preferred way of displaying ambiguous numbers in the context of measurements.
user.nickname	string maximum-length: 100	Human friendly name for these credentials
user.notify	Array.<UserNotifications> maximum-count: 7	Definition of how and when to send alerts to the user.
user.options	Object.<codified, string> maximum-length of values: 20	Additional options which do not fit in with the formats or measurements preferences.
user.passwordExpired	boolean	Indicated whether the credentials have expired according to the company's policy.
user.permissions	Array.<Permission>	Individual permission rules which override the UserGroup rules.
user.processedUtc	datetime	When the was change procesed.
user.timezone	codified see: Timezone.code	The user's local timezone.
user.updated		by: login, from: monster
user.v	Array.<uint32>	Version keys for all parts of your User.

Response message structure

getSessionDetailsResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"expiry": string,
	"ghostId": string,
	"machine": {
		"company": number,
		"enabled": boolean,
		"formats": {
			string: string
		},
		"groups": [
			{
				"company": number,
				"id": number,
				"name": string,
				"notes": string,
				"permissions": [
					{
						"company": number,
						"kind": string,
						"labels": [
							string
						],
						"level": string,
						"method": string,
						"type": string
					}
				],
				"processedUtc": string,
				"updated": {
				},
				"v": [
					number
				]
			}
		],
		"insecure": boolean,
		"ipRanges": [
			string
		],
		"key": string,
		"language": string,
		"measurements": {
			string: string
		},
		"nickname": string,
		"notAfter": string,
		"notBefore": string,
		"notes": string,
		"options": {
			string: string
		},
		"permissions": [
			{
				"company": number,
				"kind": string,
				"labels": [
					string
				],
				"level": string,
				"method": string,
				"type": string
			}
		],
		"processedUtc": string,
		"referrers": [
			string
		],
		"secret": string,
		"services": [
			string
		],
		"timezone": string,
		"updated": {
		},
		"v": [
			number
		]
	},
	"message": string,
	"passwordPolicy": {
		"expireMode": string,
		"expireThreshold": number,
		"includeLetters": boolean,
		"includeNumbers": boolean,
		"includeSpecial": boolean,
		"includeUpperLower": boolean,
		"minimumLength": number
	},
	"reqId": number,
	"serverTime": string,
	"sessionPolicy": {
		"applications": [
			string
		],
		"expireTimeout": number,
		"idleAllowed": boolean,
		"ipv4Ranges": [
			string
		],
		"maxSessions": number,
		"multiUser": string
	},
	"user": {
		"company": number,
		"contact": {
			"addresses": {
				string: string
			},
			"company": number,
			"dates": {
				string: string
			},
			"emails": {
				string: string
			},
			"id": number,
			"name": string,
			"notes": string,
			"options": {
				string: string
			},
			"otherNames": {
				string: string
			},
			"phones": {
				string: number
			},
			"pictures": [
				number
			],
			"processedUtc": string,
			"roles": [
				string
			],
			"updated": {
			},
			"urls": {
				string: string
			},
			"v": [
				number
			]
		},
		"enabled": boolean,
		"formats": {
			string: string
		},
		"groups": [
			{
				"company": number,
				"id": number,
				"name": string,
				"notes": string,
				"permissions": [
					{
						"company": number,
						"kind": string,
						"labels": [
							string
						],
						"level": string,
						"method": string,
						"type": string
					}
				],
				"processedUtc": string,
				"updated": {
				},
				"v": [
					number
				]
			}
		],
		"language": string,
		"login": string,
		"measurements": {
			string: string
		},
		"nickname": string,
		"notify": [
			{
				"email": string,
				"enabled": boolean,
				"end": string,
				"name": string,
				"offline": [
					string
				],
				"online": [
					string
				],
				"sms": number,
				"start": string,
				"weekdays": [
					boolean
				]
			}
		],
		"options": {
			string: string
		},
		"passwordExpired": boolean,
		"permissions": [
			{
				"company": number,
				"kind": string,
				"labels": [
					string
				],
				"level": string,
				"method": string,
				"type": string
			}
		],
		"processedUtc": string,
		"timezone": string,
		"updated": {
		},
		"v": [
			number
		]
	}
}

Possible exceptions

Error Code	Description
2	A communication error occurred. If you receive this error, please contact technical support.
28	The session is valid, but the CompanyPolicies is missing. If you receive this error, please contact technical support.
54	The session is valid, but the User (or Machine) is missing. If you receive this error, please contact technical support.

login

Creates a new session and allows access to authorized services.

Request message description

Property	Type	Required	Description
password	string	always	User's password.
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.
userAgent	string	optional	Application name. This should match the allowed applications from user's company's SessionPolicy.applications.
username	string	always	User's email address.

Request message structure

login {
	"password": string,
	"reqId": number,
	"userAgent": string,
	"username": 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.

Response message structure

loginResponse {
	"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 username is not a valid email address.
3	The password is blank or not given.
11	The username and/or password are not correct.
12	The client application is not allowed based on the Company's policy.
13	The client IP address is not allowed based on the Company's policy.
14	The User's Company's policy does not allow for multiple sessions per User, and there is already another active session.
28	The User's Company cannot be found. If you encounter this error, please contact support.
73	There are too many concurrent sessions for this User.
73	There are too many concurrent WebSocket connections for this User.
85	The credentials are correct, but the User is not allowed to log in.

logout

Ends your session.

Request message description

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

Request message structure

logout {
	"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.
expiry	datetime	The timestamp from when you session expired.
ghostId	string	Your old, no longer valid, session identifier.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

logoutResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"expiry": string,
	"ghostId": string,
	"message": string,
	"reqId": number
}

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.

updateOwnContact

Allows a User to update their own Contact. If your User has no associated Contact, you will receive a Contact not found error.

Request message description

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

Request message structure

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

Response 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

updateOwnContactResponse {
	"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 contact object, or it is invalid.
3	The contact object does not contain an id, or it is invalid.
3	No valid changes would be performed.
3	The v was not an array, or contained too few numbers.
3	One of the otherNames keys or values is invalid. Returns an ErrorDetailInput as the `errorDetails`.
3	One of the emails keys or values is invalid. Returns an ErrorDetailInput as the `errorDetails`.
3	One of the phones keys or values is invalid. Returns an ErrorDetailInput as the `errorDetails`.
3	One of the addresses keys or values is invalid. Returns an ErrorDetailInput as the `errorDetails`.
3	One of the urls keys or values is invalid. Returns an ErrorDetailInput as the `errorDetails`.
3	One of the dates keys or values is invalid. Returns an ErrorDetailInput as the `errorDetails`.
3	One of the options keys or values is invalid. Returns an ErrorDetailInput as the `errorDetails`.
3	One of the pictures values is invalid. Returns an ErrorDetailInput as the `errorDetails`.
6	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.
31	Your User does not have a Contact defined.
54	Your User was not found. If the problem persists, please contact support.
69	One or more of the pictures identifiers given was not found.
85	Your User is disabled. If the problem persists, please contact support.

updateOwnPassword

Allows a session User to change their own password.

Request message description

Property	Type	Required	Description
current	string	always	Your current password, as verification that you are the proper account owner.
password	string	always	Your new password must conform to your company's password policy.
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

Request message structure

updateOwnPassword {
	"current": string,
	"password": string,
	"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.
expires	datetime	Specific date/time of when the password will expire.
message	string	An English description of the error.
passwordPolicy	PasswordPolicy	Your Company's password policy.
passwordPolicy.expireMode	PasswordExpiryMode	Defines how passwords expire.
passwordPolicy.expireThreshold	byte	The threshold for expiry.
passwordPolicy.includeLetters	boolean	Do passwords require alphabetical characters.
passwordPolicy.includeNumbers	boolean	Do passwords require numeric characters.
passwordPolicy.includeSpecial	boolean	Do passwords require non-alphanumeric characters.
passwordPolicy.includeUpperLower	boolean	Do passwords require upper-case and lower-case letters.
passwordPolicy.minimumLength	byte	The minimum number of characters required.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

updateOwnPasswordResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"expires": string,
	"message": string,
	"passwordPolicy": {
		"expireMode": string,
		"expireThreshold": number,
		"includeLetters": boolean,
		"includeNumbers": boolean,
		"includeSpecial": boolean,
		"includeUpperLower": boolean,
		"minimumLength": number
	},
	"reqId": number
}

Possible exceptions

Error Code	Description
2	A communication error occurred. If you receive this error, please contact technical support.
3	The current password is blank or not given.
3	The new password is blank or not given.
7	You cannot execute this command because your session has expired.
8	You cannot execute this command because you are not logged in.
11	The current password is not correct.
15	The new password is not strong enough to comply with the PasswordPolicy requirements.
17	The current password cannot be the same as the new password.
28	Your CompanyPolicies is missing. If the problem persists, please contact support.
28	Your Company's PasswordPolicy is missing. If the problem persists, please contact support.
54	The session User was not found. If the problem persists, please contact support.
85	The session User is disabled. If the problem persists, please contact support.

updateOwnPreferences

Allows a session User to change their own preferences.

Request message description

Property	Type	Required	Description
formats	Object.<string, string>	optional	Formatting help for dates, times, numbers.
language	string	optional	Preferred region/language for the UI and notifications. Valid formats use <ISO 639-1><dash><ISO 3166-2> such as "fr-CA" or "en-US".
measurements	Object.<string, SystemsOfUnits?>	optional	Preferred way of displaying ambiguous numbers in the context of measurements.
notify	Array.<UserNotifications>	optional	List of UserNotifications preferences. Please note that active times cannot overlap.
options	Object.<string, string>	optional	Additional options which do not fit in with the formats or measurements preferences. If a value of null is given, the option is removed. To keep the option, you can use a blank string. For convenience, if the value of an option is given as JSON (instead of a string), they are automatically serialized with no white-space.
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.
timezone	codified see: Timezone.code	optional	Your local Timezone used to calculate times.

Request message structure

updateOwnPreferences {
	"formats": {
		string: string
	},
	"language": string,
	"measurements": {
		string: string
	},
	"notify": [
		{
			"email": string,
			"enabled": boolean,
			"end": string,
			"name": string,
			"offline": [
				string
			],
			"online": [
				string
			],
			"sms": number,
			"start": string,
			"weekdays": [
				boolean
			]
		}
	],
	"options": {
		string: string
	},
	"reqId": number,
	"timezone": string
}

Response 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

updateOwnPreferencesResponse {
	"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	No valid changes would be performed.
3	The given language was not a valid region.
3	One of the keys given in the formats dictionary was blank.
3	One of the keys given in the measurements dictionary was blank.
3	One of the keys given in the options dictionary was blank.
3	One of the given notify values was null, had a blank name property, or was not a valid object.
3	One of the measurements could not be parsed. Returns an ErrorDetailInput as the `errorDetails`.
3	One of the notify could not be parsed. Returns an ErrorDetailInput as the `errorDetails`.
3	One of the notify did not contain a name. Returns an ErrorDetailInput 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.
16	You cannot execute this command because your password has expired.
54	Your User was not found. If the problem persists, please contact support.
62	The given timezone could not be found. Returns an ErrorDetailInput as the `errorDetails`.
85	Your User is disabled. If the problem persists, please contact support.

Users and Groups

getContact

Gets details of the specified Contact.

Request message description

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

Request message structure

getContact {
	"contact": {
		"id": number
	},
	"includeDeleted": boolean,
	"reqId": number
}

Response message description

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

Response message structure

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

Possible exceptions

Error Code	Description
3	The request does not contain a contact object, or it is invalid.
3	The contact object does not contain an id, or it is invalid.
5	You do not have permission to view this Contact.
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.
31	The Contact was not found by its unique identifier.

getContactsList

Gets the list of Contacts 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

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

Response message structure

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

Possible exceptions

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 Contacts 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.

getMachine

Gets details of the specified Machine.

Request message description

Property	Type	Required	Default	Description
includeDeleted	boolean	optional	`false`	When true, the command will also return a deleted Machine.
machine	ParamKey	always		An object to contain the "key" of the Machine.
machine.key	string	always		The Machine's login.
reqId	int32?	optional		Identifier used by external system to correlate requests to responses.

Request message structure

getMachine {
	"includeDeleted": boolean,
	"machine": {
		"key": string
	},
	"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.
machine	Machine	The requested Machine.
machine.company	uint64 see: Company.id	The company to which this user belongs.
machine.enabled	boolean	Indicates whether system access is disable.
machine.formats	Object.<codified, datetimetemplate> maximum-length of values: 20	The format strings defining the preferred way to display ambiguous values.
machine.groups	Array.<uint64> see: UserGroup.id	A list of groups to which this machine account belongs.
machine.insecure	boolean	When true, no access restrictions (SelfMachine.secret, SelfMachine.referrers, or SelfMachine.ipRanges) are enforced.
machine.ipRanges	Array.<ipv4> maximum-length of values: 19	Restrict service access to only the provided IP ranges. Currently we only support IPv4 ranges using CIDR slash-notation.
machine.key	string maximum-length: 50	The unique idenifier used to access the system.
machine.language	codified maximum-length: 5 minimum-length: 2	Preferred region/language for the UI and notifications. Valid formats use <ISO 639-1><dash><ISO 3166-2> such as "fr-CA" or "en-US".
machine.measurements	Object.<codified, SystemsOfUnits>	Preferred way of displaying ambiguous numbers in the context of measurements.
machine.nickname	string maximum-length: 100	Human friendly name for these credentials
machine.notAfter	datetime	An optional timestamp that restricts this machine account from being used after the given date.
machine.notBefore	datetime	An optional timestamp that restricts this machine account from being used before the given date.
machine.notes	string maximum-length: 8000	Notes about this machine.
machine.options	Object.<codified, string> maximum-length of values: 20	Additional options which do not fit in with the formats or measurements preferences.
machine.permissions	Array.<Permission>	Permission rules which override the group rules.
machine.processedUtc	datetime	When the was change procesed.
machine.referrers	Array.<url> maximum-length of values: 254	Optional list of your managed domains from which this machine account can be used.
machine.secret	string maximum-length: 1000	A token used to encode or validate requests.
machine.services	Array.<url> maximum-length of values: 254	List of system service URIs that this machine account is permitted to access.
machine.timezone	codified see: Timezone.code	The service account's local timezone.
machine.updated		by: login, from: monster
machine.v	Array.<uint32>	Object version keys used to validate synchronization for all object properties.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

getMachineResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"machine": {
		"company": number,
		"enabled": boolean,
		"formats": {
			string: string
		},
		"groups": [
			number
		],
		"insecure": boolean,
		"ipRanges": [
			string
		],
		"key": string,
		"language": string,
		"measurements": {
			string: string
		},
		"nickname": string,
		"notAfter": string,
		"notBefore": string,
		"notes": string,
		"options": {
			string: string
		},
		"permissions": [
			{
				"company": number,
				"kind": string,
				"labels": [
					string
				],
				"level": string,
				"method": string,
				"type": string
			}
		],
		"processedUtc": string,
		"referrers": [
			string
		],
		"secret": string,
		"services": [
			string
		],
		"timezone": string,
		"updated": {
		},
		"v": [
			number
		]
	},
	"message": string,
	"reqId": number
}

Possible exceptions

Error Code	Description
3	The request does not contain a machine object, or it is invalid.
3	The machine object does not contain a key, or it is invalid.
5	You do not have permission to view Machines.
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.
127	The requested Machine is not found.

getMachinesList

Gets the list of Machines 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.
first	string	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.
last	string	optional
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

getMachinesList {
	"company": {
		"id": number
	},
	"first": string,
	"includeArchive": boolean,
	"includeDeleted": boolean,
	"last": string,
	"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 Machines belong.
company.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
machines	Array.<Machine>	The list requested of Machines.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

getMachinesListResponse {
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"machines": [
		{
			"company": number,
			"enabled": boolean,
			"formats": {
				string: string
			},
			"groups": [
				number
			],
			"insecure": boolean,
			"ipRanges": [
				string
			],
			"key": string,
			"language": string,
			"measurements": {
				string: string
			},
			"nickname": string,
			"notAfter": string,
			"notBefore": string,
			"notes": string,
			"options": {
				string: string
			},
			"permissions": [
				{
					"company": number,
					"kind": string,
					"labels": [
						string
					],
					"level": string,
					"method": string,
					"type": string
				}
			],
			"processedUtc": string,
			"referrers": [
				string
			],
			"secret": string,
			"services": [
				string
			],
			"timezone": string,
			"updated": {
			},
			"v": [
				number
			]
		}
	],
	"message": string,
	"reqId": number
}

Possible exceptions

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 Machines.
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.

getSessionsList

Gets the list of SessionFull for the specified Company.

Request message description

Property	Type	Required	Description
company	ParamId	always	An object to contain the "id" of the Company.
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

getSessionsList {
	"company": {
		"id": 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 SessionFulls belong.
company.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.
sessions	Array.<SessionFull>	The list of requested SessionFull.

Response message structure

getSessionsListResponse {
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number,
	"sessions": [
		{
			"active": boolean,
			"company": number,
			"created": string,
			"expiry": string,
			"handle": string,
			"ipAddress": string,
			"lastActivity": string,
			"lastCommand": string,
			"login": string,
			"sockets": number,
			"status": string,
			"userAgent": string
		}
	]
}

Possible exceptions

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 SessionFulls for this Company.
5	You do not have permission to view Users 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.

getSessionsListByUser

Gets the list of SessionFulls for the specified User.

Request message description

Property	Type	Required	Description
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.
user	ParamLogin	always	An object to contain the "login" of the User.
user.login	email	always	The User's login.

Request message structure

getSessionsListByUser {
	"reqId": number,
	"user": {
		"login": 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.
sessions	Array.<SessionFull>	The list of requested SessionFull.
user	RespLoginCompany	An object to contain the "login" of the User to which the array of SessionFulls belong.
user.company	uint64	Identifier of the Company to which the User belongs.
user.login	string	The User's login.

Response message structure

getSessionsListByUserResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number,
	"sessions": [
		{
			"active": boolean,
			"company": number,
			"created": string,
			"expiry": string,
			"handle": string,
			"ipAddress": string,
			"lastActivity": string,
			"lastCommand": string,
			"login": string,
			"sockets": number,
			"status": string,
			"userAgent": string
		}
	],
	"user": {
		"company": number,
		"login": string
	}
}

Possible exceptions

Error Code	Description
3	The request does not contain a user object, or it is invalid.
3	The user object does not contain a login, or it is not an email address.
5	You do not have permission to view SessionFulls for this Company.
5	You do not have permission to view Users 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.
54	The User was not found by its unique identifier.

getUser

Gets details of the specified User.

Request message description

Property	Type	Required	Default	Description
includeDeleted	boolean	optional	`false`	When true, the command will also return a deleted User.
reqId	int32?	optional		Identifier used by external system to correlate requests to responses.
user	ParamLogin	always		An object to contain the "login" of the User.
user.login	email	always		The User's login.

Request message structure

getUser {
	"includeDeleted": boolean,
	"reqId": number,
	"user": {
		"login": 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.
user	User	The requested User.
user.company	uint64 see: Company.id	The company to which this user belongs.
user.contact	uint64? see: Contact.id	Contact information for this user.
user.enabled	boolean	Indicates whether system access is disabled.
user.formats	Object.<codified, datetimetemplate> maximum-length of values: 20	The format strings defining the preferred way to display ambiguous values.
user.groups	Array.<uint64> see: UserGroup.id	A list of groups to which this user belongs.
user.language	codified maximum-length: 5 minimum-length: 2	Preferred region/language for the UI and notifications. Valid formats use <ISO 639-1><dash><ISO 3166-2> such as "fr-CA" or "en-US".
user.login	email maximum-length: 254 minimum-length: 6	Unique identifier of this user.
user.measurements	Object.<codified, SystemsOfUnits>	Preferred way of displaying ambiguous numbers in the context of measurements.
user.nickname	string maximum-length: 100	Human friendly name for these credentials
user.notify	Array.<UserNotifications> maximum-count: 7	Definition of how and when to send alerts to the user.
user.options	Object.<codified, string> maximum-length of values: 20	Additional options which do not fit in with the formats or measurements preferences.
user.passwordExpired	boolean	Indicated whether the credentials have expired according to the company's policy.
user.permissions	Array.<Permission>	Individual permission rules which override the group rules.
user.processedUtc	datetime	When the was change procesed.
user.timezone	codified see: Timezone.code	The user's local timezone.
user.updated		by: login, from: monster
user.v	Array.<int32> fixed count: 2	Object version keys used to validate synchronization for all object properties.
user.v[0]	int32	The first element is for the general properties
user.v[1]	int32	The second element is for the advanced properties

Response message structure

getUserResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number,
	"user": {
		"company": number,
		"contact": number,
		"enabled": boolean,
		"formats": {
			string: string
		},
		"groups": [
			number
		],
		"language": string,
		"login": string,
		"measurements": {
			string: string
		},
		"nickname": string,
		"notify": [
			{
				"email": string,
				"enabled": boolean,
				"end": string,
				"name": string,
				"offline": [
					string
				],
				"online": [
					string
				],
				"sms": number,
				"start": string,
				"weekdays": [
					boolean
				]
			}
		],
		"options": {
			string: string
		},
		"passwordExpired": boolean,
		"permissions": [
			{
				"company": number,
				"kind": string,
				"labels": [
					string
				],
				"level": string,
				"method": string,
				"type": string
			}
		],
		"processedUtc": string,
		"timezone": string,
		"updated": {
		},
		"v": [
			number
		]
	}
}

Possible exceptions

Error Code	Description
3	The request does not contain a user object, or it is invalid.
3	The user object does not contain a login, or it is an invalid email address.
5	You do not have permission to view Users.
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.
54	The requested User is not found.

getUserGroup

Gets an existing UserGroup.

Request message description

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

Request message structure

getUserGroup {
	"includeDeleted": boolean,
	"reqId": number,
	"userGroup": {
		"id": 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.
userGroup	UserGroup	The requested UserGroup.
userGroup.company	uint64 see: Company.id	The company to which this group belongs.
userGroup.id	uint64	Unique identifier of this group.
userGroup.name	string maximum-length: 100	A name given to this group.
userGroup.notes	string	Notes about this group, and to whom this group should be applied.
userGroup.permissions	Array.<Permission>	Permissions for this group.
userGroup.processedUtc	datetime	When the was change procesed.
userGroup.updated		by: login, from: monster
userGroup.v	Array.<uint32>	Object version keys used to validate synchronization for all object properties.

Response message structure

getUserGroupResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number,
	"userGroup": {
		"company": number,
		"id": number,
		"name": string,
		"notes": string,
		"permissions": [
			{
				"company": number,
				"kind": string,
				"labels": [
					string
				],
				"level": string,
				"method": string,
				"type": string
			}
		],
		"processedUtc": string,
		"updated": {
		},
		"v": [
			number
		]
	}
}

Possible exceptions

Error Code	Description
3	The request does not contain a userGroup object, or it is invalid.
3	The requested userGroup id was invalid.
5	You do not have permission to view UserGroups.
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.
30	The UserGroup was not found by its unique identifier.

getUserGroupsList

Gets the list of UserGroups 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

getUserGroupsList {
	"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 contacts belong.
company.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.
userGroups	Array.<UserGroup>	The requested list of UserGroups.

Response message structure

getUserGroupsListResponse {
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number,
	"userGroups": [
		{
			"company": number,
			"id": number,
			"name": string,
			"notes": string,
			"permissions": [
				{
					"company": number,
					"kind": string,
					"labels": [
						string
					],
					"level": string,
					"method": string,
					"type": string
				}
			],
			"processedUtc": string,
			"updated": {
			},
			"v": [
				number
			]
		}
	]
}

Possible exceptions

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 UserGroups.
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.

getUsersList

Gets the list of Users 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.
first	string	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.
last	string	optional
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

getUsersList {
	"company": {
		"id": number
	},
	"first": string,
	"includeArchive": boolean,
	"includeDeleted": boolean,
	"last": string,
	"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 Users belong.
company.id	uint64?	Identifier given as input for the command.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.
users	Array.<User>	The list of requested Users.

Response message structure

getUsersListResponse {
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number,
	"users": [
		{
			"company": number,
			"contact": number,
			"enabled": boolean,
			"formats": {
				string: string
			},
			"groups": [
				number
			],
			"language": string,
			"login": string,
			"measurements": {
				string: string
			},
			"nickname": string,
			"notify": [
				{
					"email": string,
					"enabled": boolean,
					"end": string,
					"name": string,
					"offline": [
						string
					],
					"online": [
						string
					],
					"sms": number,
					"start": string,
					"weekdays": [
						boolean
					]
				}
			],
			"options": {
				string: string
			},
			"passwordExpired": boolean,
			"permissions": [
				{
					"company": number,
					"kind": string,
					"labels": [
						string
					],
					"level": string,
					"method": string,
					"type": string
				}
			],
			"processedUtc": string,
			"timezone": string,
			"updated": {
			},
			"v": [
				number
			]
		}
	]
}

Possible exceptions

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 Users.
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.

killSession

Terminates a SessionFull and forces the User to log back in.

Request message description

Property	Type	Required	Description
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.
session	ParamHandle	always	An object to contain the "handle" of the SessionFull.
session.handle	string	always	A "handle" identifying a session.

Request message structure

killSession {
	"reqId": number,
	"session": {
		"handle": 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.
session	Session	An object which contains the SessionFull's handle, related User login, and owning Company id.
session.company	uint64? see: Company.id	Identifier of the Company to which this object belongs
session.expiry	datetime	A timestamp for when the Session will expire.
session.handle	string	A "handle" identifying a resource.
session.login	string see: User.login	The User to which the Session belongs.

Response message structure

killSessionResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number,
	"session": {
		"company": number,
		"expiry": string,
		"handle": string,
		"login": string
	}
}

Possible exceptions

Error Code	Description
3	The request does not contain a session object, or it is invalid.
3	The session object does not contain a handle, or it is invalid.
5	You do not have permission to kill this SessionFull.
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.
19	The SessionFull was not found by its handle, or it is expired.

mergeContact

Creates a new or updates an existing Contact.

Request message description

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

Request message structure

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

Response message description

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

Response message structure

mergeContactResponse {
	"contact": {
		"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 contact object, or it is invalid.
3	Not enough keys exist in the contact object.
3	During create: When creating a new Contact, a company was not given.
3	During create: When creating a new Contact, a name was not given, or it is invalid.
3	During update: When updating a Contact, the id was invalid.
3	During update: When updating a Contact, the name was given as blank.
3	During update: When updating a Contact, the v was not an array, or contained too few numbers.
3	One of the contact.otherNames keys or values is invalid. Returns an ErrorDetailInput as the `errorDetails`.
3	One of the contact.emails keys or values is invalid. Returns an ErrorDetailInput as the `errorDetails`.
3	One of the contact.phones keys or values is invalid. Returns an ErrorDetailInput as the `errorDetails`.
3	One of the contact.addresses keys or values is invalid. Returns an ErrorDetailInput as the `errorDetails`.
3	One of the contact.urls keys or values is invalid. Returns an ErrorDetailInput as the `errorDetails`.
3	One of the contact.dates keys or values is invalid. Returns an ErrorDetailInput as the `errorDetails`.
3	One of the contact.options keys or values is invalid. Returns an ErrorDetailInput as the `errorDetails`.
3	One of the contact.pictures values is invalid. Returns an ErrorDetailInput as the `errorDetails`.
5	You do not have permission to create a new Contact.
5	You do not have permission to update this Contact.
6	During update: When updating a Contact, 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.
31	During update: The Contact was not found by its unique identifier.
69	One of the contact.pictures given as input in the Pictures array was not found. Returns an ErrorDetailBadIds as the `errorDetails`.
130	During update: When updating a Contact, the company was provided as a different value.

mergeMachine

Creates a new or updates an existing Machine.

Request message description

Property	Type	Required	Description
machine	Object.<string, ?>	always	An object to contain the Machine parameters.
machine.company	uint64?	create	The company to which this Machine belongs. After creation, this value is read-only.
machine.enabled	boolean	optional	Indicates whether system access is disable.
machine.formats	Object.<string, string>	optional	The format strings defining the preferred way to display ambiguous values.
machine.groups	Array.<uint64> for values see: UserGroup.id	optional	A list of UserGroup to which this Machine belongs.
machine.insecure	boolean	optional	Indicates whether completely insecure/unrestricted system access is allowed.
machine.ipRanges	Array.<ipv4> maximum-length of values: 19	optional	Restrict Machine access to only the provided IPv4 ranges (using CIDR slash-notation).
machine.key	string	update	The unique identifier of the Machine you want to update.
machine.language	string maximum-length: 5 minimum-length: 2	optional	Preferred region/language for the UI and notifications. Valid formats use <ISO 639-1><dash><ISO 3166-2> such as "fr-CA" or "en-US".
machine.measurements	Object.<string, SystemsOfUnits?>	optional	Preferred way of displaying ambiguous numbers in the context of measurements.
machine.nickname	string maximum-length: 100	optional	Human friendly name for this Machine.
machine.notAfter	datetime	optional	An optional timestamp that restricts this Machine from being used after the given date.
machine.notBefore	datetime	optional	An optional timestamp that restricts this Machine from being used before the given date.
machine.notes	string maximum-length: 8000	optional	Notes about this Machine.
machine.options	Object.<string, string>	optional	Additional options which do not fit in with the formats or measurements preferences.
machine.permissions	Array.<ParamPermission>	optional	Individual permission rules which override the UserGroup rules.
machine.referrers	Array.<url> maximum-length of values: 254	optional	Optional list of your managed domains from which this Machine can be used.
machine.secret	boolean	optional	A flag to either remove, or generate a new SelfMachine.secret.
machine.services	Array.<url> maximum-length of values: 254	optional	List of Fleet Freedom service URIs that this Machine is permitted to access.
machine.timezone	codified see: Timezone.code	optional	The Machine's local timezone.
machine.v	Array.<int32>	optional
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

Request message structure

mergeMachine {
	"machine": {
		"company": number,
		"enabled": boolean,
		"formats": {
			string: string
		},
		"groups": [
			number
		],
		"insecure": boolean,
		"ipRanges": [
			string
		],
		"key": string,
		"language": string,
		"measurements": {
			string: string
		},
		"nickname": string,
		"notAfter": string,
		"notBefore": string,
		"notes": string,
		"options": {
			string: string
		},
		"permissions": [
			{
				"company": number,
				"kind": string,
				"labels": [
					string
				],
				"level": string,
				"method": string
			}
		],
		"referrers": [
			string
		],
		"secret": boolean,
		"services": [
			string
		],
		"timezone": string,
		"v": [
			number
		]
	},
	"reqId": number
}

Response 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.
machine	RespKeyCompany	An object which contains the "key" and "company" keys when there is no error.
machine.company	uint64	Identifier of the Company to which the Machine belongs.
machine.key	string	The Machine's key.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

mergeMachineResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"machine": {
		"company": number,
		"key": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

Error Code	Description
2	A communication error occurred. If you receive this error, please contact technical support.
2	Unable to generate unique key. If you receive this error, please contact technical support.
3	The request does not contain a machine object, or it is invalid.
3	No valid changes would be performed.
3	The given language value was not a valid culture.
3	One of the keys given in the machine.formats dictionary was blank.
3	One of the keys given in the machine.measurements dictionary was blank.
3	One of the keys given in the machine.options dictionary was blank.
3	During create: When creating a new Machine, a key was given. Keys are generated by the system during creation.
3	During create: When creating a new Machine, a company was not given.
3	One of the schemes in the given machine.services array was not allowed. Returns an ErrorDetailEnum as the `errorDetails`.
3	One of the schemes in the given machine.referrers array was not allowed. Returns an ErrorDetailEnum as the `errorDetails`.
3	The given machine.notBefore value could not be parsed into a date/time. Returns an ErrorDetailInput as the `errorDetails`.
3	The given machine.notAfter value could not be parsed into a date/time. Returns an ErrorDetailInput as the `errorDetails`.
3	One of the values given in the machine.measurements dictionary was invalid. Returns an ErrorDetailInput as the `errorDetails`.
3	One of the values given in the machine.groups array was invalid. Returns an ErrorDetailInput as the `errorDetails`.
3	One of the values given in the machine.permissions array was invalid. Returns an ErrorDetailInput as the `errorDetails`.
3	One of the values given in the machine.services array was invalid. Returns an ErrorDetailInput as the `errorDetails`.
3	One of the values given in the machine.referrers array was invalid. Returns an ErrorDetailInput as the `errorDetails`.
3	One of the values given in the machine.ipRanges array was invalid. Returns an ErrorDetailInput as the `errorDetails`.
3	One of the values given in the machine.ipRanges array was a loopback. Returns an ErrorDetailInput as the `errorDetails`.
3	During update: When updating a Machine, the given key was invalid. Returns an ErrorDetailInput as the `errorDetails`.
5	During create: You do not have sufficient permission to create a new Machine.
5	During update: You do not have sufficient permission to update Machines.
6	During update: When updating a Machine, 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.
30	One or more of the UserGroups given could not be found, or were from a different Company. Returns an ErrorDetailBadIds as the `errorDetails`.
62	The given Timezone value could not be found. Returns an ErrorDetailInput as the `errorDetails`.
71	The Machine you are creating or updating would have higher, or more, permissions than you do. Returns an ErrorDetailEscalation as the `errorDetails`.
127	During update: When updating a Machine and the Machine does not exists.
130	During update: When updating a Machine, the machine.company can not be changed.

mergeUser

Creates a new or updates an existing User.

Request message description

Property	Type	Required	Description
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.
user	Object.<string, ?>	always
user.company	uint64?	create	The company to which this User belongs. After creation, this value is read-only.
user.contact	uint64? see: Contact.id	optional	Contact information for this User.
user.enabled	boolean	optional	Indicates whether system access is disable.
user.formats	Object.<codified, string>	optional	The format strings defining the preferred way to display ambiguous values.
user.groups	Array.<uint64> for values see: UserGroup.id	optional	A list of UserGroups to which this User is a member.
user.language	string maximum-length: 5 minimum-length: 2	optional	Preferred region/language for the UI and notifications. Valid formats use <ISO 639-1><dash><ISO 3166-2> such as "fr-CA" or "en-US".
user.login	email	always	The unique identifier of the User you want to update.
user.measurements	Object.<codified, SystemsOfUnits?>	optional	Preferred way of displaying ambiguous numbers in the context of measurements.
user.nickname	string maximum-length: 100	optional	Human friendly name for these credentials
user.notify	Array.<UserNotifications>	optional	Definition of how and when to send alerts to the User.
user.options	Object.<codified, string>	optional	Additional options which do not fit in with the formats or measurements preferences.
user.password	string	create	This User's password.
user.passwordExpired	boolean	optional	Indicated whether the credentials have expired according to the company's policy.
user.permissions	Array.<ParamPermission> maximum-count of values: 254	optional	Individual permission rules which override the UserGroup rules.
user.timezone	codified see: Timezone.code	optional	The User's local timezone.
user.v	Array.<int32>	optional

Request message structure

mergeUser {
	"reqId": number,
	"user": {
		"company": number,
		"contact": number,
		"enabled": boolean,
		"formats": {
			string: string
		},
		"groups": [
			number
		],
		"language": string,
		"login": string,
		"measurements": {
			string: string
		},
		"nickname": string,
		"notify": [
			{
				"email": string,
				"enabled": boolean,
				"end": string,
				"name": string,
				"offline": [
					string
				],
				"online": [
					string
				],
				"sms": number,
				"start": string,
				"weekdays": [
					boolean
				]
			}
		],
		"options": {
			string: string
		},
		"password": string,
		"passwordExpired": boolean,
		"permissions": [
			{
				"company": number,
				"kind": string,
				"labels": [
					string
				],
				"level": string,
				"method": string
			}
		],
		"timezone": string,
		"v": [
			number
		]
	}
}

Response 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.
user	RespLoginCompany
user.company	uint64	Identifier of the Company to which the User belongs.
user.login	string	The User's login.

Response message structure

mergeUserResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number,
	"user": {
		"company": number,
		"login": string
	}
}

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 user object, or it is invalid.
3	No valid changes would be performed.
3	The user object did not contain a login, or was not a valid email address.
3	The user object contains a contact which is not valid.
3	The user object contains a blank password.
3	The given language was not a valid region.
3	One of the keys given in the user.formats dictionary was blank.
3	One of the keys given in the user.measurements dictionary was blank.
3	One of the keys given in the user.options dictionary was blank.
3	One of the given user.notify values was null, had a blank name property, or was not a valid object.
3	The contact given is from a different company than the User.
3	During create: When creating a new User, a company was not given.
3	During create: When creating a new User, a password was not given.
3	During update: When updating a User, the company can not be changed.
3	One of the user.measurements could not be parsed. Returns an ErrorDetailInput as the `errorDetails`.
3	One of the user.notify preferences could not be parsed. Returns an ErrorDetailInput as the `errorDetails`.
3	One of the user.notify preferences did not contain a name. Returns an ErrorDetailInput as the `errorDetails`.
3	One of the user.groups was not given as a number. Returns an ErrorDetailInput as the `errorDetails`.
3	One of the user.permissions was invalid. Returns an ErrorDetailInput as the `errorDetails`.
5	During create: You do not have sufficient permission to create a new User.
5	During update: You do not have sufficient permission to update Users.
5	During update: You do not have sufficient permission to update User permissions.
5	During update: You do not have sufficient permission to view contacts.
6	During update: When updating a User, 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.
15	The user.password given for the User was not strong enough.
16	You cannot execute this command because your password has expired.
28	The User's company's password policy could not be found. If you receive this error, please contact technical support.
30	One or more of the UserGroups given could not be found, or were from a different company. Returns an ErrorDetailBadIds as the `errorDetails`.
31	The Contact given could not be found.
54	During update: When updating a User and the User does not exists.
55	During create: When creating a new User and the User already exists.
57	You cannot disable your own User.
62	The given Timezone could not be found. Returns an ErrorDetailInput as the `errorDetails`.
71	The User you are creating or updating would have higher, or more, permissions than you do. Returns an ErrorDetailEscalation as the `errorDetails`.
130	The specified user.contact was found, but was not in the same Company as the given User.
130	During update: When updating an User, the user.company can not be changed.

mergeUserGroup

Creates a new or updates an existing UserGroup.

Request message description

Property	Type	Required	Description
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.
userGroup	Object.<string, ?>	always	A simple object to contain the UserGroup parameters.
userGroup.company	uint64?	create	The company to which this UserGroup belongs. After creation, this value is read-only.
userGroup.id	uint64?	update	The unique identifier of the UserGroup you want to update.
userGroup.name	string maximum-length: 100	create	Name for the UserGroup.
userGroup.notes	string	optional	Notes for the UserGroup.
userGroup.permissions	Array.<ParamPermission> maximum-count of values: 254	optional	List of permissions assigned to members of this UserGroup.
userGroup.v	Array.<int32>	optional

Request message structure

mergeUserGroup {
	"reqId": number,
	"userGroup": {
		"company": number,
		"id": number,
		"name": string,
		"notes": string,
		"permissions": [
			{
				"company": number,
				"kind": string,
				"labels": [
					string
				],
				"level": string,
				"method": string
			}
		],
		"v": [
			number
		]
	}
}

Response 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.
userGroup	RespIdCompany	An object which contains the "id" and "company".
userGroup.company	uint64	Identifier of the Company to which this object belongs.
userGroup.id	uint64?	Identifier given as input for the command.

Response message structure

mergeUserGroupResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number,
	"userGroup": {
		"company": number,
		"id": 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 userGroup object, or it is invalid.
3	Not enough keys exist in the userGroup object.
3	During create: When creating a new UserGroup, a company was not given.
3	During create: When creating a new UserGroup, a name was not given, or it is invalid.
3	During create: When creating a new UserGroup, no Permissions were given.
3	During update: When updating a UserGroup, the id was invalid.
3	During update: When updating a UserGroup, the userGroup object contained too few keys.
3	During update: When updating a UserGroup, all Permissions were removed.
5	During create: You do not have permission to create a new UserGroup.
5	During update: You do not have permission to update UserGroups.
6	During update: When updating a UserGroup, 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.
30	During update: The UserGroup was not found by its unique identifier.
71	Resulting permissions would grant a higher level of access than session User's own access level.
130	During update: When updating a UserGroup, the userGroup.company can not be changed.

removeContact

Deletes an existing Contact.

Request message description

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

Request message structure

removeContact {
	"contact": {
		"id": number
	},
	"reqId": number
}

Response message description

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

Response message structure

removeContactResponse {
	"contact": {
		"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 contact object, or it is invalid.
3	The contact object does not contain an id, or it is invalid.
5	You do not have permission to delete this Contact.
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.
31	The Contact was not found by its unique identifier.
121	This Contact is still being used by a Asset or User. Returns an ErrorDetailContactInUse as the `errorDetails`.

removeMachine

Deletes an existing Machine.

Request message description

Property	Type	Required	Description
machine	ParamKey	always	An object to contain the "key" of the Machine.
machine.key	string	always	The Machine's login.
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

Request message structure

removeMachine {
	"machine": {
		"key": string
	},
	"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.
machine	RespKeyDeleted	An object which contains the Machine's key, owning Company id, and deleted status.
machine.company	uint64	Identifier of the Company to which the Machine belongs.
machine.deleted	boolean	Flag showing if the object is deleted.
machine.key	string	The Machine's key.
machine.v	Array.<uint32>
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

removeMachineResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"machine": {
		"company": number,
		"deleted": boolean,
		"key": string,
		"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 machine object, or it is invalid.
3	The machine object does not contain a key, or it is invalid.
5	You do not have permission to delete Machines.
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.
127	The requested Machine is not found.

removeUser

Deletes an existing User.

Request message description

Property	Type	Required	Description
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.
user	ParamLogin	always	An object to contain the "login" of the User.
user.login	email	always	The User's login.

Request message structure

removeUser {
	"reqId": number,
	"user": {
		"login": 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.
user	RespLoginDeleted	An object which contains the User's login, owning Company id, and deleted status.
user.company	uint64	Identifier of the Company to which the User belongs.
user.deleted	boolean	Flag showing if the object is deleted.
user.login	string	The User's login.
user.v	Array.<uint32>

Response message structure

removeUserResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number,
	"user": {
		"company": number,
		"deleted": boolean,
		"login": string,
		"v": [
			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 user object, or it is invalid.
3	The user object does not contain a login, or it is an invalid email address.
5	You do not have permission to delete Users.
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.
54	The requested User is not found.
57	You cannot delete your own User.

removeUserGroup

Deletes an existing UserGroup.

Request message description

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

Request message structure

removeUserGroup {
	"reqId": number,
	"userGroup": {
		"id": 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.
userGroup	RespDeleted	An object which contains the "id" and "company" keys when there is no error.
userGroup.company	uint64	Identifier of the Company to which this object belongs.
userGroup.deleted	boolean	Flag showing if the object is deleted.
userGroup.id	uint64?	Identifier given as input for the command.
userGroup.v	Array.<uint32>

Response message structure

removeUserGroupResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number,
	"userGroup": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			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 userGroup object, or it is invalid.
3	The requested userGroup id was invalid.
5	You do not have permission to delete UserGroups.
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.
30	The UserGroup was not found by its unique identifier.
65	The UserGroup is currently in use. Please remove any Users who are a member of the UserGroup, then try again.

restoreContact

Restores the specified Contact.

Request message description

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

Request message structure

restoreContact {
	"contact": {
		"id": number
	},
	"reqId": number
}

Response message description

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

Response message structure

restoreContactResponse {
	"contact": {
		"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 contact object, or it is invalid.
3	The contact object does not contain an id, or it is invalid.
5	You do not have permission to restore this Contact.
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.
31	The Contact was not found by its unique identifier.
32	The Contact was found, but is not marked as deleted.

restoreMachine

Restores the specified Machine if it's been deleted.

Request message description

Property	Type	Required	Description
machine	ParamKey	always	An object to contain the "key" of the Machine.
machine.key	string	always	The Machine's login.
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

Request message structure

restoreMachine {
	"machine": {
		"key": string
	},
	"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.
machine	RespKeyDeleted	An object which contains the Machine's key, owning Company id, and deleted status.
machine.company	uint64	Identifier of the Company to which the Machine belongs.
machine.deleted	boolean	Flag showing if the object is deleted.
machine.key	string	The Machine's key.
machine.v	Array.<uint32>
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

restoreMachineResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"machine": {
		"company": number,
		"deleted": boolean,
		"key": string,
		"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 machine object, or it is invalid.
3	The machine object does not contain a key, or it is invalid.
5	You do not have permission to restore deleted Machines.
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.
127	The requested Machine is not found.
128	The requested Machine was found, but is not marked as deleted.

restoreUser

Restores the specified User if it's been deleted.

Request message description

Property	Type	Required	Description
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.
user	ParamLogin	always	An object to contain the "login" of the User.
user.login	email	always	The User's login.

Request message structure

restoreUser {
	"reqId": number,
	"user": {
		"login": 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.
user	RespLoginDeleted	An object which contains the User's login, owning Company id, and deleted status.
user.company	uint64	Identifier of the Company to which the User belongs.
user.deleted	boolean	Flag showing if the object is deleted.
user.login	string	The User's login.
user.v	Array.<uint32>

Response message structure

restoreUserResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number,
	"user": {
		"company": number,
		"deleted": boolean,
		"login": string,
		"v": [
			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 user object, or it is invalid.
3	The user object does not contain a login, or it is an invalid email address.
5	You do not have permission to restore Users.
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.
54	The requested User is not found.
55	The requested User not found, but is not marked as deleted.

restoreUserGroup

Restores a previously deleted UserGroup.

Request message description

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

Request message structure

restoreUserGroup {
	"reqId": number,
	"userGroup": {
		"id": 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.
userGroup	RespDeleted	An object which contains the "id" and "company" keys when there is no error.
userGroup.company	uint64	Identifier of the Company to which this object belongs.
userGroup.deleted	boolean	Flag showing if the object is deleted.
userGroup.id	uint64?	Identifier given as input for the command.
userGroup.v	Array.<uint32>

Response message structure

restoreUserGroupResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number,
	"userGroup": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			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 userGroup object, or it is invalid.
3	The requested userGroup id was invalid.
5	You do not have permission to delete UserGroups.
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.
30	The UserGroup was not found by its unique identifier.
66	The UserGroup was found, but is not marked as deleted.

White-labelling

getCompanyReseller

Gets details of the specified CompanyReseller.

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

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

Response message description

Property	Type	Description
companyReseller	CompanyReseller	The requested CompanyReseller.
companyReseller.contactInfo	Object.<string, uint64> see: Contact.id maximum-count of keys: 100 for values see: Contact.id	A list of Contacts for company specific things like Technical Support, Billing, etc...
companyReseller.domain	string maximum-length: 100	The URN and path to the instance of v4. It does not contain the protocol because all instances are required to be HTTPS.
companyReseller.favourite	string maximum-length: 200	The name of the icon file used for browser bookmarks.
companyReseller.gamut	Object.<string, ColourStyle> maximum-length of keys: 25	Colours used as templates for status tags, labels, and places.
companyReseller.graphics	Object.<string, codified> maximum-length of keys: 25 maximum-length of values: 30	A list of symbol names and their corresponding FontAwesome icon names.
companyReseller.icon	string maximum-length: 200	The name of the image uploaded as the logo (used for collapsed/mobile view).
companyReseller.id	uint64 see: Company.id	Unique identifier of the Company.
companyReseller.languages	Array.<codified> maximum-length of values: 5	A list of supported languages for your customers.
companyReseller.logo	string maximum-length: 200	The name of the image uploaded as the logo (used for regular view).
companyReseller.notifyEmail	NotificationServerEmail	The server used for notification and conversational email messages sent and received by the system.
companyReseller.notifyEmail.incomingAddress	string	The domain or IP address of the incoming email server.
companyReseller.notifyEmail.incomingLogin	string	The username used to login to the incoming email server.
companyReseller.notifyEmail.incomingMessageNumber	uint32	IMAP message sequence number so only recent messages are retrieved.
companyReseller.notifyEmail.incomingPort	uint16	The port number of the incoming email server.
companyReseller.notifyEmail.incomingSecure	boolean	Is the incoming email server using a secure SSL/TLS connection (it should).
companyReseller.notifyEmail.incomingType	string	The type of incoming protocol to use (IMAP or POP3).
companyReseller.notifyEmail.outgoingAddress	string	The domain or IP address of the outgoing email server.
companyReseller.notifyEmail.outgoingLogin	string	The username used to login to the outgoing email server.
companyReseller.notifyEmail.outgoingPort	uint16	The port number of the outgoing email server.
companyReseller.notifyEmail.outgoingReplyTo	email	An optional field which can be set as the "sent from" and/or "reply-to" address.
companyReseller.notifyEmail.outgoingSecure	boolean	Is the outgoing email server using a secure SSL/TLS connection (it should).
companyReseller.notifyEmail.outgoingType	string	The type of outgoing protocol to use (only SMTP).
companyReseller.notifySms	NotificationServerSms	Definition for load-balanced outbound SMS numbers for the reseller.
companyReseller.notifySms.notifyLimit	uint16	A per-number/per-day limit on the amount of Notifications sent.
companyReseller.notifySms.phoneNumbers	Object.<string, Array.<phone>> fixed length of keys: 2	All phone numbers listed by the country (using two-digit ISO 3166-1 alpha-2 country codes) they each serve.
companyReseller.parent	uint64 see: Company.id	The unique identifier of this company's parent organization.
companyReseller.processedUtc	datetime	When the was change procesed.
companyReseller.recoverBody	string	The body of the email sent to a user requesting a password reset.
companyReseller.recoverIsHtml	boolean
companyReseller.recoverSubject	string	The subject of the email sent to a user requesting a password reset.
companyReseller.serviceName	string maximum-length: 150	The name of the branded service being provided to the seller's customers.
companyReseller.termsPreamble	string	A preamble to the general terms and conditions offered by Fleet Freedom.
companyReseller.termsUpdated	datetime	The date and time when the terms were updated. This will promt users who are logging-in to re-agree to the new terms
companyReseller.updated		by: login, from: monster
companyReseller.v	Array.<uint32>	Object version keys used to validate synchronization for all object properties.
companyReseller.website	Object.<string, colour> maximum-length of keys: 25 maximum-length of values: 22	Themed colours used in the web-based UI.
errorCode	ErrorCode	The unique, numeric error code when processing this request.
errorDetails	ErrorDetail	An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
message	string	An English description of the error.
reqId	int32?	Identifier used by external system to correlate requests to responses.

Response message structure

getCompanyResellerResponse {
	"companyReseller": {
		"contactInfo": {
			string: number
		},
		"domain": string,
		"favourite": string,
		"gamut": {
			string: {
				"fill": string,
				"stroke": string
			}
		},
		"graphics": {
			string: string
		},
		"icon": string,
		"id": number,
		"languages": [
			string
		],
		"logo": string,
		"notifyEmail": {
			"incomingAddress": string,
			"incomingLogin": string,
			"incomingMessageNumber": number,
			"incomingPort": number,
			"incomingSecure": boolean,
			"incomingType": string,
			"outgoingAddress": string,
			"outgoingLogin": string,
			"outgoingPort": number,
			"outgoingReplyTo": string,
			"outgoingSecure": boolean,
			"outgoingType": string
		},
		"notifySms": {
			"notifyLimit": number,
			"phoneNumbers": {
				string: [
					number
				]
			}
		},
		"parent": number,
		"processedUtc": string,
		"recoverBody": string,
		"recoverIsHtml": boolean,
		"recoverSubject": string,
		"serviceName": string,
		"termsPreamble": string,
		"termsUpdated": string,
		"updated": {
		},
		"v": [
			number
		],
		"website": {
			string: string
		}
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}

Possible exceptions

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.
5	You do not have permission to view this CompanyReseller.
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 CompanyReseller was not found by its unique identifier.

mergeCompanyReseller

Adds or updates the CompanyReseller to a Company.

Request message description

Property	Type	Required	Description
companyReseller	Object.<string, ?>	always	A simple object to contain the CompanyReseller parameters.
companyReseller.contactInfo	Object.<string, uint64?> maximum-count of keys: 100 for values see: Contact.id	optional	A list of Contacts for company specific things like Technical Support, Billing, etc...
companyReseller.domain	string maximum-length: 100	create	The URN and path to the instance of v4. It does not contain the protocol because all instances are required to be HTTPS.
companyReseller.favourite	string maximum-length: 200	optional	The name of the icon file used for browser bookmarks.
companyReseller.gamut	Object.<string, ColourStyle> maximum-length of keys: 25	create	Colours used as templates for status tags, labels, and places.
companyReseller.graphics	Object.<string, codified> maximum-length of keys: 25 maximum-length of values: 30	create	A list of symbol names and their corresponding FontAwesome icon names.
companyReseller.icon	string maximum-length: 200	create	The name of the image uploaded as the logo (used for collapsed/mobile view).
companyReseller.id	uint64	always	The unique identifier of the company you want to update.
companyReseller.languages	Array.<codified> maximum-length of values: 5	optional	A list of supported languages for your customers.
companyReseller.logo	string maximum-length: 200	create	The name of the image uploaded as the logo (used for regular view).
companyReseller.notifyEmail	Object.<string, ?>	create	Settings for sending and receiving email notifcations and asset messages.
companyReseller.notifyEmail.incomingAddress	string	optional	The domain or IP address of the incoming email server.
companyReseller.notifyEmail.incomingLogin	string	optional	The username used to login to the incoming email server.
companyReseller.notifyEmail.incomingMessageNumber	uint32?	optional	IMAP message sequence number so only recent messages are retrieved.
companyReseller.notifyEmail.incomingPassword	string	optional	The password used to login to the incoming email server.
companyReseller.notifyEmail.incomingPort	uint16?	optional	The port number of the incoming email server.
companyReseller.notifyEmail.incomingSecure	boolean	optional	Is the incoming email server using a secure SSL/TLS connection (it should).
companyReseller.notifyEmail.incomingType	string	optional	The type of incoming protocol to use (IMAP or POP3).
companyReseller.notifyEmail.outgoingAddress	string	optional	The domain or IP address of the outgoing email server.
companyReseller.notifyEmail.outgoingLogin	string	optional	The username used to login to the outgoing email server.
companyReseller.notifyEmail.outgoingPassword	string	optional	The password used to login to the outgoing email server.
companyReseller.notifyEmail.outgoingPort	uint16?	optional	The port number of the outgoing email server.
companyReseller.notifyEmail.outgoingReplyTo	email	optional	An optional field which can be set as the "sent from" and/or "reply-to" address.
companyReseller.notifyEmail.outgoingSecure	boolean	optional	Is the outgoing email server using a secure SSL/TLS connection (it should).
companyReseller.notifySms	Object.<string, ?>	create	Settings for sending and receiving SMS notifcations and asset messages.
companyReseller.notifySms.notifyLimit	uint16?	optional	A per-number/per-day limit on the amount of Notifications sent.
companyReseller.notifySms.phoneNumbers	Object.<string, Array.<phone>> fixed length of keys: 2	optional	All phone numbers listed by the country (using two-digit ISO 3166-1 alpha-2 country codes) they each serve.
companyReseller.recoverBody	string	create	The body of the email sent to a user requesting a password reset.
companyReseller.recoverIsHtml	boolean	optional
companyReseller.recoverSubject	string	optional	The subject of the email sent to a user requesting a password reset.
companyReseller.serviceName	string maximum-length: 150	create	The name of the branded service being provided to the seller's customers.
companyReseller.termsPreamble	string	optional	A small body of text added as a preamble for the Trak-iT Wireless Inc. terms of service.
companyReseller.termsUpdated	datetime	optional	A timestamp from when the preamble was changed.
companyReseller.v	Array.<int32>	optional
companyReseller.website	Object.<string, colour> maximum-length of keys: 25 maximum-length of values: 22	create	Themed colours used in the web-based UI.
reqId	int32?	optional	Identifier used by external system to correlate requests to responses.

Request message structure

mergeCompanyReseller {
	"companyReseller": {
		"contactInfo": {
			string: number
		},
		"domain": string,
		"favourite": string,
		"gamut": {
			string: {
				"fill": string,
				"stroke": string
			}
		},
		"graphics": {
			string: string
		},
		"icon": string,
		"id": number,
		"languages": [
			string
		],
		"logo": string,
		"notifyEmail": {
			"incomingAddress": string,
			"incomingLogin": string,
			"incomingMessageNumber": number,
			"incomingPassword": string,
			"incomingPort": number,
			"incomingSecure": boolean,
			"incomingType": string,
			"outgoingAddress": string,
			"outgoingLogin": string,
			"outgoingPassword": string,
			"outgoingPort": number,
			"outgoingReplyTo": string,
			"outgoingSecure": boolean
		},
		"notifySms": {
			"notifyLimit": number,
			"phoneNumbers": {
				string: [
					number
				]
			}
		},
		"recoverBody": string,
		"recoverIsHtml": boolean,
		"recoverSubject": string,
		"serviceName": string,
		"termsPreamble": string,
		"termsUpdated": string,
		"v": [
			number
		],
		"website": {
			string: string
		}
	},
	"reqId": number
}

Response message description

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

Response message structure

mergeCompanyResellerResponse {
	"companyReseller": {
		"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 companyReseller object, or it is invalid.
3	No valid changes would be performed.
3	The value for companyReseller.notifyEmail.incomingType was invalid. It can only be `IMAP` or `POP3`.
3	The value for companyReseller.notifyEmail.outgoingReplyTo was not valid email address.
3	One of the keys in the companyReseller.notifySms.phoneNumbers object is blank.
3	One of the values in the companyReseller.notifySms.phoneNumbers object is not valid.
3	During create: When adding a CompanyReseller, the companyReseller.id was not given.
3	During create: When adding a CompanyReseller, the companyReseller.serviceName was not given or was blank.
3	During create: When adding a CompanyReseller, the companyReseller.logo was not given.
3	During create: When adding a CompanyReseller, the companyReseller.icon was not given.
3	During create: When adding a CompanyReseller, the companyReseller.domain was not given.
3	During create: When adding a CompanyReseller, the companyReseller.website was not given or was invalid.
3	During create: When adding a CompanyReseller, the companyReseller.graphics was not given or was invalid.
3	During create: When adding a CompanyReseller, the companyReseller.gamut was not given or was invalid.
3	During create: When adding a CompanyReseller, the companyReseller.recoverBody was not given or was blank.
3	During update: When updating the CompanyReseller, the v was not an array, or contained too few numbers.
3	During update: When updating the CompanyReseller, the companyReseller.serviceName was given as blank or white-space.
3	During update: When updating the CompanyReseller, the companyReseller.logo was given as blank or white-space.
3	During update: When updating the CompanyReseller, the companyReseller.icon was given as blank or white-space.
3	During update: When updating the CompanyReseller, the companyReseller.domain was given as blank or white-space.
5	You do not have permission to add a CompanyReseller.
5	You do not have permission to update the CompanyReseller.
6	During update: When updating a CompanyReseller, 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	The Company was not found by its unique identifier.
106	During update: The CompanyReseller was not found by its unique identifier.
130	The resulting CompanyReseller.recoverSubject and CompanyReseller.recoverBody do not contain the required `%GUID%`.
130	During update: When updating the CompanyReseller, the resulting NotificationServerEmail would be invalid.
130	During update: When updating the CompanyReseller, the resulting NotificationServerSms would be invalid.

removeCompanyReseller

Deletes an existing CompanyReseller.

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

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

Response message description

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

Response message structure

removeCompanyResellerResponse {
	"companyReseller": {
		"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 companyReseller object, or it is invalid.
3	The companyReseller 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 delete this CompanyReseller.
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.
106	The CompanyReseller was not found by its unique identifier.

restoreCompanyReseller

Restores the specified CompanyReseller.

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

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

Response message description

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

Response message structure

restoreCompanyResellerResponse {
	"companyReseller": {
		"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 view this Company.
5	You do not have permission to restore this CompanyReseller.
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.
106	The CompanyReseller was not found by its unique identifier.
107	The CompanyReseller was found, but is not marked as deleted.