Call our help line: 1 866-787-2548

WebSocket Reference

Providers and Configurations

API Definitions

BroadcastMaintenanceobject

Notification to clients of a scheduled maintenance window. During a maintenance window, the service may go down and come back online repeatedly until the window ends.
JSON description
PropertyTypeDescription
endingdatetimeTimestamp of when the maintenance will end.
kindBroadcastTypeDowntime!
messagestringA message about when the maintenance window begins and ends.
serverTimedatetimeThe UTC date/time of the server hosting the connection.
startingdatetimeTimestamp of when the maintenance window begins.
JSON structure
{
	"ending": string,
	"kind": string,
	"message": string,
	"serverTime": string,
	"starting": string
}

BroadcastTypestring

The kinds of broadcast messages sent to all connected clients.
ValueDescription
maintenanceNotification of impending maintenance window involving downtime. During a maintenance window, the service may go down and come back online repeatedly until the window ends.
upgradeNotification that an upgrade will be available.

BroadcastUpgradeobject

Notification to clients that an upgrade will take place (with optional requirement of reloading all resources).
JSON description
PropertyTypeDescription
etadatetimeTimestamp of when the upgrade will be ready.
kindBroadcastTypeUpgrade to v4 system.
messagestringA message about when the service upgrade will be available.
reloadbooleanTrue when system objects have changed structure. It is recommended that all resources are purged and reloaded.
serverTimedatetimeThe UTC date/time of the server hosting the connection.
JSON structure
{
	"eta": string,
	"kind": string,
	"message": string,
	"reload": boolean,
	"serverTime": string
}

connection

Gets details of the current session (yourself) and User. 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.
Initial message description
PropertyTypeDescription
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
expirydatetimeThe timestamp of when this session expires.
ghostIdstringYour session identifier.
machineSelfMachineThis 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.companyuint64The company to which this user belongs.
machine.enabledbooleanIndicates whether system access is disable.
machine.formatsObject.<codified, datetimetemplate>
maximum-length of values: 20
The format strings defining the preferred way to display ambiguous values.
machine.groupsArray.<UserGroup>The list of UserGroup to which this User belongs.
machine.insecurebooleanWhen true, no access restrictions (machine.secret, machine.referrers, or machine.ipRanges) are enforced.
machine.ipRangesArray.<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.keystring
maximum-length: 50
The unique idenifier used to access the system.
machine.languagecodified
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.measurementsObject.<codified, SystemsOfUnits>Preferred way of displaying ambiguous numbers in the context of measurements.
machine.nicknamestring
maximum-length: 100
Human friendly name for these credentials
machine.notAfterdatetimeAn optional timestamp that restricts this machine account from being used after the given date.
machine.notBeforedatetimeAn optional timestamp that restricts this machine account from being used before the given date.
machine.notesstring
maximum-length: 8000
Notes about this machine.
machine.optionsObject.<codified, string>
maximum-length of values: 20
Additional options which do not fit in with the formats or measurements preferences.
machine.permissionsArray.<Permission>Permission rules which override the group rules.
machine.referrersArray.<url>
maximum-length of values: 254
Optional list of your managed domains from which this machine account can be used.
machine.secretstring
maximum-length: 1000
A token used to encode or validate requests.
machine.servicesArray.<url>
maximum-length of values: 254
List of system service URIs that this machine account is permitted to access.
machine.timezonecodifiedThe service account's local timezone.
machine.vArray.<uint32>
messagestringAn English description of the error.
passwordPolicyPasswordPolicyThis User's Company.passwordPolicy.
passwordPolicy.expireModePasswordExpiryModeDefines how passwords expire.
passwordPolicy.expireThresholdbyteThe threshold for expiry.
passwordPolicy.includeLettersbooleanDo passwords require alphabetical characters.
passwordPolicy.includeNumbersbooleanDo passwords require numeric characters.
passwordPolicy.includeSpecialbooleanDo passwords require non-alphanumeric characters.
passwordPolicy.includeUpperLowerbooleanDo passwords require upper-case and lower-case letters.
passwordPolicy.minimumLengthbyteThe minimum number of characters required.
reqIdint32?Identifier used by external system to correlate requests to responses.
serverTimedatetimeThe UTC date/time of the server hosting the connection.
sessionPolicySessionPolicyThis User's Company.sessionPolicy.
sessionPolicy.applicationsArray.<string>The list of applications users are allowed to use to create sessions.
sessionPolicy.expireTimeoutuint16The lifetime duration of a session in minutes.
sessionPolicy.idleAllowedbooleanDefines whether a session should be automatically killed when the connection breaks.
sessionPolicy.ipv4RangesArray.<ipv4>
maximum-length of values: 19
Restrict session creation to only the provided IPv4 ranges (using CIDR slash-notation). Leave blank for Internet access.
sessionPolicy.maxSessionsbyteThe maximum number of sessions allowed per user.
sessionPolicy.multiUserSessionMultiUserDefines the behaviour of the system when a user creates multiple sessions.
userSelfUserThis 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.companyuint64The company to which this user belongs.
user.contactContactAssociated contact information for this user.
user.contact.addressesObject.<string, string>Mailing addresses. Use the object key like a name of the address. Example keys: Home, Work, Park, etc.
user.contact.companyuint64The company to which this contact belongs
user.contact.datesObject.<string, datetime>Date information. Use the object key like a name of the date. Example keys: Birthday, Started Date, Retired On, etc.
user.contact.emailsObject.<string, email>
maximum-length of values: 254
Email addresses. Use the object key like a name of the address. Example keys: Home, Work, Support, Old, etc.
user.contact.iduint64Unique identifier of this contact.
user.contact.namestring
maximum-length: 100
The person's name
user.contact.notesstringNotes about this person.
user.contact.optionsObject.<string, string>Uncategorized information. Use the object keys and values however you'd like.
user.contact.otherNamesObject.<string, string>
maximum-length of values: 254
A collection of other names this person might go by. Use the object key like a name identifier. Example keys: Initials, Nickname, Maiden Name, etc.
user.contact.phonesObject.<string, phone>Phone numbers. Use the object key like a name of the phone number. Example keys: Mobile, Fax, Home, Office, etc.
user.contact.picturesArray.<uint64>
for values see: Picture.id
Pictures of this Contact.
user.contact.rolesArray.<string>A list of roles they play in the Company.
user.contact.urlsObject.<string, url>
maximum-length of values: 254
Websites and other online resources. Use the object key like a name of the address. Example keys: Downloads, Support, FTP, etc.
user.contact.vArray.<uint32>Object version keys used to validate synchronization for all object properties.
user.enabledbooleanIndicates whether system access is disable.
user.formatsObject.<codified, datetimetemplate>
maximum-length of values: 20
The format strings defining the preferred way to display ambiguous values.
user.groupsArray.<UserGroup>The list of UserGroups to which this User belongs.
user.languagecodified
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.loginemail
maximum-length: 254
minimum-length: 6
The unique public email address used to access the system.
user.measurementsObject.<codified, SystemsOfUnits>Preferred way of displaying ambiguous numbers in the context of measurements.
user.nicknamestring
maximum-length: 100
Human friendly name for these credentials
user.notifyArray.<UserNotifications>
maximum-count: 7
Definition of how and when to send alerts to the user.
user.optionsObject.<codified, string>
maximum-length of values: 20
Additional options which do not fit in with the formats or measurements preferences.
user.passwordExpiredbooleanIndicated whether the credentials have expired according to the company's policy.
user.permissionsArray.<Permission>Individual permission rules which override the UserGroup rules.
user.timezonecodifiedThe user's local timezone.
user.vArray.<uint32>
Initial message structure
connectionResponse {
	"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
					}
				],
				"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
			}
		],
		"referrers": [
			string
		],
		"secret": string,
		"services": [
			string
		],
		"timezone": string,
		"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
			],
			"roles": [
				string
			],
			"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
					}
				],
				"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
			}
		],
		"timezone": string,
		"v": [
			number
		]
	}
}
Possible exceptions
Error CodeDescription
2A communication error occurred.
If you receive this error, please contact technical support.
13The client IP address is not allowed based on the Company's policy.
28The session is valid, but the CompanyPolicies is missing.
If you receive this error, please contact technical support.
54The session is valid, but the User (or Machine) is missing.
If you receive this error, please contact technical support.
73There are too many concurrent WebSocket connections for this User.

getSubscriptionsList

Gets the list of current subscriptions for this socket.
Request message description
PropertyTypeRequiredDescription
reqIdint32?optionalIdentifier used by external system to correlate requests to responses.
Request message structure
getSubscriptionsList {
	"reqId": number
}
Response message description
PropertyTypeDescription
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
subscriptionsArray.<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 CodeDescription
7You cannot execute this command because your session has expired.
8You cannot execute this command because you are not logged in.
16You cannot execute this command because your password has expired.

getTimezone

Gets details of the specified Timezone.
Request message description
PropertyTypeRequiredDescription
reqIdint32?optionalIdentifier used by external system to correlate requests to responses.
timezoneParamCodealwaysAn object to contain the "code" of the Timezone.
timezone.codestringalwaysA "code" identifying a resource.
Request message structure
getTimezone {
	"reqId": number,
	"timezone": {
		"code": string
	}
}
Response message description
PropertyTypeDescription
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
timezoneTimezoneThe requested Timezone.
timezone.codecodifiedUnique timezone code
timezone.dstbooleanIndicates whether this timezone abides by daylight savings
timezone.namestringCommon timezone name
timezone.offsetint16Minutes offset from GMT
Response message structure
getTimezoneResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number,
	"timezone": {
		"code": string,
		"dst": boolean,
		"name": string,
		"offset": number
	}
}
Possible exceptions
Error CodeDescription
3The request does not contain a timezone object, or it is invalid.
3The timezone object does not contain a code, or it is invalid.
7You cannot execute this command because your session has expired.
8You cannot execute this command because you are not logged in.
16You cannot execute this command because your password has expired.
62The Timezone was not found by its codified identifier.

getTimezonesList

Gets a list of Timezones.
Request message description
PropertyTypeRequiredDescription
reqIdint32?optionalIdentifier used by external system to correlate requests to responses.
Request message structure
getTimezonesList {
	"reqId": number
}
Response message description
PropertyTypeDescription
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
timezonesArray.<Timezone>The list of valid system Timezones.
Response message structure
getTimezonesListResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number,
	"timezones": [
		{
			"code": string,
			"dst": boolean,
			"name": string,
			"offset": number
		}
	]
}
Possible exceptions
Error CodeDescription
2System Timezone list could not be retrieved.
If you receive this error, please contact technical support.
7You cannot execute this command because your session has expired.
8You cannot execute this command because you are not logged in.
16You 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
PropertyTypeRequiredDescription
reqIdint32?optionalIdentifier used by external system to correlate requests to responses.
Request message structure
noop {
	"reqId": number
}
Response message description
PropertyTypeDescription
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response message structure
noopResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}
Possible exceptions
Error CodeDescription
7Your session is invalid or expired.
7You cannot execute this command because your session has expired.
8You haven't logged in yet.
8You cannot execute this command because you are not logged in.
16You are logged in, but your pasword is expired.
16You cannot execute this command because your password has expired.

subscribe

Subscribes the socket to receive notifications for merge/delete changes to objects.
Request message description
PropertyTypeRequiredDescription
companyParamIdalwaysAn object to contain the "id" key.
company.iduint64alwaysIdentifier given as input for the command.
reqIdint32?optionalIdentifier used by external system to correlate requests to responses.
subscriptionTypesArray.<SubscriptionType>alwaysThe list of subscription types you want to receive.
Request message structure
subscribe {
	"company": {
		"id": number
	},
	"reqId": number,
	"subscriptionTypes": [
		string
	]
}
Response message description
PropertyTypeDescription
companyRespIdAn 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.iduint64?Identifier given as input for the command.
deniedArray.<SubscriptionType>Subscription types not added to your socket due to insufficient permissions.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
invalidArray.<string>A returned list of nonsense you sent to my beautiful service.
mergedArray.<SubscriptionType>Subscription types added/removed (or were not applicable) to your socket's subscription list.
messagestringAn English description of the error.
reqIdint32?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 CodeDescription
3The request does not contain a company or it is invalid.
3The request does not contain a subscriptionTypes or it is invalid.
3The given subscriptionTypes is empty.
5Access was denied for all subscription types. This error is not returned if at least one subscription type succeeds.
Returns an ErrorDetailBadKeys as the errorDetails..
7You cannot execute this command because your session has expired.
8You cannot execute this command because you are not logged in.
9Your session has expired during pocessing.
16You cannot execute this command because your password has expired.

Subscriptionobject

Contains a Company.id and an array of SubscriptionTypes for each Company.
JSON description
PropertyTypeDescription
companyuint64The company relevant to the subscription types you want to receive.
subscriptionTypesArray.<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.
ValueMessage NameMessage ObjectsDescription
assetAdvanced
  • assetAdvanced
Assets' advanced properties such as position, attributes, and status tags.
assetDispatch
  • assetDispatch
Assets' current dispatch such as DispatchJobs and route progress.
assetGeneral
  • assetDeleted
  • assetGeneral
  • assetSuspended
Assets' general properties such as name, icon, and labels.
assetMessage
  • assetMessage
  • assetMessageDeleted
  • assetPndMessage
  • assetPndMessageDeleted
AssetMessages between Assets and Users.
behaviour
  • behaviour
  • behaviourDeleted
Configured behaviours.
behaviourLog
  • behaviourLog
  • behaviourLogDeleted
Behaviour log messages to help developers debug their BehaviourScript.
behaviourScript
  • behaviourScript
  • behaviourScriptDeleted
Behaviour script logic.
billingDiscount
  • billableHostingDiscount
  • billableHostingDiscountDeleted
Discount rules for Assets.
billingHosting
  • billableHostingRule
  • billableHostingRuleDeleted
Billing rules for Assets.
billingLicense
  • billableHostingLicense
  • billableHostingLicenseDeleted
Hardware licenses for Providers.
billingProfile
  • billingProfile
  • billingProfileDeleted
Profiles used to generate BillingReport for a customer.
billingReport
  • billingReport
  • billingReportDeleted
Reports generated for a billee Company.
companyGeneral
  • companyDeleted
  • companyGeneral
Renaming and changing the nodes of a company.
companyLabels
  • companyStyles
Company's label and tag styles.
companyPolicies
  • companyPolicies
Company's SessionPolicy and PasswordPolicy.
companyReseller
  • companyReseller
  • companyResellerDeleted
A Company's white-labelling details.
contact
  • contact
  • contactDeleted
Contact information used by Assets and Users.
dispatchJob
  • dispatchJob
  • dispatchJobDeleted
Some work that needs to be done by performing one or more DispatchSteps.
dispatchTask
  • dispatchTask
  • dispatchTaskDeleted
Assets' DispatchTask information.
document
  • document
  • documentDeleted
Hosted document information.
formResult
  • formResult
  • formResultDeleted
Forms that are completed and fully filled out.
formTemplate
  • formTemplate
  • formTemplateDeleted
Customized forms to be filled.
hosCarrier
  • hosCarrier
  • hosCarrierDeleted
Hours of Service carriers.
hosEvent
  • hosEvent
Driver's E-log event records.
hosInspection
  • hosInspection
  • hosInspectionDeleted
Driver vehicle inspection reports.
icon
  • icon
  • iconDeleted
Synchronizes icon information.
machine
  • machine
  • machineDeleted
API Credentials information and permissions.
maintenanceJob
  • maintenanceJob
  • maintenanceJobDeleted
Historical Vehicle and Trailer maintenance work.
maintenanceSchedule
  • maintenanceSchedule
  • maintenanceScheduleDeleted
Recurring maintenance work for Vehicles and Trailers.
picture
  • picture
  • pictureDeleted
Synchronizes picture information.
placeGeneral
  • placeDeleted
  • placeGeneral
Place information.
providerAdvanced
  • providerAdvanced
Raw provider (device) data like GPS coordinates and parsed ODB-II values.
providerConfig
  • providerConfig
  • providerConfigDeleted
Provider (device) configurations.
providerConfiguration
Deprecated
  • providerConfiguration
  • providerConfigurationDeleted
Provider (device) configurations.
Use providerConfig instead.
providerGeneral
  • providerDeleted
  • providerGeneral
  • providerSuspended
Providers' (device) general properties such as name, notes, and selected Asset.
providerRegistration
  • providerRegistration
  • providerRegistrationDeleted
Pending Providers (devices) that have not yet been configured or provisioned.
providerScript
  • providerScript
  • providerScriptDeleted
Provider (device) script logic.
reportResult
  • reportResult
  • reportResultDeleted
Historical asset details like breadcrumb trails.
reportSchedule
  • reportSchedule
  • reportScheduleDeleted
Schedules for reports that run automatically.
reportTemplate
  • reportTemplate
  • reportTemplateDeleted
Report configurations.
userAdvanced
  • userAdvanced
User information such as permissions and group membership.
userGeneral
  • userDeleted
  • userGeneral
General user information such as name, contact information, and preferences.
userGroup
  • userGroup
  • userGroupDeleted
Group information for easy access control.

unsubscribe

Unsubscribes the socket from receiving notifications for merge/delete changes to objects.
Request message description
PropertyTypeRequiredDescription
companyParamIdalwaysAn object to contain the "id" key.
company.iduint64alwaysIdentifier given as input for the command.
reqIdint32?optionalIdentifier used by external system to correlate requests to responses.
subscriptionTypesArray.<SubscriptionType>alwaysThe list of subscription types you want to receive.
Request message structure
unsubscribe {
	"company": {
		"id": number
	},
	"reqId": number,
	"subscriptionTypes": [
		string
	]
}
Response message description
PropertyTypeDescription
companyRespIdAn 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.iduint64?Identifier given as input for the command.
deniedArray.<SubscriptionType>Subscription types not added to your socket due to insufficient permissions.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
invalidArray.<string>A returned list of nonsense you sent to my beautiful service.
mergedArray.<SubscriptionType>Subscription types added/removed (or were not applicable) to your socket's subscription list.
messagestringAn English description of the error.
reqIdint32?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 CodeDescription
3The request does not contain a company or it is invalid.
3The request does not contain a subscriptionTypes or it is invalid.
3The given subscriptionTypes is empty.
5Access was denied for all subscription types. This error is not returned if at least one subscription type succeeds.
Returns an ErrorDetailBadKeys as the errorDetails..
7You cannot execute this command because your session has expired.
8You cannot execute this command because you are not logged in.
9Your session has expired during pocessing.
16You 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
PropertyTypeRequiredDefaultDescription
assetParamIdalwaysAn object to contain the "id" of the Asset.
asset.iduint64alwaysIdentifier given as input for the command.
includeDispatchbooleanoptionalfalseWhen true, the command will also return the AssetDispatch for the asset.
includeMessagesbooleanoptionalfalseWhen true, the command will also return AssetMessages for the asset.
reqIdint32?optionalIdentifier used by external system to correlate requests to responses.
Request message structure
getAsset {
	"asset": {
		"id": number
	},
	"includeDispatch": boolean,
	"includeMessages": boolean,
	"reqId": number
}
Response message description
PropertyTypeDescription
assetAssetThe requested Asset.
asset.attributesObject.<codified, AssetAttribute>
for keys see: AssetAttribute.name
A list of attributes given to this asset by the connection device such as wiring state, VBus, etc.
asset.companyuint64The company to which this asset belongs.
asset.dispatchAssetDispatchCurrent jobs dispatched and driving directions.
asset.dispatch.companyuint64The company to which this asset belongs.
asset.dispatch.directionsArray.<DispatchDirection>Driving directions and route path details.
asset.dispatch.iduint64Unique identifier of this asset.
asset.dispatch.jobsArray.<uint64>The current list of DispatchJobs assigned to the asset.
asset.dispatch.lastDispatcheddatetimeTimestamp from the last update to this AssetDispatch by a User, Machine, Asset, or an assigned DispatchJob.
asset.dispatch.tasks
Deprecated
Array.<DispatchTask>The current list of tasks assigned to this asset.
asset.dispatch.vArray.<uint32>Object version keys used to validate synchronization for all object properties.
asset.iconuint64
see: Icon.id
The icon that represents this asset on the map and in lists.
asset.iduint64Unique identifier of this asset.
asset.kindAssetTypeType of asset.
asset.labelsArray.<codified>
for values see: LabelStyle.code
Codified label names.
asset.messagesArray.<AssetMessage>A list of messages sent to or from this asset.
asset.messagingAddressstring
maximum-length: 254
The fall-back address which is used to send Messages if the asset is a Person and has no Contact phone or email.
asset.namestring
maximum-length: 100
This thing's name.
asset.notesstringNotes about it.
asset.odometerdoubleThe cumulative distance travelled in kilometres.
asset.picturesArray.<uint64>
for values see: Picture.id
A list of photos of this thing.
asset.placesObject.<uint64, AssetPlaceStatus>
for keys see: Place.id
The current state of this asset's interaction with known Places.
asset.positionPositionThe things GPS coordinates including speed, bearing, and street information.
asset.position.accuracyuint32?Threshold in meters for the accuracy of a position
asset.position.addressstringThe road segment description
asset.position.altitudedouble?Distance in meters from the sea level
asset.position.bearinguint16?Direction of travel
asset.position.dtsdatetimeThe Date/Time of the GPS reading
asset.position.latdouble?Latitude
asset.position.lngdouble?Longitude
asset.position.originstringProvider Identifier
asset.position.speeddouble?Speed
asset.position.speedLimitdouble?The posted speed limit for the road segment
asset.position.streetAddressStreetAddressA better description of the current road-segment
asset.position.streetAddress.citystringCity name.
asset.position.streetAddress.countrystring
fixed length: 2
Country code. Codes should be a value from ISO 3166-1 alpha-2.
asset.position.streetAddress.isTollbooleanIndicates that there is a toll for the current road segment.
asset.position.streetAddress.numberstringHouse number.
asset.position.streetAddress.postalstringPostal or zip code.
asset.position.streetAddress.provincestring
fixed length: 2
Province or state code. Codes should be a value from ISO 3166-2.
asset.position.streetAddress.regionstringRegion name.
asset.position.streetAddress.streetstringFull street name.
asset.providersArray.<string>
for values see: Provider.id
The list of devices providing events for this asset.
asset.reference
Deprecated
string
maximum-length: 100
A custom field used to refer to an external system.
Use asset.references[AssetGeneral.REFERENCE] instead.
asset.referencesObject.<string, string>
maximum-count: 10
maximum-length of keys: 20
maximum-length of values: 100
Name/value collections of custom fields used to refer to external systems.
asset.relationshipsArray.<uint64>
for values see: Asset.id
A list of assets related to this one; like a Person for a Vehicle (driver).
asset.tagsArray.<codified>
for values see: LabelStyle.code
The codified status tag names.
asset.vArray.<int32>
fixed count: 3
Object version keys used to validate synchronization for all object properties.
asset.v[0]int32The first element is for the AssetGeneral properties.
asset.v[1]int32The second element is for the AssetAdvanced properties.
asset.v[2]int32The third element is for the Asset.dispatch properties.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response 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,
			"tasks": [
				{
					"address": string,
					"arrived": string,
					"asset": number,
					"attachments": [
						number
					],
					"company": number,
					"completed": string,
					"created": string,
					"duration": string,
					"eta": string,
					"id": number,
					"instructions": string,
					"latlng": {
						"lat": number,
						"lng": number
					},
					"name": string,
					"notes": string,
					"place": number,
					"reference": string,
					"references": {
						string: string
					},
					"signatory": string,
					"signature": boolean,
					"status": string,
					"v": [
						number
					]
				}
			],
			"v": [
				number
			]
		},
		"icon": number,
		"id": number,
		"kind": string,
		"labels": [
			string
		],
		"messages": [
			{
				"asset": number,
				"body": string,
				"company": number,
				"delivered": string,
				"folder": string,
				"from": string,
				"id": number,
				"incoming": boolean,
				"kind": string,
				"processed": string,
				"readBy": string,
				"status": string,
				"subject": string,
				"to": string,
				"user": string,
				"v": [
					number
				]
			}
		],
		"messagingAddress": string,
		"name": string,
		"notes": string,
		"odometer": number,
		"pictures": [
			number
		],
		"places": {
			string: {
				"enter": string,
				"kind": string,
				"latest": string
			}
		},
		"position": {
			"accuracy": number,
			"address": string,
			"altitude": number,
			"bearing": number,
			"dts": string,
			"lat": number,
			"lng": number,
			"origin": string,
			"speed": number,
			"speedLimit": number,
			"streetAddress": {
				"city": string,
				"country": string,
				"isToll": boolean,
				"number": string,
				"postal": string,
				"province": string,
				"region": string,
				"street": string
			}
		},
		"providers": [
			string
		],
		"reference": string,
		"references": {
			string: string
		},
		"relationships": [
			number
		],
		"tags": [
			string
		],
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}
Possible exceptions
Error CodeDescription
3The request does not contain a asset object, or it is invalid.
3The asset object does not contain an id, or it is invalid.
5You do not have permission to view this Asset.
7You cannot execute this command because your session has expired.
8You cannot execute this command because you are not logged in.
16You cannot execute this command because your password has expired.
20The 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
PropertyTypeRequiredDefaultDescription
companyParamIdalwaysAn object to contain the "id" of the Company.
company.iduint64alwaysIdentifier given as input for the command.
includeMessagesbooleanoptionalfalseWhen true, the command will also return AssetMessages for the asset.
includeTasksbooleanoptionalfalseWhen true, the command will also return DispatchTasks for the asset.
reqIdint32?optionalIdentifier used by external system to correlate requests to responses.
Request message structure
getAssetsList {
	"company": {
		"id": number
	},
	"includeMessages": boolean,
	"includeTasks": boolean,
	"reqId": number
}
Response message description
PropertyTypeDescription
assetsArray.<Asset>The list of requested Assets.
companyRespIdAn object to contain the "id" of the Company to which the array of Assets belong.
company.iduint64?Identifier given as input for the command.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response 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,
				"tasks": [
					{
						"address": string,
						"arrived": string,
						"asset": number,
						"attachments": [
							number
						],
						"company": number,
						"completed": string,
						"created": string,
						"duration": string,
						"eta": string,
						"id": number,
						"instructions": string,
						"latlng": {
							"lat": number,
							"lng": number
						},
						"name": string,
						"notes": string,
						"place": number,
						"reference": string,
						"references": {
							string: string
						},
						"signatory": string,
						"signature": boolean,
						"status": string,
						"v": [
							number
						]
					}
				],
				"v": [
					number
				]
			},
			"icon": number,
			"id": number,
			"kind": string,
			"labels": [
				string
			],
			"messages": [
				{
					"asset": number,
					"body": string,
					"company": number,
					"delivered": string,
					"folder": string,
					"from": string,
					"id": number,
					"incoming": boolean,
					"kind": string,
					"processed": string,
					"readBy": string,
					"status": string,
					"subject": string,
					"to": string,
					"user": string,
					"v": [
						number
					]
				}
			],
			"messagingAddress": string,
			"name": string,
			"notes": string,
			"odometer": number,
			"pictures": [
				number
			],
			"places": {
				string: {
					"enter": string,
					"kind": string,
					"latest": string
				}
			},
			"position": {
				"accuracy": number,
				"address": string,
				"altitude": number,
				"bearing": number,
				"dts": string,
				"lat": number,
				"lng": number,
				"origin": string,
				"speed": number,
				"speedLimit": number,
				"streetAddress": {
					"city": string,
					"country": string,
					"isToll": boolean,
					"number": string,
					"postal": string,
					"province": string,
					"region": string,
					"street": string
				}
			},
			"providers": [
				string
			],
			"reference": string,
			"references": {
				string: string
			},
			"relationships": [
				number
			],
			"tags": [
				string
			],
			"v": [
				number
			]
		}
	],
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}
Possible exceptions
Error CodeDescription
3The request does not contain a company object, or it is invalid.
3The company object does not contain an id, or it is invalid.
5You do not have permission to view any Assets for this Company.
7You cannot execute this command because your session has expired.
8You cannot execute this command because you are not logged in.
16You cannot execute this command because your password has expired.
28The 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
PropertyTypeRequiredDefaultDescription
companyParamIdalwaysAn object to contain the "id" of the Company.
company.iduint64alwaysIdentifier given as input for the command.
includeMessagesbooleanoptionalfalseWhen true, the command will also return AssetMessages for the asset.
includeTasksbooleanoptionalfalseWhen true, the command will also return DispatchTasks for the asset.
referencestringoptionalCase-insensitive reference used to match Assets.
reqIdint32?optionalIdentifier used by external system to correlate requests to responses.
Request message structure
getAssetsListByReference {
	"company": {
		"id": number
	},
	"includeMessages": boolean,
	"includeTasks": boolean,
	"reference": string,
	"reqId": number
}
Response message description
PropertyTypeDescription
assetsArray.<Asset>The list of requested Assets.
companyRespIdAn object to contain the "id" of the Company to which the array of Assets belong.
company.iduint64?Identifier given as input for the command.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
referencestringThe reference string given as input.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response 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,
				"tasks": [
					{
						"address": string,
						"arrived": string,
						"asset": number,
						"attachments": [
							number
						],
						"company": number,
						"completed": string,
						"created": string,
						"duration": string,
						"eta": string,
						"id": number,
						"instructions": string,
						"latlng": {
							"lat": number,
							"lng": number
						},
						"name": string,
						"notes": string,
						"place": number,
						"reference": string,
						"references": {
							string: string
						},
						"signatory": string,
						"signature": boolean,
						"status": string,
						"v": [
							number
						]
					}
				],
				"v": [
					number
				]
			},
			"icon": number,
			"id": number,
			"kind": string,
			"labels": [
				string
			],
			"messages": [
				{
					"asset": number,
					"body": string,
					"company": number,
					"delivered": string,
					"folder": string,
					"from": string,
					"id": number,
					"incoming": boolean,
					"kind": string,
					"processed": string,
					"readBy": string,
					"status": string,
					"subject": string,
					"to": string,
					"user": string,
					"v": [
						number
					]
				}
			],
			"messagingAddress": string,
			"name": string,
			"notes": string,
			"odometer": number,
			"pictures": [
				number
			],
			"places": {
				string: {
					"enter": string,
					"kind": string,
					"latest": string
				}
			},
			"position": {
				"accuracy": number,
				"address": string,
				"altitude": number,
				"bearing": number,
				"dts": string,
				"lat": number,
				"lng": number,
				"origin": string,
				"speed": number,
				"speedLimit": number,
				"streetAddress": {
					"city": string,
					"country": string,
					"isToll": boolean,
					"number": string,
					"postal": string,
					"province": string,
					"region": string,
					"street": string
				}
			},
			"providers": [
				string
			],
			"reference": string,
			"references": {
				string: string
			},
			"relationships": [
				number
			],
			"tags": [
				string
			],
			"v": [
				number
			]
		}
	],
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reference": string,
	"reqId": number
}
Possible exceptions
Error CodeDescription
3The request does not contain a company object, or it is invalid.
3The company object does not contain an id, or it is invalid.
3The reference is blank or null.
5You do not have permission to view any Assets for this Company.
7You cannot execute this command because your session has expired.
8You cannot execute this command because you are not logged in.
16You cannot execute this command because your password has expired.
28The 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
PropertyTypeRequiredDefaultDescription
companyParamIdalwaysAn object to contain the "id" of the Company.
company.iduint64alwaysIdentifier given as input for the command.
includeMessagesbooleanoptionalfalseWhen true, the command will also return AssetMessages for the asset.
includeTasksbooleanoptionalfalseWhen true, the command will also return DispatchTasks for the asset.
referencesObject.<string, string>optionalCase-insensitive reference pairs used to match Assets.
reqIdint32?optionalIdentifier used by external system to correlate requests to responses.
Request message structure
getAssetsListByReferences {
	"company": {
		"id": number
	},
	"includeMessages": boolean,
	"includeTasks": boolean,
	"references": {
		string: string
	},
	"reqId": number
}
Response message description
PropertyTypeDescription
assetsArray.<Asset>The list of requested Assets.
companyRespIdAn object to contain the "id" of the Company to which the array of Assets belong.
company.iduint64?Identifier given as input for the command.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
referencesObject.<string, string>The reference string given as input.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response 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,
				"tasks": [
					{
						"address": string,
						"arrived": string,
						"asset": number,
						"attachments": [
							number
						],
						"company": number,
						"completed": string,
						"created": string,
						"duration": string,
						"eta": string,
						"id": number,
						"instructions": string,
						"latlng": {
							"lat": number,
							"lng": number
						},
						"name": string,
						"notes": string,
						"place": number,
						"reference": string,
						"references": {
							string: string
						},
						"signatory": string,
						"signature": boolean,
						"status": string,
						"v": [
							number
						]
					}
				],
				"v": [
					number
				]
			},
			"icon": number,
			"id": number,
			"kind": string,
			"labels": [
				string
			],
			"messages": [
				{
					"asset": number,
					"body": string,
					"company": number,
					"delivered": string,
					"folder": string,
					"from": string,
					"id": number,
					"incoming": boolean,
					"kind": string,
					"processed": string,
					"readBy": string,
					"status": string,
					"subject": string,
					"to": string,
					"user": string,
					"v": [
						number
					]
				}
			],
			"messagingAddress": string,
			"name": string,
			"notes": string,
			"odometer": number,
			"pictures": [
				number
			],
			"places": {
				string: {
					"enter": string,
					"kind": string,
					"latest": string
				}
			},
			"position": {
				"accuracy": number,
				"address": string,
				"altitude": number,
				"bearing": number,
				"dts": string,
				"lat": number,
				"lng": number,
				"origin": string,
				"speed": number,
				"speedLimit": number,
				"streetAddress": {
					"city": string,
					"country": string,
					"isToll": boolean,
					"number": string,
					"postal": string,
					"province": string,
					"region": string,
					"street": string
				}
			},
			"providers": [
				string
			],
			"reference": string,
			"references": {
				string: string
			},
			"relationships": [
				number
			],
			"tags": [
				string
			],
			"v": [
				number
			]
		}
	],
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"references": {
		string: string
	},
	"reqId": number
}
Possible exceptions
Error CodeDescription
3The request does not contain a company object, or it is invalid.
3The company object does not contain an id, or it is invalid.
3The references is not an object, or it is invalid.
5You do not have permission to view any Assets for this Company.
7You cannot execute this command because your session has expired.
8You cannot execute this command because you are not logged in.
16You cannot execute this command because your password has expired.
28The Company was not found by its unique identifier.

mergeAsset

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

removeAsset

Deletes an existing Asset.
Request message description
PropertyTypeRequiredDescription
assetParamIdalwaysAn object to contain the "id" of the Asset.
asset.iduint64alwaysIdentifier given as input for the command.
reqIdint32?optionalIdentifier used by external system to correlate requests to responses.
Request message structure
removeAsset {
	"asset": {
		"id": number
	},
	"reqId": number
}
Response message description
PropertyTypeDescription
assetRespDeletedAn object which contains the Asset's id, owning Company id, and deleted status.
asset.companyuint64Identifier of the Company to which this object belongs.
asset.deletedbooleanFlag showing if the object is deleted.
asset.iduint64?Identifier given as input for the command.
asset.vArray.<uint32>
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response message structure
removeAssetResponse {
	"asset": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}
Possible exceptions
Error CodeDescription
2A communication error occurred.
If you receive this error, please contact technical support.
3The request does not contain a asset object, or it is invalid.
3The asset object does not contain an id, or it is invalid.
5You do not have permission to delete this Asset.
7You cannot execute this command because your session has expired.
8You cannot execute this command because you are not logged in.
16You cannot execute this command because your password has expired.
20The Asset was not found by its unique identifier.

restoreAsset

Restores the specified Asset.
Request message description
PropertyTypeRequiredDescription
assetParamIdalwaysAn object to contain the "id" of the Asset.
asset.iduint64alwaysIdentifier given as input for the command.
reqIdint32?optionalIdentifier used by external system to correlate requests to responses.
Request message structure
restoreAsset {
	"asset": {
		"id": number
	},
	"reqId": number
}
Response message description
PropertyTypeDescription
assetRespDeletedAn object which contains the Asset's id, owning Company id, and deleted status.
asset.companyuint64Identifier of the Company to which this object belongs.
asset.deletedbooleanFlag showing if the object is deleted.
asset.iduint64?Identifier given as input for the command.
asset.vArray.<uint32>
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response message structure
restoreAssetResponse {
	"asset": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}
Possible exceptions
Error CodeDescription
2A communication error occurred.
If you receive this error, please contact technical support.
3The request does not contain a asset object, or it is invalid.
3The asset object does not contain an id, or it is invalid.
5You do not have permission to restore this Asset.
7You cannot execute this command because your session has expired.
8You cannot execute this command because you are not logged in.
16You cannot execute this command because your password has expired.
20The Asset was not found by its unique identifier.
21The Asset was found, but is not marked as deleted.

reviveAsset

Revives (disables suspension on) an existing Asset.
Request message description
PropertyTypeRequiredDescription
assetParamIdalwaysAn object to contain the "id" of the Asset.
asset.iduint64alwaysIdentifier given as input for the command.
reqIdint32?optionalIdentifier used by external system to correlate requests to responses.
Request message structure
reviveAsset {
	"asset": {
		"id": number
	},
	"reqId": number
}
Response message description
PropertyTypeDescription
assetRespSuspendedAn object which contains the Asset's unique identifier and suspended status.
asset.companyuint64Identifier of the Company to which this object belongs.
asset.iduint64?Identifier given as input for the command.
asset.suspendedbooleanFlag showing if the object is suspended.
asset.vArray.<uint32>
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response message structure
reviveAssetResponse {
	"asset": {
		"company": number,
		"id": number,
		"suspended": boolean,
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}
Possible exceptions
Error CodeDescription
2A communication error occurred.
If you receive this error, please contact technical support.
3The request does not contain a asset object, or it is invalid.
3The asset object does not contain an id, or it is invalid.
5You do not have permission to revive this Asset.
7You cannot execute this command because your session has expired.
8You cannot execute this command because you are not logged in.
16You cannot execute this command because your password has expired.
20The Asset was not found by its unique identifier.
97The Asset was found, but is not marked as suspended.

suspendAsset

Suspends an existing Asset.
Request message description
PropertyTypeRequiredDescription
assetParamIdalwaysAn object to contain the "id" of the Asset.
asset.iduint64alwaysIdentifier given as input for the command.
reqIdint32?optionalIdentifier used by external system to correlate requests to responses.
Request message structure
suspendAsset {
	"asset": {
		"id": number
	},
	"reqId": number
}
Response message description
PropertyTypeDescription
assetRespSuspendedAn object which contains the Asset's unique identifier and suspended status.
asset.companyuint64Identifier of the Company to which this object belongs.
asset.iduint64?Identifier given as input for the command.
asset.suspendedbooleanFlag showing if the object is suspended.
asset.vArray.<uint32>
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response message structure
suspendAssetResponse {
	"asset": {
		"company": number,
		"id": number,
		"suspended": boolean,
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}
Possible exceptions
Error CodeDescription
2A communication error occurred.
If you receive this error, please contact technical support.
3The request does not contain a asset object, or it is invalid.
3The asset object does not contain an id, or it is invalid.
5You do not have permission to suspended this Asset.
7You cannot execute this command because your session has expired.
8You cannot execute this command because you are not logged in.
16You cannot execute this command because your password has expired.
20The Asset was not found by its unique identifier.
96The Asset was not found, but it is already marked as suspended.
97The 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
PropertyTypeRequiredDescription
assetParamIdalwaysAn object to contain the "id" of the Asset.
asset.iduint64alwaysIdentifier given as input for the command.
reqIdint32?optionalIdentifier used by external system to correlate requests to responses.
Request message structure
clearBehaviourLogsByAsset {
	"asset": {
		"id": number
	},
	"reqId": number
}
Response message description
PropertyTypeDescription
assetRespIdCompanyAn object to contain the "id" of the Asset to which the array of BehaviourLogs relates.
asset.companyuint64Identifier of the Company to which this object belongs.
asset.iduint64?Identifier given as input for the command.
countint32The total number of behaviour logs cleared.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response message structure
clearBehaviourLogsByAssetResponse {
	"asset": {
		"company": number,
		"id": number
	},
	"count": number,
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}
Possible exceptions
Error CodeDescription
2A communication error occurred.
If you receive this error, please contact technical support.
3The request does not contain a asset object, or it is invalid.
3The asset object does not contain an id, or it is invalid.
5You do not have permission to view this Asset.
5You do not have permission to clear Behaviours for this Asset.
7You cannot execute this command because your session has expired.
8You cannot execute this command because you are not logged in.
16You cannot execute this command because your password has expired.
20The Asset was not found by its unique identifier.

clearBehaviourLogsByBehaviour

Gets the list of BehaviourLogs for the specified Behaviour.
Request message description
PropertyTypeRequiredDescription
behaviourParamIdalwaysAn object to contain the "id" of the Behaviour.
behaviour.iduint64alwaysIdentifier given as input for the command.
reqIdint32?optionalIdentifier used by external system to correlate requests to responses.
Request message structure
clearBehaviourLogsByBehaviour {
	"behaviour": {
		"id": number
	},
	"reqId": number
}
Response message description
PropertyTypeDescription
behaviourRespIdScriptAn object to contain the "id" of the Behaviour to which the array of BehaviourLogs belong.
behaviour.companyuint64Identifier of the Company to which this object belongs.
behaviour.iduint64?Identifier given as input for the command.
behaviour.scriptuint64Identifier of the script to which this object belongs.
countint32The total number of behaviour logs cleared.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response message structure
clearBehaviourLogsByBehaviourResponse {
	"behaviour": {
		"company": number,
		"id": number,
		"script": number
	},
	"count": number,
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}
Possible exceptions
Error CodeDescription
2A communication error occurred.
If you receive this error, please contact technical support.
3The request does not contain a behaviour object, or it is invalid.
3The behaviour object does not contain an id, or it is invalid.
5You do not have permission to view BehaviourLogs for this Behaviour.
5You do not have permission to clear Behaviours for this Company.
7You cannot execute this command because your session has expired.
8You cannot execute this command because you are not logged in.
16You cannot execute this command because your password has expired.
26The Behaviour was not found by its unique identifier.

clearBehaviourLogsByScript

Gets the list of BehaviourLogs for the specified BehaviourScript.
Request message description
PropertyTypeRequiredDescription
behaviourScriptParamIdalwaysAn object to contain the "id" of the BehaviourScript.
behaviourScript.iduint64alwaysIdentifier given as input for the command.
reqIdint32?optionalIdentifier used by external system to correlate requests to responses.
Request message structure
clearBehaviourLogsByScript {
	"behaviourScript": {
		"id": number
	},
	"reqId": number
}
Response message description
PropertyTypeDescription
behaviourScriptRespIdCompanyAn object to contain the "id" of the BehaviourScript to which the array of BehaviourLogs belong.
behaviourScript.companyuint64Identifier of the Company to which this object belongs.
behaviourScript.iduint64?Identifier given as input for the command.
countint32The total number of behaviour logs cleared.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response message structure
clearBehaviourLogsByScriptResponse {
	"behaviourScript": {
		"company": number,
		"id": number
	},
	"count": number,
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}
Possible exceptions
Error CodeDescription
2A communication error occurred.
If you receive this error, please contact technical support.
3The request does not contain a behaviourScript object, or it is invalid.
3The behaviourScript object does not contain an id, or it is invalid.
5You do not have permission to view BehaviourLogs for the BehaviourScript's Company.
5You do not have permission to clear behaviours for this BehaviourScript.
7You cannot execute this command because your session has expired.
8You cannot execute this command because you are not logged in.
16You cannot execute this command because your password has expired.
23The BehaviourScript was not found by its unique identifier.

getBehaviour

Gets details of the specified Behaviour.
Request message description
PropertyTypeRequiredDescription
behaviourParamIdalwaysAn object to contain the "id" key.
behaviour.iduint64alwaysIdentifier given as input for the command.
reqIdint32?optionalIdentifier used by external system to correlate requests to responses.
Request message structure
getBehaviour {
	"behaviour": {
		"id": number
	},
	"reqId": number
}
Response message description
PropertyTypeDescription
behaviourBehaviourThe requested Behaviour.
behaviour.companyuint64The company to which this behaviour belongs.
behaviour.filtersexpressionA search pattern used to filter the providers which can implement this behaviour.
behaviour.iduint64Unique identifier of this behaviour.
behaviour.namestring
maximum-length: 100
The name of this behaviour.
behaviour.notesstringNotes.
behaviour.parametersObject.<string, BehaviourParameter>The list of defined variable name/value pairs for the script requires.
behaviour.prioritybyteThe priority flag allows you to define an execution order for all behaviours for a provider.
behaviour.scriptuint64The script which this behaviour implements.
behaviour.targetsexpressionThe search pattern used to target the assets which will embed this behaviour in their execution context.
behaviour.vArray.<uint32>Object version keys used to validate synchronization for all object properties.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response 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,
		"script": number,
		"targets": string,
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}
Possible exceptions
Error CodeDescription
3The request does not contain a behaviour object, or it is invalid.
3The behaviour object does not contain an id, or it is invalid.
5You do not have permission to view this Behaviour.
7You cannot execute this command because your session has expired.
8You cannot execute this command because you are not logged in.
16You cannot execute this command because your password has expired.
26The Behaviour was not found by its unique identifier.

getBehaviourLogsListByAsset

Gets the list of BehaviourLogs for the specified Asset.
Request message description
PropertyTypeRequiredDescription
assetParamIdalwaysAn object to contain the "id" of the Asset.
asset.iduint64alwaysIdentifier given as input for the command.
reqIdint32?optionalIdentifier used by external system to correlate requests to responses.
Request message structure
getBehaviourLogsListByAsset {
	"asset": {
		"id": number
	},
	"reqId": number
}
Response message description
PropertyTypeDescription
assetRespIdCompanyAn object to contain the "id" of the Asset to which the array of BehaviourLogs relates.
asset.companyuint64Identifier of the Company to which this object belongs.
asset.iduint64?Identifier given as input for the command.
behaviourLogsArray.<BehaviourLog>The list of requested BehaviourLogs.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response 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,
			"script": number,
			"v": [
				number
			]
		}
	],
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}
Possible exceptions
Error CodeDescription
2A communication error occurred.
If you receive this error, please contact technical support.
3The request does not contain a asset object, or it is invalid.
3The asset object does not contain an id, or it is invalid.
5You do not have permission to view this Asset.
5You do not have permission to view BehaviourLogs for this Asset's Company.
7You cannot execute this command because your session has expired.
8You cannot execute this command because you are not logged in.
16You cannot execute this command because your password has expired.
20The Asset was not found by its unique identifier.

getBehaviourLogsListByBehaviour

Gets the list of BehaviourLog for the specified Behaviour.
Request message description
PropertyTypeRequiredDescription
behaviourParamIdalwaysAn object to contain the "id" of the Behaviour.
behaviour.iduint64alwaysIdentifier given as input for the command.
reqIdint32?optionalIdentifier used by external system to correlate requests to responses.
Request message structure
getBehaviourLogsListByBehaviour {
	"behaviour": {
		"id": number
	},
	"reqId": number
}
Response message description
PropertyTypeDescription
behaviourRespIdScriptAn object to contain the "id" of the Behaviour to which the array of BehaviourLogs belong.
behaviour.companyuint64Identifier of the Company to which this object belongs.
behaviour.iduint64?Identifier given as input for the command.
behaviour.scriptuint64Identifier of the script to which this object belongs.
behaviourLogsArray.<BehaviourLog>The list of requested BehaviourLogs.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response 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,
			"script": number,
			"v": [
				number
			]
		}
	],
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}
Possible exceptions
Error CodeDescription
2A communication error occurred.
If you receive this error, please contact technical support.
3The request does not contain a behaviour object, or it is invalid.
3The behaviour object does not contain an id, or it is invalid.
5You do not have permission to view BehaviourLogs for this Behaviour.
5You do not have permission to view Behaviours for this Company.
7You cannot execute this command because your session has expired.
8You cannot execute this command because you are not logged in.
16You cannot execute this command because your password has expired.
26The Behaviour was not found by its unique identifier.

getBehaviourLogsListByScript

Gets the list of BehaviourLogs for the specified BehaviourScript.
Request message description
PropertyTypeRequiredDescription
behaviourScriptParamIdalwaysAn object to contain the "id" of the BehaviourScript.
behaviourScript.iduint64alwaysIdentifier given as input for the command.
reqIdint32?optionalIdentifier used by external system to correlate requests to responses.
Request message structure
getBehaviourLogsListByScript {
	"behaviourScript": {
		"id": number
	},
	"reqId": number
}
Response message description
PropertyTypeDescription
behaviourLogsArray.<BehaviourLog>The list of requested BehaviourLogs.
behaviourScriptRespIdCompanyAn object to contain the "id" of the BehaviourScript to which the array of BehaviourLogs belong.
behaviourScript.companyuint64Identifier of the Company to which this object belongs.
behaviourScript.iduint64?Identifier given as input for the command.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response message structure
getBehaviourLogsListByScriptResponse {
	"behaviourLogs": [
		{
			"asset": number,
			"behaviour": number,
			"character": number,
			"company": number,
			"dts": string,
			"id": number,
			"kind": string,
			"line": number,
			"message": string,
			"script": number,
			"v": [
				number
			]
		}
	],
	"behaviourScript": {
		"company": number,
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}
Possible exceptions
Error CodeDescription
2A communication error occurred.
If you receive this error, please contact technical support.
3The request does not contain a behaviourScript object, or it is invalid.
3The behaviourScript object does not contain an id, or it is invalid.
5You do not have permission to view BehaviourLogs for the BehaviourScript's Company.
5You do not have permission to view BehaviourScripts for this Company.
7You cannot execute this command because your session has expired.
8You cannot execute this command because you are not logged in.
16You cannot execute this command because your password has expired.
23The BehaviourScript was not found by its unique identifier.

getBehaviourScript

Gets details of the specified BehaviourScript.
Request message description
PropertyTypeRequiredDescription
behaviourScriptParamIdalwaysAn object to contain the "id" key.
behaviourScript.iduint64alwaysIdentifier given as input for the command.
reqIdint32?optionalIdentifier used by external system to correlate requests to responses.
Request message structure
getBehaviourScript {
	"behaviourScript": {
		"id": number
	},
	"reqId": number
}
Response message description
PropertyTypeDescription
behaviourScriptBehaviourScriptThe requested BehaviourScript.
behaviourScript.companyuint64The company to which this script belongs.
behaviourScript.compilesbooleanFlag set by the compiler if this code compiles
behaviourScript.fillcolour
maximum-length: 22
The background colour given to this script for easy visual identification.
behaviourScript.filtersexpressionA list of targeting expressions. These expressions are defaults for derived Behaviours.
behaviourScript.globalbooleanIndicates whether this script is available to child companies.
behaviourScript.graphiccodified
maximum-length: 22
The codified graphic name given to this script for easy visual identification.
behaviourScript.iduint64Unique identifier of this script.
behaviourScript.namestring
maximum-length: 100
The nickname given to this script.
behaviourScript.notesstringUsage notes and instructions for users on how best to setup this script.
behaviourScript.parametersObject.<string, BehaviourParameter>Listed parameters for the Behaviour function.
behaviourScript.sourcestring
maximum-length: 8060
The source code.
behaviourScript.strokecolour
maximum-length: 22
The text/graphic colour given to this script for easy visual identification.
behaviourScript.vArray.<uint32>Object version keys used to validate synchronization for all object properties.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response 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
			}
		},
		"source": string,
		"stroke": string,
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}
Possible exceptions
Error CodeDescription
3The request does not contain a behaviourScript object, or it is invalid.
3The behaviourScript object does not contain an id, or it is invalid.
5You do not have permission to view this BehaviourScript.
7You cannot execute this command because your session has expired.
8You cannot execute this command because you are not logged in.
16You cannot execute this command because your password has expired.
23The BehaviourScript was not found by its unique identifier.

getBehaviourScriptsList

Gets the list of BehaviourScripts for the specified Company.
Request message description
PropertyTypeRequiredDescription
companyParamIdalwaysAn object to contain the "id" of the Company.
company.iduint64alwaysIdentifier given as input for the command.
reqIdint32?optionalIdentifier used by external system to correlate requests to responses.
treebooleanoptionalWhen 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
	},
	"reqId": number,
	"tree": boolean
}
Response message description
PropertyTypeDescription
behaviourScriptsArray.<BehaviourScript>The list of requested BehaviourScripts.
companyRespIdAn object to contain the "id" of the Company to which the array of BehaviourScripts belong.
company.iduint64?Identifier given as input for the command.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response 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
				}
			},
			"source": string,
			"stroke": string,
			"v": [
				number
			]
		}
	],
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}
Possible exceptions
Error CodeDescription
2A communication error occurred.
If you receive this error, please contact technical support.
3The request does not contain a company object, or it is invalid.
3The company object does not contain an id, or it is invalid.
5You do not have permission to view BehaviourScripts for this Company.
7You cannot execute this command because your session has expired.
8You cannot execute this command because you are not logged in.
16You cannot execute this command because your password has expired.
28The Company was not found by its unique identifier.

getBehavioursList

Gets the list of Behaviours for the specified Company.
Request message description
PropertyTypeRequiredDescription
companyParamIdalwaysAn object to contain the "id" of the Company.
company.iduint64alwaysIdentifier given as input for the command.
reqIdint32?optionalIdentifier used by external system to correlate requests to responses.
Request message structure
getBehavioursList {
	"company": {
		"id": number
	},
	"reqId": number
}
Response message description
PropertyTypeDescription
behavioursArray.<Behaviour>The list of reqested Behaviours.
companyRespIdAn object to contain the "id" of the Company to which the array of Behaviours belong.
company.iduint64?Identifier given as input for the command.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response 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,
			"script": number,
			"targets": string,
			"v": [
				number
			]
		}
	],
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}
Possible exceptions
Error CodeDescription
2A communication error occurred.
If you receive this error, please contact technical support.
3The request does not contain a company object, or it is invalid.
3The company object does not contain an id, or it is invalid.
5You do not have permission to view this Company.
5You do not have permission to view Behaviours for this Company.
7You cannot execute this command because your session has expired.
8You cannot execute this command because you are not logged in.
16You cannot execute this command because your password has expired.
28The Company was not found by its unique identifier.

mergeBehaviour

Creates a new or updates an existing Behaviour.
Request message description
PropertyTypeRequiredDescription
behaviourObject.<string, ?>alwaysA simple object to contain the Behaviour parameters.
behaviour.companyuint64?create
behaviour.filtersexpressionoptionalA search pattern used to select the assets which will embed this Behaviour in their execution context.
behaviour.iduint64?updateThe unique identifier of the Behaviour you want to update.
behaviour.namestring
maximum-length: 100
createName for the Behaviour.
behaviour.notesstringoptionalNotes for the Behaviour.
behaviour.parametersObject.<string, BehaviourParameter>optionalThe values needed to implement the script. Each key in this object is the name of a required script argument.
behaviour.prioritybyte?optionalThe order in which this Behaviour is executed.
behaviour.scriptuint64?createIdentifier of the BehaviourScript to which this Behaviour belongs. After creation, this value is read-only.
behaviour.targetsexpressionoptionalA search pattern used to select the providers which can implement this Behaviour.
behaviour.vArray.<int32>optional
reqIdint32?optionalIdentifier used by external system to correlate requests to responses.
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
PropertyTypeDescription
behaviourRespIdScriptAn object which contains the "id", "company", and "script" keys when there is no error.
behaviour.companyuint64Identifier of the Company to which this object belongs.
behaviour.iduint64?Identifier given as input for the command.
behaviour.scriptuint64Identifier of the script to which this object belongs.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response message structure
mergeBehaviourResponse {
	"behaviour": {
		"company": number,
		"id": number,
		"script": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}
Possible exceptions
Error CodeDescription
2A communication error occurred.
If you receive this error, please contact technical support.
3The request does not contain a behaviour object, or it is invalid.
3Not enough keys exist in the behaviour object.
3During create: When creating a new Behaviour, a name was not given, or it is invalid.
3During create: When creating a new Behaviour, a script was not given.
3During create: When creating a new Behaviour, a company was not given.
3During update: When updating a Behaviour, the id was invalid.
3During update: When updating a Behaviour, the name was given as blank.
3During update: When updating a Behaviour, the v was not an array, or contained too few numbers.
3The 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..
3One of the behaviour.parameters was invalid.
Returns an ErrorDetailInput as the errorDetails..
3One of the behaviour.parameters keys was blank or white-space.
Returns an ErrorDetailInput as the errorDetails..
5You do not have permission to create a new Behaviour.
5You do not have permission to update this Behaviour.
6During update: When updating a Behaviour, an incorrect v value was given as input.
7You cannot execute this command because your session has expired.
8You cannot execute this command because you are not logged in.
16You cannot execute this command because your password has expired.
23During update: The BehaviourScript was not found by its unique identifier.
26During update: The Behaviour was not found by its unique identifier.
130There is one or more missing or invalid parameters required by the BehaviourScript.
Returns an ErrorDetailBadKeys as the errorDetails..
130During update: When updating a Behaviour, the behaviour.script can not be changed.
Returns an ErrorDetailBadKeys as the errorDetails..
130During 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
PropertyTypeRequiredDescription
behaviourScriptObject.<string, ?>alwaysA simple object to contain the BehaviourScript parameters.
behaviourScript.companyuint64?createIdentifier of the Company to which this BehaviourScript belongs. After creation, this value is read-only.
behaviourScript.fillstringoptionalBackground and fill colour in the UI.
behaviourScript.filtersexpressionoptionalA search pattern used to select the providers.
behaviourScript.globalbooleanoptionalWhen set to true, this Company as well as all child companies will be able to implement this BehaviourScript for that companies assets.
behaviourScript.graphicstringoptionalThe name of the symbol shown in the UI.
behaviourScript.iduint64?updateThe unique identifier of the BehaviourScript you want to update.
behaviourScript.namestring
maximum-length: 100
createName for the BehaviourScript.
behaviourScript.notesstringoptionalNotes for the BehaviourScript.
behaviourScript.parametersObject.<string, BehaviourParameter>optionalThe defined arguments for this BehaviourScript. Each key in the object is the name of an argument.
behaviourScript.sourcestringcreateSource code of the BehaviourScript.
behaviourScript.strokestringoptionalText and outline colour in the UI.
behaviourScript.vArray.<int32>optional
reqIdint32?optionalIdentifier used by external system to correlate requests to responses.
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
PropertyTypeDescription
behaviourScriptRespIdCompanyAn object which contains the "id" and "company" keys when there is no error.
behaviourScript.companyuint64Identifier of the Company to which this object belongs.
behaviourScript.iduint64?Identifier given as input for the command.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response message structure
mergeBehaviourScriptResponse {
	"behaviourScript": {
		"company": number,
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}
Possible exceptions
Error CodeDescription
2A communication error occurred.
If you receive this error, please contact technical support.
3The request does not contain a behaviourScript object, or it is invalid.
3Not enough keys exist in the behaviourScript object.
3During create: When creating a new BehaviourScript, a name was not given, or it is invalid.
3During create: When creating a new BehaviourScript, a company was not given.
3During create: When creating a new BehaviourScript, the source was not given, or it is blank.
3During update: When updating a BehaviourScript, the id was invalid.
3During update: When updating a BehaviourScript, the name was given as blank.
3During update: When updating a BehaviourScript, the v was not an array, or contained too few numbers.
3One of the behaviourScript.parameters default values' was not valid.
Returns an ErrorDetailBadKeys as the errorDetails..
3One of the behaviourScript.parameters was invalid.
Returns an ErrorDetailInput as the errorDetails..
3One of the behaviourScript.parameters keys was blank or white-space.
Returns an ErrorDetailInput as the errorDetails..
5You do not have permission to create a new BehaviourScript.
5You do not have permission to update this BehaviourScript.
6During update: When updating a BehaviourScript, an incorrect v value was given as input.
7You cannot execute this command because your session has expired.
8You cannot execute this command because you are not logged in.
16You cannot execute this command because your password has expired.
23During update: The BehaviourScript was not found by its unique identifier.
25During 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..
130During update: When updating a BehaviourScript, the behaviourScript.company can not be changed.

removeBehaviour

Deletes a Behaviour.
Request message description
PropertyTypeRequiredDescription
behaviourParamIdalwaysAn object to contain the "id" key.
behaviour.iduint64alwaysIdentifier given as input for the command.
reqIdint32?optionalIdentifier used by external system to correlate requests to responses.
Request message structure
removeBehaviour {
	"behaviour": {
		"id": number
	},
	"reqId": number
}
Response message description
PropertyTypeDescription
behaviourRespDeletedAn object which contains the Behaviour's id, owning Company id, and deleted status.
behaviour.companyuint64Identifier of the Company to which this object belongs.
behaviour.deletedbooleanFlag showing if the object is deleted.
behaviour.iduint64?Identifier given as input for the command.
behaviour.vArray.<uint32>
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response message structure
removeBehaviourResponse {
	"behaviour": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}
Possible exceptions
Error CodeDescription
2A communication error occurred.
If you receive this error, please contact technical support.
3The request does not contain a behaviour object, or it is invalid.
3The behaviour object does not contain an id, or it is invalid.
5You do not have permission to delete this Behaviour.
7You cannot execute this command because your session has expired.
8You cannot execute this command because you are not logged in.
16You cannot execute this command because your password has expired.
26The Behaviour was not found by its unique identifier.

removeBehaviourScript

Deletes an existing BehaviourScript.
Request message description
PropertyTypeRequiredDescription
behaviourScriptParamIdalwaysAn object to contain the "id" key.
behaviourScript.iduint64alwaysIdentifier given as input for the command.
reqIdint32?optionalIdentifier used by external system to correlate requests to responses.
Request message structure
removeBehaviourScript {
	"behaviourScript": {
		"id": number
	},
	"reqId": number
}
Response message description
PropertyTypeDescription
behaviourScriptRespDeletedAn object which contains the BehaviourScript's id, owning Company id, and deleted status.
behaviourScript.companyuint64Identifier of the Company to which this object belongs.
behaviourScript.deletedbooleanFlag showing if the object is deleted.
behaviourScript.iduint64?Identifier given as input for the command.
behaviourScript.vArray.<uint32>
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response message structure
removeBehaviourScriptResponse {
	"behaviourScript": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}
Possible exceptions
Error CodeDescription
2A communication error occurred.
If you receive this error, please contact technical support.
3The request does not contain a behaviourScript object, or it is invalid.
3The behaviourScript object does not contain an id, or it is invalid.
5You do not have permission to delete this BehaviourScript.
7You cannot execute this command because your session has expired.
8You cannot execute this command because you are not logged in.
16You cannot execute this command because your password has expired.
23The BehaviourScript was not found by its unique identifier.
25This BehaviourScript is still being used by one of more Behaviours.
Returns an ErrorDetailCount as the errorDetails..

restoreBehaviour

Restores a deleted Behaviour.
Request message description
PropertyTypeRequiredDescription
behaviourParamIdalwaysAn object to contain the "id" key.
behaviour.iduint64alwaysIdentifier given as input for the command.
reqIdint32?optionalIdentifier used by external system to correlate requests to responses.
Request message structure
restoreBehaviour {
	"behaviour": {
		"id": number
	},
	"reqId": number
}
Response message description
PropertyTypeDescription
behaviourRespDeletedAn object which contains the Behaviour's id, owning Company id, and deleted status.
behaviour.companyuint64Identifier of the Company to which this object belongs.
behaviour.deletedbooleanFlag showing if the object is deleted.
behaviour.iduint64?Identifier given as input for the command.
behaviour.vArray.<uint32>
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response message structure
restoreBehaviourResponse {
	"behaviour": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}
Possible exceptions
Error CodeDescription
2A communication error occurred.
If you receive this error, please contact technical support.
3The request does not contain a behaviour object, or it is invalid.
3The behaviour object does not contain an id, or it is invalid.
5You do not have permission to restore this Behaviour.
7You cannot execute this command because your session has expired.
8You cannot execute this command because you are not logged in.
16You cannot execute this command because your password has expired.
26The Behaviour was not found by its unique identifier.
27The Behaviour was found, but is not marked as deleted.

restoreBehaviourScript

Restores the specified BehaviourScript.
Request message description
PropertyTypeRequiredDescription
behaviourScriptParamIdalwaysAn object to contain the "id" key.
behaviourScript.iduint64alwaysIdentifier given as input for the command.
reqIdint32?optionalIdentifier used by external system to correlate requests to responses.
Request message structure
restoreBehaviourScript {
	"behaviourScript": {
		"id": number
	},
	"reqId": number
}
Response message description
PropertyTypeDescription
behaviourScriptRespDeletedAn object which contains the BehaviourScript's id, owning Company id, and deleted status.
behaviourScript.companyuint64Identifier of the Company to which this object belongs.
behaviourScript.deletedbooleanFlag showing if the object is deleted.
behaviourScript.iduint64?Identifier given as input for the command.
behaviourScript.vArray.<uint32>
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response message structure
restoreBehaviourScriptResponse {
	"behaviourScript": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}
Possible exceptions
Error CodeDescription
2A communication error occurred.
If you receive this error, please contact technical support.
3The request does not contain a behaviourScript object, or it is invalid.
3The behaviourScript object does not contain an id, or it is invalid.
5You do not have permission to restore this BehaviourScript.
7You cannot execute this command because your session has expired.
8You cannot execute this command because you are not logged in.
16You cannot execute this command because your password has expired.
23The BehaviourScript was not found by its unique identifier.
24The BehaviourScript was found, but is not marked as deleted.

Billing

getBillingProfile

Gets details of the specified BillingProfile.
Request message description
PropertyTypeRequiredDescription
billingProfileParamIdalwaysAn object to contain the "id" of the BillingProfile.
billingProfile.iduint64alwaysIdentifier given as input for the command.
reqIdint32?optionalIdentifier used by external system to correlate requests to responses.
Request message structure
getBillingProfile {
	"billingProfile": {
		"id": number
	},
	"reqId": number
}
Response message description
PropertyTypeDescription
billingProfileBillingProfileThe requested BillingProfile.
billingProfile.billeeuint64Unique identifier of the Company receiving the bill. Most of the time, this value is the same as the target.
billingProfile.companyuint64Unique identifier of the Company that owns this profile and is sending the bill.
billingProfile.currencyBillingCurrencykind of money
billingProfile.cycleBillingCycleRepeating cycle used for generating bills
billingProfile.cycleEnddatetimeWhen should the cycle end (customer cancelled)
billingProfile.cyclePostDatedbooleanPro-rated, or post-dated.
billingProfile.cycleStartdatetimeWhen is the first day of the billing cycle
billingProfile.googleServicesEnabledbooleanAre the Google services available to be proxied by the service?
billingProfile.iduint64Unique identifier of this billing profile
billingProfile.messagesArray.<BillableSmsProfile>SMS messaging tiers
billingProfile.namestring
maximum-length: 254
The name for this profile
billingProfile.notesstring
maximum-length: 1000
Notes about the billing profile for the billee or target.
billingProfile.targetuint64Unique identifier of the Company to which this rule pertains.
billingProfile.vArray.<uint32>Object version keys used to validate synchronization for all object properties.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response 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,
		"target": number,
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}
Possible exceptions
Error CodeDescription
3The request does not contain a billingProfile object, or it is invalid.
3The requested billingProfile id was invalid.
5You do not have permission to view this Company's BillingProfiles.
7You cannot execute this command because your session has expired.
8You cannot execute this command because you are not logged in.
16You cannot execute this command because your password has expired.
111The BillingProfile was not found by its unique identifier.

getBillingProfilesList

Gets the list of BillingProfiles for the specified Company.
Request message description
PropertyTypeRequiredDescription
companyParamIdalwaysAn object to contain the "id" of the Company.
company.iduint64alwaysIdentifier given as input for the command.
reqIdint32?optionalIdentifier used by external system to correlate requests to responses.
Request message structure
getBillingProfilesList {
	"company": {
		"id": number
	},
	"reqId": number
}
Response message description
PropertyTypeDescription
billingProfilesArray.<BillingProfile>The list of requested BillingProfiles.
companyRespIdAn object to contain the "id" of the Company to which the array of BillingProfiles belong.
company.iduint64?Identifier given as input for the command.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response 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,
			"target": number,
			"v": [
				number
			]
		}
	],
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}
Possible exceptions
Error CodeDescription
2A communication error occurred.
If you receive this error, please contact technical support.
3The request does not contain a company object, or it is invalid.
3The company object does not contain an id, or it is invalid.
5You do not have permission to view this Company's BillingProfiles.
7You cannot execute this command because your session has expired.
8You cannot execute this command because you are not logged in.
16You cannot execute this command because your password has expired.
28The Company was not found by its unique identifier.

getBillingReport

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

getBillingReportsList

Gets the list of BillingReports for the specified BillingProfile.
Request message description
PropertyTypeRequiredDescription
billingProfileParamIdalwaysAn object to contain the "id" of the BillingProfile.
billingProfile.iduint64alwaysIdentifier given as input for the command.
reqIdint32?optionalIdentifier used by external system to correlate requests to responses.
Request message structure
getBillingReportsList {
	"billingProfile": {
		"id": number
	},
	"reqId": number
}
Response message description
PropertyTypeDescription
billingProfileRespIdCompanyAn object to contain the "id" of the BillingProfile to which the array of BillableHostingRules belong.
billingProfile.companyuint64Identifier of the Company to which this object belongs.
billingProfile.iduint64?Identifier given as input for the command.
billingReportsArray.<BillingReport>The list of requested BillingReports.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response message structure
getBillingReportsListResponse {
	"billingProfile": {
		"company": number,
		"id": number
	},
	"billingReports": [
		{
			"billee": number,
			"company": number,
			"currency": string,
			"endDate": string,
			"error": string,
			"hostingBreakdown": {
				string: [
					{
						"asset": number,
						"billableDays": number,
						"cost": number,
						"created": string,
						"deleted": string,
						"discount": number,
						"labels": [
							string
						],
						"name": string,
						"notes": string,
						"phoneNumbers": [
							number
						],
						"providers": [
							string
						],
						"suspended": string,
						"suspendedCost": number,
						"suspendedDays": number,
						"suspendedDiscount": number,
						"total": number,
						"updatedDts": string
					}
				]
			},
			"id": number,
			"name": string,
			"notes": string,
			"profile": number,
			"startDate": string,
			"status": string,
			"summary": [
				{
					"hostingSummary": [
						{
							"count": number,
							"kind": string,
							"total": number
						}
					],
					"name": string,
					"notes": string,
					"parent": number,
					"target": number
				}
			],
			"total": number,
			"v": [
				number
			]
		}
	],
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}
Possible exceptions
Error CodeDescription
2A communication error occurred.
If you receive this error, please contact technical support.
3The request does not contain a billingProfile object, or it is invalid.
3The billingProfile object does not contain an id, or it is invalid.
5You do not have permission to view this Company's BillingReports.
7You cannot execute this command because your session has expired.
8You cannot execute this command because you are not logged in.
16You cannot execute this command because your password has expired.
28The Company was not found by its unique identifier.
111The BillingProfile was not found by its unique identifier.

getBillingReportsListByCompany

Gets the list of BillingReports for the specified Company.
Request message description
PropertyTypeRequiredDescription
companyParamIdalwaysAn object to contain the "id" of the Company.
company.iduint64alwaysIdentifier given as input for the command.
reqIdint32?optionalIdentifier used by external system to correlate requests to responses.
Request message structure
getBillingReportsListByCompany {
	"company": {
		"id": number
	},
	"reqId": number
}
Response message description
PropertyTypeDescription
billingReportsArray.<BillingReport>The list of requested BillingReports.
companyRespIdAn object to contain the "id" of the Company to which the array of BillingReports belong.
company.iduint64?Identifier given as input for the command.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response message structure
getBillingReportsListByCompanyResponse {
	"billingReports": [
		{
			"billee": number,
			"company": number,
			"currency": string,
			"endDate": string,
			"error": string,
			"hostingBreakdown": {
				string: [
					{
						"asset": number,
						"billableDays": number,
						"cost": number,
						"created": string,
						"deleted": string,
						"discount": number,
						"labels": [
							string
						],
						"name": string,
						"notes": string,
						"phoneNumbers": [
							number
						],
						"providers": [
							string
						],
						"suspended": string,
						"suspendedCost": number,
						"suspendedDays": number,
						"suspendedDiscount": number,
						"total": number,
						"updatedDts": string
					}
				]
			},
			"id": number,
			"name": string,
			"notes": string,
			"profile": number,
			"startDate": string,
			"status": string,
			"summary": [
				{
					"hostingSummary": [
						{
							"count": number,
							"kind": string,
							"total": number
						}
					],
					"name": string,
					"notes": string,
					"parent": number,
					"target": number
				}
			],
			"total": number,
			"v": [
				number
			]
		}
	],
	"company": {
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}
Possible exceptions
Error CodeDescription
2A communication error occurred.
If you receive this error, please contact technical support.
3The request does not contain a company object, or it is invalid.
3The company object does not contain an id, or it is invalid.
5You do not have permission to view this Company's BillingReports.
7You cannot execute this command because your session has expired.
8You cannot execute this command because you are not logged in.
16You cannot execute this command because your password has expired.
28The Company was not found by its unique identifier.

getHostingDiscount

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

getHostingDiscountsList

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

getHostingLicense

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

getHostingLicensesList

Gets the list of BillableHostingLicenses for the specified BillingProfile.
Request message description
PropertyTypeRequiredDescription
billingProfileParamIdalwaysAn object to contain the "id" of the BillingProfile.
billingProfile.iduint64alwaysIdentifier given as input for the command.
reqIdint32?optionalIdentifier used by external system to correlate requests to responses.
Request message structure
getHostingLicensesList {
	"billingProfile": {
		"id": number
	},
	"reqId": number
}
Response message description
PropertyTypeDescription
billingProfileRespIdCompanyAn object to contain the "id" of the BillingProfile to which the array of BillableHostingLicenses belong.
billingProfile.companyuint64Identifier of the Company to which this object belongs.
billingProfile.iduint64?Identifier given as input for the command.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
hostingLicensesArray.<BillableHostingLicense>The list of BillableHostingLicenses.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response 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,
			"profile": number,
			"reference": string,
			"start": string,
			"suspended": boolean,
			"targets": string,
			"v": [
				number
			]
		}
	],
	"message": string,
	"reqId": number
}
Possible exceptions
Error CodeDescription
2A communication error occurred.
If you receive this error, please contact technical support.
3The request does not contain a billingProfile object, or it is invalid.
3The billingProfile object does not contain an id, or it is invalid.
5You do not have permission to view this Company's BillableHostingLicenses.
7You cannot execute this command because your session has expired.
8You cannot execute this command because you are not logged in.
16You cannot execute this command because your password has expired.
28The Company was not found by its unique identifier.
If you receive this error, please contact technical support.
111The BillingProfile was not found by its unique identifier.

getHostingRule

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

getHostingRulesList

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

mergeBillingProfile

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

mergeHostingDiscount

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

mergeHostingLicense

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

mergeHostingRule

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

removeBillingProfile

Deletes an existing BillingProfile.
Request message description
PropertyTypeRequiredDescription
billingProfileParamIdalwaysAn object to contain the "id" of the BillingProfile.
billingProfile.iduint64alwaysIdentifier given as input for the command.
reqIdint32?optionalIdentifier used by external system to correlate requests to responses.
Request message structure
removeBillingProfile {
	"billingProfile": {
		"id": number
	},
	"reqId": number
}
Response message description
PropertyTypeDescription
billingProfileRespDeletedAn object which contains the BillingProfile's unique identifier and deleted status.
billingProfile.companyuint64Identifier of the Company to which this object belongs.
billingProfile.deletedbooleanFlag showing if the object is deleted.
billingProfile.iduint64?Identifier given as input for the command.
billingProfile.vArray.<uint32>
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response message structure
removeBillingProfileResponse {
	"billingProfile": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}
Possible exceptions
Error CodeDescription
2A communication error occurred, the BillingProfile was not deleted.
If you receive this error, please contact technical support.
3The request does not contain a billingProfile object, or it is invalid.
3The requested billingProfile id was invalid.
5You do not have permission to delete this Company's BillingProfiles.
7You cannot execute this command because your session has expired.
8You cannot execute this command because you are not logged in.
16You cannot execute this command because your password has expired.
111The BillingProfile was not found by its unique identifier.

removeBillingReport

Deletes an existing BillingReport.
Request message description
PropertyTypeRequiredDescription
billingReportParamIdalwaysAn object to contain the "id" of the BillingReport.
billingReport.iduint64alwaysIdentifier given as input for the command.
reqIdint32?optionalIdentifier used by external system to correlate requests to responses.
Request message structure
removeBillingReport {
	"billingReport": {
		"id": number
	},
	"reqId": number
}
Response message description
PropertyTypeDescription
billingReportRespDeletedAn object which contains the BillingReport's unique identifier and deleted status.
billingReport.companyuint64Identifier of the Company to which this object belongs.
billingReport.deletedbooleanFlag showing if the object is deleted.
billingReport.iduint64?Identifier given as input for the command.
billingReport.vArray.<uint32>
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response message structure
removeBillingReportResponse {
	"billingReport": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}
Possible exceptions
Error CodeDescription
2A communication error occurred, the BillingReport was not deleted.
If you receive this error, please contact technical support.
3The request does not contain a billingReport object, or it is invalid.
3The requested billingReport id was invalid.
5You do not have permission to delete this Company's BillingReports.
7You cannot execute this command because your session has expired.
8You cannot execute this command because you are not logged in.
16You cannot execute this command because your password has expired.
119The BillingReport was not found by its unique identifier.

removeHostingDiscount

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

removeHostingLicense

Deletes an existing BillableHostingLicense.
Request message description
PropertyTypeRequiredDescription
hostingLicenseParamIdalwaysAn object to contain the "id" of the BillableHostingLicense.
hostingLicense.iduint64alwaysIdentifier given as input for the command.
reqIdint32?optionalIdentifier used by external system to correlate requests to responses.
Request message structure
removeHostingLicense {
	"hostingLicense": {
		"id": number
	},
	"reqId": number
}
Response message description
PropertyTypeDescription
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
hostingLicenseRespDeletedAn object which contains the BillableHostingLicense's unique identifier and deleted status.
hostingLicense.companyuint64Identifier of the Company to which this object belongs.
hostingLicense.deletedbooleanFlag showing if the object is deleted.
hostingLicense.iduint64?Identifier given as input for the command.
hostingLicense.vArray.<uint32>
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response message structure
removeHostingLicenseResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"hostingLicense": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"message": string,
	"reqId": number
}
Possible exceptions
Error CodeDescription
2A communication error occurred, the BillableHostingLicense was not deleted.
If you receive this error, please contact technical support.
3The request does not contain a hostingLicense object, or it is invalid.
3The requested hostingLicense id was invalid.
5You do not have permission to delete this Company's BillableHostingLicenses.
7You cannot execute this command because your session has expired.
8You cannot execute this command because you are not logged in.
16You cannot execute this command because your password has expired.
117The BillableHostingLicense was not found by its unique identifier.

removeHostingRule

Deletes an existing BillableHostingRule.
Request message description
PropertyTypeRequiredDescription
hostingRuleParamIdalwaysAn object to contain the "id" of the BillableHostingRule.
hostingRule.iduint64alwaysIdentifier given as input for the command.
reqIdint32?optionalIdentifier used by external system to correlate requests to responses.
Request message structure
removeHostingRule {
	"hostingRule": {
		"id": number
	},
	"reqId": number
}
Response message description
PropertyTypeDescription
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
hostingRuleRespDeletedAn object which contains the BillableHostingRule's unique identifier and deleted status.
hostingRule.companyuint64Identifier of the Company to which this object belongs.
hostingRule.deletedbooleanFlag showing if the object is deleted.
hostingRule.iduint64?Identifier given as input for the command.
hostingRule.vArray.<uint32>
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response message structure
removeHostingRuleResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"hostingRule": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"message": string,
	"reqId": number
}
Possible exceptions
Error CodeDescription
2A communication error occurred, the BillableHostingRule was not deleted.
If you receive this error, please contact technical support.
3The request does not contain a hostingRule object, or it is invalid.
3The requested hostingRule id was invalid.
5You do not have permission to delete this Company's BillableHostingRules.
7You cannot execute this command because your session has expired.
8You cannot execute this command because you are not logged in.
16You cannot execute this command because your password has expired.
113The BillableHostingRule was not found by its unique identifier.

restoreBillingProfile

Restores the specified BillingProfile to its previous version.
Request message description
PropertyTypeRequiredDescription
billingProfileParamIdalwaysAn object to contain the "id" of the BillingProfile.
billingProfile.iduint64alwaysIdentifier given as input for the command.
reqIdint32?optionalIdentifier used by external system to correlate requests to responses.
Request message structure
restoreBillingProfile {
	"billingProfile": {
		"id": number
	},
	"reqId": number
}
Response message description
PropertyTypeDescription
billingProfileRespDeletedAn object which contains the BillingProfile's unique identifier and deleted status.
billingProfile.companyuint64Identifier of the Company to which this object belongs.
billingProfile.deletedbooleanFlag showing if the object is deleted.
billingProfile.iduint64?Identifier given as input for the command.
billingProfile.vArray.<uint32>
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response message structure
restoreBillingProfileResponse {
	"billingProfile": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}
Possible exceptions
Error CodeDescription
2A communication error occurred.
If you receive this error, please contact technical support.
3The request does not contain a billingProfile object, or it is invalid.
3The requested billingProfile id was invalid.
5You do not have permission to restore BillingProfiles.
7You cannot execute this command because your session has expired.
8You cannot execute this command because you are not logged in.
16You cannot execute this command because your password has expired.
111The BillingProfile was not found by its unique identifier.
112The BillingProfile was found, but is not marked as deleted.

restoreBillingReport

Restores the specified BillingReport to its previous version.
Request message description
PropertyTypeRequiredDescription
billingReportParamIdalwaysAn object to contain the "id" of the BillingReport.
billingReport.iduint64alwaysIdentifier given as input for the command.
reqIdint32?optionalIdentifier used by external system to correlate requests to responses.
Request message structure
restoreBillingReport {
	"billingReport": {
		"id": number
	},
	"reqId": number
}
Response message description
PropertyTypeDescription
billingReportRespDeletedAn object which contains the BillingReport's unique identifier and deleted status.
billingReport.companyuint64Identifier of the Company to which this object belongs.
billingReport.deletedbooleanFlag showing if the object is deleted.
billingReport.iduint64?Identifier given as input for the command.
billingReport.vArray.<uint32>
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response message structure
restoreBillingReportResponse {
	"billingReport": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}
Possible exceptions
Error CodeDescription
2A communication error occurred.
If you receive this error, please contact technical support.
3The request does not contain a billingReport object, or it is invalid.
3The requested billingReport id was invalid.
5You do not have permission to restore BillingReports.
7You cannot execute this command because your session has expired.
8You cannot execute this command because you are not logged in.
16You cannot execute this command because your password has expired.
119The BillingReport was not found by its unique identifier.
120The BillingReport was found, but is not marked as deleted.

restoreHostingDiscount

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

restoreHostingLicense

Restores the specified BillableHostingLicense to its previous version.
Request message description
PropertyTypeRequiredDescription
hostingLicenseParamIdalwaysAn object to contain the "id" of the BillableHostingLicense.
hostingLicense.iduint64alwaysIdentifier given as input for the command.
reqIdint32?optionalIdentifier used by external system to correlate requests to responses.
Request message structure
restoreHostingLicense {
	"hostingLicense": {
		"id": number
	},
	"reqId": number
}
Response message description
PropertyTypeDescription
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
hostingLicenseRespDeletedAn object which contains the BillableHostingLicense's unique identifier and deleted status.
hostingLicense.companyuint64Identifier of the Company to which this object belongs.
hostingLicense.deletedbooleanFlag showing if the object is deleted.
hostingLicense.iduint64?Identifier given as input for the command.
hostingLicense.vArray.<uint32>
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response message structure
restoreHostingLicenseResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"hostingLicense": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"message": string,
	"reqId": number
}
Possible exceptions
Error CodeDescription
2A communication error occurred.
If you receive this error, please contact technical support.
3The request does not contain a hostingLicense object, or it is invalid.
3The requested hostingLicense id was invalid.
5You do not have permission to delete BillableHostingLicenses.
7You cannot execute this command because your session has expired.
8You cannot execute this command because you are not logged in.
16You cannot execute this command because your password has expired.
117The BillableHostingLicense was not found by its unique identifier.
118The BillableHostingLicense was found, but is not marked as deleted.

restoreHostingRule

Restores the specified BillableHostingRule to its previous version.
Request message description
PropertyTypeRequiredDescription
hostingRuleParamIdalwaysAn object to contain the "id" of the BillableHostingRule.
hostingRule.iduint64alwaysIdentifier given as input for the command.
reqIdint32?optionalIdentifier used by external system to correlate requests to responses.
Request message structure
restoreHostingRule {
	"hostingRule": {
		"id": number
	},
	"reqId": number
}
Response message description
PropertyTypeDescription
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
hostingRuleRespDeletedAn object which contains the BillableHostingRule's unique identifier and deleted status.
hostingRule.companyuint64Identifier of the Company to which this object belongs.
hostingRule.deletedbooleanFlag showing if the object is deleted.
hostingRule.iduint64?Identifier given as input for the command.
hostingRule.vArray.<uint32>
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response message structure
restoreHostingRuleResponse {
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"hostingRule": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"message": string,
	"reqId": number
}
Possible exceptions
Error CodeDescription
2A communication error occurred.
If you receive this error, please contact technical support.
3The request does not contain a hostingRule object, or it is invalid.
3The requested hostingRule id was invalid.
5You do not have permission to restore BillableHostingRules.
7You cannot execute this command because your session has expired.
8You cannot execute this command because you are not logged in.
16You cannot execute this command because your password has expired.
113The BillableHostingRule was not found by its unique identifier.
114The 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
PropertyTypeRequiredDefaultDescription
companyParamIdalwaysAn object to contain the "id" of the Company.
company.iduint64alwaysIdentifier given as input for the command.
includeParentbooleanoptionalfalseWhen set to true, the parent Company is included in the results.
reqIdint32?optionalIdentifier used by external system to correlate requests to responses.
treebooleanoptionaltrueWhen set to true, the full tree of companies is returned. Otherwise, only the first-level child-companies are included.
Request message structure
getCompaniesList {
	"company": {
		"id": number
	},
	"includeParent": boolean,
	"reqId": number,
	"tree": boolean
}
Response message description
PropertyTypeDescription
companiesArray.<CompanyGeneral>The list of requested companies.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response message structure
getCompaniesListResponse {
	"companies": [
		{
			"id": number,
			"name": string,
			"notes": string,
			"parent": number,
			"references": {
				string: string
			},
			"v": [
				number
			]
		}
	],
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}
Possible exceptions
Error CodeDescription
3The request does not contain a company object, or it is invalid.
3The company object does not contain an id, or it is invalid.
5You do not have permission to view this Company or child companies.
7You cannot execute this command because your session has expired.
8You cannot execute this command because you are not logged in.
16You cannot execute this command because your password has expired.
28The Company was not found by its unique identifier.

getCompany

Gets details of the specified Company.
Request message description
PropertyTypeRequiredDescription
companyParamIdalwaysAn object to contain the "id" key.
company.iduint64alwaysIdentifier given as input for the command.
reqIdint32?optionalIdentifier used by external system to correlate requests to responses.
Request message structure
getCompany {
	"company": {
		"id": number
	},
	"reqId": number
}
Response message description
PropertyTypeDescription
companyCompanyThe requested Company.
company.directoryObject.<string, Array.<uint64>>
for value-values see: Contact.id
The list of Contacts from this and other companies broken down by contact role.
company.iduint64Unique identifier of the Company.
company.labelsObject.<codified, LabelStyle>
for keys see: LabelStyle.code
The styles for labels added to Assets, Places, and other things.
company.namestring
maximum-length: 100
The organizational name.
company.notesstringNotes.
company.parentuint64The unique identifier of this company's parent organization.
company.passwordPolicyPasswordPolicyThe password complexity and expiry policy.
company.passwordPolicy.expireModePasswordExpiryModeDefines how passwords expire.
company.passwordPolicy.expireThresholdbyteThe threshold for expiry.
company.passwordPolicy.includeLettersbooleanDo passwords require alphabetical characters.
company.passwordPolicy.includeNumbersbooleanDo passwords require numeric characters.
company.passwordPolicy.includeSpecialbooleanDo passwords require non-alphanumeric characters.
company.passwordPolicy.includeUpperLowerbooleanDo passwords require upper-case and lower-case letters.
company.passwordPolicy.minimumLengthbyteThe minimum number of characters required.
company.referencesObject.<string, string>
maximum-count: 10
maximum-length of keys: 20
maximum-length of values: 100
Name/value collections of custom fields used to refer to external systems.
company.resellerCompanyResellerIf this company is a reseller, then they have their own theme, support and billing information.
company.reseller.contactInfoObject.<string, uint64>
maximum-count of keys: 100
for values see: Contact.id
A list of Contacts for company specific things like Technical Support, Billing, etc...
company.reseller.domainstring
maximum-length: 100
The URN and path to the instance of v4. It does not contain the protocol because all instances are required to be HTTPS.
company.reseller.favouritestring
maximum-length: 200
The name of the icon file used for browser bookmarks.
company.reseller.gamutObject.<string, ColourStyle>
maximum-length of keys: 25
Colours used as templates for status tags, labels, and places.
company.reseller.graphicsObject.<string, codified>
maximum-length of keys: 25
maximum-length of values: 30
A list of symbol names and their corresponding FontAwesome icon names.
company.reseller.iconstring
maximum-length: 200
The name of the image uploaded as the logo (used for collapsed/mobile view).
company.reseller.iduint64Unique identifier of the Company.
company.reseller.languagesArray.<codified>
maximum-length of values: 5
A list of supported languages for your customers.
company.reseller.notifyEmailNotificationServerEmailThe server used for notification and conversational email messages sent and received by the system.
company.reseller.notifyEmail.incomingAddressstringThe domain or IP address of the incoming email server.
company.reseller.notifyEmail.incomingLoginstringThe username used to login to the incoming email server.
company.reseller.notifyEmail.incomingMessageNumberuint32IMAP message sequence number so only recent messages are retrieved.
company.reseller.notifyEmail.incomingPortuint16The port number of the incoming email server.
company.reseller.notifyEmail.incomingSecurebooleanIs the incoming email server using a secure SSL/TLS connection (it should).
company.reseller.notifyEmail.incomingTypestringThe type of incoming protocol to use (IMAP or POP3).
company.reseller.notifyEmail.outgoingAddressstringThe domain or IP address of the outgoing email server.
company.reseller.notifyEmail.outgoingLoginstringThe username used to login to the outgoing email server.
company.reseller.notifyEmail.outgoingPortuint16The port number of the outgoing email server.
company.reseller.notifyEmail.outgoingReplyToemailAn optional field which can be set as the "sent from" and/or "reply-to" address.
company.reseller.notifyEmail.outgoingSecurebooleanIs the outgoing email server using a secure SSL/TLS connection (it should).
company.reseller.notifyEmail.outgoingTypestringThe type of outgoing protocol to use (only SMTP).
company.reseller.notifySmsNotificationServerSmsDefinition for load-balanced outbound SMS numbers for the reseller.
company.reseller.notifySms.notifyLimituint16A per-number/per-day limit on the amount of Notifications sent.
company.reseller.notifySms.phoneNumbersObject.<string, Array.<phone>>
fixed length of keys: 2
All phone numbers listed by the country (using two-digit ISO 3166-1 alpha-2 country codes) they each serve.
company.reseller.parentuint64The unique identifier of this company's parent organization.
company.reseller.recoverBodystringThe body of the email sent to a user requesting a password reset.
company.reseller.recoverIsHtmlboolean
company.reseller.recoverSubjectstringThe subject of the email sent to a user requesting a password reset.
company.reseller.serviceNamestring
maximum-length: 150
The name of the branded service being provided to the seller's customers.
company.reseller.termsPreamblestringA preamble to the general terms and conditions offered by Fleet Freedom.
company.reseller.termsUpdateddatetimeThe date and time when the terms were updated. This will promt users who are logging-in to re-agree to the new terms
company.reseller.vArray.<uint32>Object version keys used to validate synchronization for all object properties.
company.reseller.websiteObject.<string, colour>
maximum-length of keys: 25
maximum-length of values: 22
Themed colours used in the web-based UI.
company.sessionPolicySessionPolicyThe session lifetime policy.
company.sessionPolicy.applicationsArray.<string>The list of applications users are allowed to use to create sessions.
company.sessionPolicy.expireTimeoutuint16The lifetime duration of a session in minutes.
company.sessionPolicy.idleAllowedbooleanDefines whether a session should be automatically killed when the connection breaks.
company.sessionPolicy.ipv4RangesArray.<ipv4>
maximum-length of values: 19
Restrict session creation to only the provided IPv4 ranges (using CIDR slash-notation). Leave blank for Internet access.
company.sessionPolicy.maxSessionsbyteThe maximum number of sessions allowed per user.
company.sessionPolicy.multiUserSessionMultiUserDefines the behaviour of the system when a user creates multiple sessions.
company.tagsObject.<codified, LabelStyle>
for keys see: LabelStyle.code
The styles for status tags added to Assets.
company.userGroupsArray.<UserGroup>A list of user groups that belong to this company. A user can only belong to groups from their own company.
company.vArray.<int32>
fixed count: 6
Object version keys used to validate synchronization for all object properties.
company.v[0]int32The first element is for the general properties
company.v[1]int32The second element is not used (yet)
company.v[2]int32The third element is not used (yet)
company.v[3]int32The fourth element is for the style properties
company.v[4]int32The fifth element is for the policy properties
company.v[5]int32The sixth element is for the reseller properties
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response 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
		},
		"references": {
			string: string
		},
		"reseller": {
			"contactInfo": {
				string: number
			},
			"domain": string,
			"favourite": string,
			"gamut": {
				string: {
					"fill": string,
					"stroke": string
				}
			},
			"graphics": {
				string: string
			},
			"icon": string,
			"id": number,
			"languages": [
				string
			],
			"logo": string,
			"notifyEmail": {
				"incomingAddress": string,
				"incomingLogin": string,
				"incomingMessageNumber": number,
				"incomingPort": number,
				"incomingSecure": boolean,
				"incomingType": string,
				"outgoingAddress": string,
				"outgoingLogin": string,
				"outgoingPort": number,
				"outgoingReplyTo": string,
				"outgoingSecure": boolean,
				"outgoingType": string
			},
			"notifySms": {
				"notifyLimit": number,
				"phoneNumbers": {
					string: [
						number
					]
				}
			},
			"parent": number,
			"recoverBody": string,
			"recoverIsHtml": boolean,
			"recoverSubject": string,
			"serviceName": string,
			"termsPreamble": string,
			"termsUpdated": string,
			"v": [
				number
			],
			"website": {
				string: string
			}
		},
		"sessionPolicy": {
			"applications": [
				string
			],
			"expireTimeout": number,
			"idleAllowed": boolean,
			"ipv4Ranges": [
				string
			],
			"maxSessions": number,
			"multiUser": string
		},
		"tags": {
			string: {
				"code": string,
				"fill": string,
				"graphic": string,
				"name": string,
				"notes": string,
				"stroke": string
			}
		},
		"userGroups": [
			{
				"company": number,
				"id": number,
				"name": string,
				"notes": string,
				"permissions": [
					{
						"company": number,
						"kind": string,
						"labels": [
							string
						],
						"level": string,
						"method": string,
						"type": string
					}
				],
				"v": [
					number
				]
			}
		],
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}
Possible exceptions
Error CodeDescription
3The request does not contain a company object, or it is invalid.
3The company object does not contain an id, or it is invalid.
5You do not have permission to view this Company.
7You cannot execute this command because your session has expired.
8You cannot execute this command because you are not logged in.
16You cannot execute this command because your password has expired.
28The Company was not found by its unique identifier.

mergeCompany

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

restoreCompany

Restores the specified Company.
Request message description
PropertyTypeRequiredDescription
companyParamIdalwaysAn object to contain the "id" key.
company.iduint64alwaysIdentifier given as input for the command.
reqIdint32?optionalIdentifier used by external system to correlate requests to responses.
Request message structure
restoreCompany {
	"company": {
		"id": number
	},
	"reqId": number
}
Response message description
PropertyTypeDescription
companyRespParentDeletedAn object which contains the Company's unique identifier and deleted status.
company.deletedbooleanFlag showing if the object is deleted.
company.iduint64?Identifier given as input for the command.
company.parentuint64Identifier of the parent to which the Company is a child.
company.vArray.<uint32>
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response message structure
restoreCompanyResponse {
	"company": {
		"deleted": boolean,
		"id": number,
		"parent": number,
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}
Possible exceptions
Error CodeDescription
2A communication error occurred.
If you receive this error, please contact technical support.
3The request does not contain a company object, or it is invalid.
3The company object does not contain an id, or it is invalid.
5You do not have permission to restore this Company.
7You cannot execute this command because your session has expired.
8You cannot execute this command because you are not logged in.
16You cannot execute this command because your password has expired.
28The Company was not found by its unique identifier.
29The Company was found, but is not marked as deleted.

Contacts

getContact

Gets details of the specified Contact.
Request message description
PropertyTypeRequiredDescription
contactParamIdalwaysAn object to contain the "id" of the Contact.
contact.iduint64alwaysIdentifier given as input for the command.
reqIdint32?optionalIdentifier used by external system to correlate requests to responses.
Request message structure
getContact {
	"contact": {
		"id": number
	},
	"reqId": number
}
Response message description
PropertyTypeDescription
contactContactThe requested Contact.
contact.addressesObject.<string, string>Mailing addresses. Use the object key like a name of the address. Example keys: Home, Work, Park, etc.
contact.companyuint64The company to which this contact belongs
contact.datesObject.<string, datetime>Date information. Use the object key like a name of the date. Example keys: Birthday, Started Date, Retired On, etc.
contact.emailsObject.<string, email>
maximum-length of values: 254
Email addresses. Use the object key like a name of the address. Example keys: Home, Work, Support, Old, etc.
contact.iduint64Unique identifier of this contact.
contact.namestring
maximum-length: 100
The person's name
contact.notesstringNotes about this person.
contact.optionsObject.<string, string>Uncategorized information. Use the object keys and values however you'd like.
contact.otherNamesObject.<string, string>
maximum-length of values: 254
A collection of other names this person might go by. Use the object key like a name identifier. Example keys: Initials, Nickname, Maiden Name, etc.
contact.phonesObject.<string, phone>Phone numbers. Use the object key like a name of the phone number. Example keys: Mobile, Fax, Home, Office, etc.
contact.picturesArray.<uint64>
for values see: Picture.id
Pictures of this Contact.
contact.rolesArray.<string>A list of roles they play in the Company.
contact.urlsObject.<string, url>
maximum-length of values: 254
Websites and other online resources. Use the object key like a name of the address. Example keys: Downloads, Support, FTP, etc.
contact.vArray.<uint32>Object version keys used to validate synchronization for all object properties.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response 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
		],
		"roles": [
			string
		],
		"urls": {
			string: string
		},
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}
Possible exceptions
Error CodeDescription
3The request does not contain a contact object, or it is invalid.
3The contact object does not contain an id, or it is invalid.
5You do not have permission to view this Contact.
7You cannot execute this command because your session has expired.
8You cannot execute this command because you are not logged in.
16You cannot execute this command because your password has expired.
31The Contact was not found by its unique identifier.

getContactsList

Gets the list of Contacts for the specified Company.
Request message description
PropertyTypeRequiredDescription
companyParamIdalwaysAn object to contain the "id" of the Company.
company.iduint64alwaysIdentifier given as input for the command.
reqIdint32?optionalIdentifier used by external system to correlate requests to responses.
Request message structure
getContactsList {
	"company": {
		"id": number
	},
	"reqId": number
}
Response message description
PropertyTypeDescription
companyRespIdAn object to contain the "id" of the Company to which the array of Contacts belong.
company.iduint64?Identifier given as input for the command.
contactsArray.<Contact>The list of requested Contacts.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response 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
			],
			"roles": [
				string
			],
			"urls": {
				string: string
			},
			"v": [
				number
			]
		}
	],
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}
Possible exceptions
Error CodeDescription
2A communication error occurred.
If you receive this error, please contact technical support.
3The request does not contain a company object, or it is invalid.
3The company object does not contain an id, or it is invalid.
5You do not have permission to view Contacts for this Company.
7You cannot execute this command because your session has expired.
8You cannot execute this command because you are not logged in.
16You cannot execute this command because your password has expired.
28The Company was not found by its unique identifier.

mergeContact

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

removeContact

Deletes an existing Contact.
Request message description
PropertyTypeRequiredDescription
contactParamIdalwaysAn object to contain the "id" of the Contact.
contact.iduint64alwaysIdentifier given as input for the command.
reqIdint32?optionalIdentifier used by external system to correlate requests to responses.
Request message structure
removeContact {
	"contact": {
		"id": number
	},
	"reqId": number
}
Response message description
PropertyTypeDescription
contactRespDeletedAn object which contains the Contact's id, owning Company id, and deleted status.
contact.companyuint64Identifier of the Company to which this object belongs.
contact.deletedbooleanFlag showing if the object is deleted.
contact.iduint64?Identifier given as input for the command.
contact.vArray.<uint32>
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response message structure
removeContactResponse {
	"contact": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}
Possible exceptions
Error CodeDescription
2A communication error occurred.
If you receive this error, please contact technical support.
3The request does not contain a contact object, or it is invalid.
3The contact object does not contain an id, or it is invalid.
5You do not have permission to delete this Contact.
7You cannot execute this command because your session has expired.
8You cannot execute this command because you are not logged in.
16You cannot execute this command because your password has expired.
31The Contact was not found by its unique identifier.
121This Contact is still being used by a Asset or User.
Returns an ErrorDetailContactInUse as the errorDetails..

restoreContact

Restores the specified Contact.
Request message description
PropertyTypeRequiredDescription
contactParamIdalwaysAn object to contain the "id" of the Contact.
contact.iduint64alwaysIdentifier given as input for the command.
reqIdint32?optionalIdentifier used by external system to correlate requests to responses.
Request message structure
restoreContact {
	"contact": {
		"id": number
	},
	"reqId": number
}
Response message description
PropertyTypeDescription
contactRespDeletedAn object which contains the Contact's id, owning Company id, and deleted status.
contact.companyuint64Identifier of the Company to which this object belongs.
contact.deletedbooleanFlag showing if the object is deleted.
contact.iduint64?Identifier given as input for the command.
contact.vArray.<uint32>
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response message structure
restoreContactResponse {
	"contact": {
		"company": number,
		"deleted": boolean,
		"id": number,
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}
Possible exceptions
Error CodeDescription
2A communication error occurred.
If you receive this error, please contact technical support.
3The request does not contain a contact object, or it is invalid.
3The contact object does not contain an id, or it is invalid.
5You do not have permission to restore this Contact.
7You cannot execute this command because your session has expired.
8You cannot execute this command because you are not logged in.
16You cannot execute this command because your password has expired.
31The Contact was not found by its unique identifier.
32The Contact was found, but is not marked as deleted.

Dispatch

getDispatchTask

Gets details of the specified DispatchTask.
Request message description
PropertyTypeRequiredDescription
dispatchTaskParamIdalwaysIdentifier object to contain the DispatchTask's identifier.
dispatchTask.iduint64alwaysIdentifier given as input for the command.
reqIdint32?optionalIdentifier used by external system to correlate requests to responses.
Request message structure
getDispatchTask {
	"dispatchTask": {
		"id": number
	},
	"reqId": number
}
Response message description
PropertyTypeDescription
dispatchTask
Deprecated
DispatchTaskThe requested DispatchTask.
Use DispatchJob instead.
dispatchTask.addressstring
maximum-length: 500
The street address of where the task must be completed.
dispatchTask.arriveddatetimeThe date/time stamp of when the asset arrived at this task.
dispatchTask.assetuint64The asset to which this task belongs.
dispatchTask.attachmentsArray.<uint64>
maximum-count: 10
for values see: Document.id
A list of hosted Document identifiers attached to this task.
dispatchTask.companyuint64The company to which this task belongs.
dispatchTask.completeddatetimeThe date/time stamp of when this task was completed.
dispatchTask.createddatetimeWhen this task was created.
dispatchTask.durationtimespanThe optional expected duration of the work for this task.
dispatchTask.etadatetimeThe optional estimated time of arrival for the asset.
dispatchTask.iduint64Unique identifier of this task.
dispatchTask.instructionsstringInstructions (filled out by dispatcher) for the field-employee to help them completed the task.
dispatchTask.latlngLatLngThe lat/long coordinates of where the task must be completed.
dispatchTask.latlng.latdoubleLatitude
dispatchTask.latlng.lngdoubleLongitude
dispatchTask.namestring
maximum-length: 100
The name of this task or the work needed to be performed.
dispatchTask.notesstringNotes about the status of the work filled in by field-employee.
dispatchTask.placeuint64?An optional place which can be used as a template instead of providing lat/long coordinates and a street address.
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.referencesObject.<string, string>
maximum-count: 10
maximum-length of keys: 20
maximum-length of values: 100
Name/value collections of custom fields used to refer to external systems.
dispatchTask.signatorystring
maximum-length: 100
The name of the person who signed the task's completion.
dispatchTask.signaturebooleanIndicates whether the task has a signature.
dispatchTask.status
Deprecated
TaskStatusThe progress of this task.
Use DispatchStepStatus instead.
dispatchTask.vArray.<uint32>Object version keys used to validate synchronization for all object properties.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response 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,
		"reference": string,
		"references": {
			string: string
		},
		"signatory": string,
		"signature": boolean,
		"status": string,
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}
Possible exceptions
Error CodeDescription
3The request does not contain a dispatchTask object, or it is invalid.
3The dispatchTask object does not contain an id, or it is invalid.
5You do not have permission to view DispatchTasks.
5You do not have permission to view the associated Asset.
7You cannot execute this command because your session has expired.
8You cannot execute this command because you are not logged in.
16You cannot execute this command because your password has expired.
20The DispatchTask was found, but the associated asset was not found.
64The DispatchTask was not found by its unique identifier.
96The 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
PropertyTypeRequiredDescription
assetParamIdalwaysAn object to contain the "id" of the Asset.
asset.iduint64alwaysIdentifier given as input for the command.
reqIdint32?optionalIdentifier used by external system to correlate requests to responses.
Request message structure
getDispatchTasksList {
	"asset": {
		"id": number
	},
	"reqId": number
}
Response message description
PropertyTypeDescription
assetRespIdCompanyAn object to contain the "id" of the Asset to which the array of DispatchTasks belong.
asset.companyuint64Identifier of the Company to which this object belongs.
asset.iduint64?Identifier given as input for the command.
dispatchTasksArray.<DispatchTask>The list of requested DispatchTasks.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response 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,
			"reference": string,
			"references": {
				string: string
			},
			"signatory": string,
			"signature": boolean,
			"status": string,
			"v": [
				number
			]
		}
	],
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}
Possible exceptions
Error CodeDescription
3The request does not contain a asset object, or it is invalid.
3The asset object does not contain an id, or it is invalid.
5You do not have permission to view DispatchTasks.
5You do not have permission to view the associated Asset.
7You cannot execute this command because your session has expired.
8You cannot execute this command because you are not logged in.
16You cannot execute this command because your password has expired.
20The Asset was not found by its unique identifier.
28The Company containing the DispatchTasks was not found.
96The 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
PropertyTypeRequiredDescription
companyParamIdalwaysAn object to contain the "id" of the Company.
company.iduint64alwaysIdentifier given as input for the command.
reqIdint32?optionalIdentifier used by external system to correlate requests to responses.
Request message structure
getDispatchTasksListByCompany {
	"company": {
		"id": number
	},
	"reqId": number
}
Response message description
PropertyTypeDescription
companyRespIdAn object to contain the "id" of the Company to which the array of DispatchTasks belong.
company.iduint64?Identifier given as input for the command.
dispatchTasksArray.<DispatchTask>The list of requested DispatchTasks.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response 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,
			"reference": string,
			"references": {
				string: string
			},
			"signatory": string,
			"signature": boolean,
			"status": string,
			"v": [
				number
			]
		}
	],
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}
Possible exceptions
Error CodeDescription
3The request does not contain a company object, or it is invalid.
3The company object does not contain an id, or it is invalid.
5You do not have permission to view DispatchTasks.
5You do not have permission to view Assets.
7You cannot execute this command because your session has expired.
8You cannot execute this command because you are not logged in.
16You cannot execute this command because your password has expired.
28The 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
PropertyTypeRequiredDescription
assetParamIdalwaysAn object to contain the "id" of the Asset.
asset.iduint64alwaysIdentifier given as input for the command.
referencestringoptionalThe "Reference" field value to match.
reqIdint32?optionalIdentifier used by external system to correlate requests to responses.
Request message structure
getDispatchTasksListByReference {
	"asset": {
		"id": number
	},
	"reference": string,
	"reqId": number
}
Response message description
PropertyTypeDescription
assetRespIdCompanyAn object to contain the "id" of the Asset to which the array of DispatchTasks belong.
asset.companyuint64Identifier of the Company to which this object belongs.
asset.iduint64?Identifier given as input for the command.
dispatchTasksArray.<DispatchTask>The list of requested DispatchTasks.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
referencestringThe "Reference" value given as input.
reqIdint32?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,
			"reference": string,
			"references": {
				string: string
			},
			"signatory": string,
			"signature": boolean,
			"status": string,
			"v": [
				number
			]
		}
	],
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reference": string,
	"reqId": number
}
Possible exceptions
Error CodeDescription
3The request does not contain a asset object, or it is invalid.
3The request does not contain a reference value, or it is blank.
3The asset object does not contain an id, or it is invalid.
5You do not have permission to view DispatchTasks.
5You do not have permission to view the associated Asset.
7You cannot execute this command because your session has expired.
8You cannot execute this command because you are not logged in.
16You cannot execute this command because your password has expired.
20The Asset was not found by its unique identifier.
28The Company containing the DispatchTasks was not found.
96The 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
PropertyTypeRequiredDescription
assetParamIdalwaysAn object to contain the "id" of the Asset.
asset.iduint64alwaysIdentifier given as input for the command.
referencesObject.<string, string>optionalCase-insensitive reference pairs used to match tasks.
reqIdint32?optionalIdentifier used by external system to correlate requests to responses.
Request message structure
getDispatchTasksListByReferences {
	"asset": {
		"id": number
	},
	"references": {
		string: string
	},
	"reqId": number
}
Response message description
PropertyTypeDescription
assetRespIdCompanyAn object to contain the "id" of the Asset to which the array of DispatchTasks belong.
asset.companyuint64Identifier of the Company to which this object belongs.
asset.iduint64?Identifier given as input for the command.
dispatchTasksArray.<DispatchTask>The list of requested DispatchTasks.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
referencesObject.<string, string>The reference string given as input.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response 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,
			"reference": string,
			"references": {
				string: string
			},
			"signatory": string,
			"signature": boolean,
			"status": string,
			"v": [
				number
			]
		}
	],
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"references": {
		string: string
	},
	"reqId": number
}
Possible exceptions
Error CodeDescription
3The request does not contain a asset object, or it is invalid.
3The request does not contain a references object, or it is invalid.
3The asset object does not contain an id, or it is invalid.
5You do not have permission to view DispatchTasks.
5You do not have permission to view the associated Asset.
7You cannot execute this command because your session has expired.
8You cannot execute this command because you are not logged in.
16You cannot execute this command because your password has expired.
20The Asset was not found by its unique identifier.
28The Company containing the DispatchTasks was not found.
96The 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
PropertyTypeRequiredDescription
dispatchTaskObject.<string, ?>alwaysThe details of a DispatchTask either for creation or update.
dispatchTask.addressstringcreate (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.assetuint64?createThe identifier of the Asset assigned to this DispatchTask.
dispatchTask.attachmentsArray.<uint64>
for values see: Document.id
optionalA list of Document identifiers to attach to this DispatchTask for both driver and dispatcher review.
dispatchTask.durationtimespanoptionalThe 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.etadatetimeoptionalEstimated time of arrival.
dispatchTask.iduint64?updateThe unique identifier of the DispatchTask you want to update.
dispatchTask.instructionsstringoptionalInstructions for the driver to help them complete the DispatchTask. Such as which door to use, a buzz code to enter the facility, etc...
dispatchTask.latlngLatLngcreate (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.latdoubleoptionalLatitude
dispatchTask.latlng.lngdoubleoptionalLongitude
dispatchTask.namestring
maximum-length: 100
createName for the DispatchTask.
dispatchTask.notesstringoptionalNotes completed by the driver about the DispatchTask. Such as service notes, damaged goods upon pick-up, etc...
dispatchTask.placeuint64?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.referencesObject.<string, string>optionalA 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.statusTaskStatus?optionalDispatchTasks have a lifetime and each status represents a DispatchTask's progress through it's life.
dispatchTask.vArray.<int32>optional
reqIdint32?optionalIdentifier 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
PropertyTypeDescription
dispatchTaskRespIdAssetThe id, owning Asset id, and owning Company id of the object requested/created.
dispatchTask.assetuint64Identifier of the Asset to which this object belongs
dispatchTask.companyuint64Identifier of the Company to which this object belongs.
dispatchTask.iduint64?Identifier given as input for the command.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response message structure
mergeDispatchTaskResponse {
	"dispatchTask": {
		"asset": number,
		"company": number,
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}
Possible exceptions
Error CodeDescription
2A communication error occurred.
If you receive this error, please contact technical support.
3The request does not contain a dispatchTask object, or it is invalid.
3Not enough keys exist in the dispatchTask object.
3Too many DispatchTask references were given.
3Too many DispatchTask attachements were given.
3The request contains an invalid dispatchTask.references object.
3The request contains an invalid dispatchTask.place id.
3The request contains an invalid dispatchTask.attachments array.
3The request contains an invalid dispatchTask.latlng object.
3The request contains an invalid dispatchTask.eta date time.
3The request contains an invalid dispatchTask.duration timespan.
3The request contains an invalid dispatchTask.status TaskStatus.
3During create: When creating a new DispatchTask, a name was not given, or was blank.
3During create: When creating a new DispatchTask, an asset was not given.
3During create: When creating a new DispatchTask, a place, a latlng, or an address must be given.
3During update: When updating a DispatchTask, the new name cannot be blank.
3During update: When updating a DispatchTask, not enough v values were given.
3During update: There are too many combined dispatchTask.references after adding the newly given keys.
Returns an ErrorDetailMinMax as the errorDetails..
5You do not have permission to view the Asset to which the DispatchTask belongs.
5During create: You do not have permission to create new DispatchTasks.
5During update: You do not have permission to update DispatchTasks.
6During update: When updating a DispatchTask, the wrong version key(s) were given.
7You cannot execute this command because your session has expired.
8You cannot execute this command because you are not logged in.
16You cannot execute this command because your password has expired.
20The Asset to which this DispatchTask is assigned was not found.
40The Place being given for the DispatchTask was not found.
64The DispatchTask was not found.
64The DispatchTask was cancelled.
81When giving only an address (not a Place or dispatchTask.latlng), the address could not be geocoded.
81When giving only an address (not a Place or dispatchTask.latlng), the address was not street-level accurate enough.
Returns an ErrorDetailExternals as the errorDetails..
96The Asset to which this DispatchTask is assigned is suspended. Before sending or updating DispatchTasks for an Asset, it must be reactivated.
124One or more of the given attachments could not be found.
Returns an ErrorDetailBadIds as the errorDetails..
130During 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
PropertyTypeRequiredDescription
dispatchTasksArray.<ParameterContent>optionalArray of parameters successfully parsed by the sub-command.
reqIdint32?optionalIdentifier 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
PropertyTypeDescription
dispatchTasksArray.<RespIdAsset>Array or responses successfully processed by the sub-command.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response message structure
multiMergeDispatchTaskResponse {
	"dispatchTasks": [
		{
			"asset": number,
			"company": number,
			"id": number
		}
	],
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}
Possible exceptions
Error CodeDescription
3The request does not contain an operation collection, or it is invalid.
3The operation collection is empty.
7You cannot execute this command because your session has expired.
8You cannot execute this command because you are not logged in.
16You cannot execute this command because your password has expired.
105Too many items exist in the operation collection.
110One 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
PropertyTypeRequiredDescription
dispatchTasksArray.<ParamId>optionalArray of parameters successfully parsed by the sub-command.
reqIdint32?optionalIdentifier used by external system to correlate requests to responses.
Request message structure
multiRemoveDispatchTask {
	"dispatchTasks": [
		{
			"id": number
		}
	],
	"reqId": number
}
Response message description
PropertyTypeDescription
dispatchTasksArray.<RespAssetDeleted>Array or responses successfully processed by the sub-command.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response 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 CodeDescription
3The request does not contain an operation collection, or it is invalid.
3The operation collection is empty.
7You cannot execute this command because your session has expired.
8You cannot execute this command because you are not logged in.
16You cannot execute this command because your password has expired.
105Too many items exist in the operation collection.
110One 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
PropertyTypeRequiredDescription
dispatchTaskParamIdalwaysIdentifier object to contain the DispatchTask's identifier.
dispatchTask.iduint64alwaysIdentifier given as input for the command.
reqIdint32?optionalIdentifier used by external system to correlate requests to responses.
Request message structure
removeDispatchTask {
	"dispatchTask": {
		"id": number
	},
	"reqId": number
}
Response message description
PropertyTypeDescription
dispatchTaskRespAssetDeletedThe id, owning Asset id, owning Company id, and deleted state.
dispatchTask.assetuint64Identifier of the Asset to which this object belongs.
dispatchTask.companyuint64Identifier of the Company to which this object belongs.
dispatchTask.deletedbooleanFlag showing if the object is deleted.
dispatchTask.iduint64?Identifier given as input for the command.
dispatchTask.vArray.<uint32>
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response 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 CodeDescription
3The request does not contain a dispatchTask object, or it is invalid.
3The dispatchTask object does not contain an id, or it is invalid.
5You do not have permission to delete DispatchTasks.
5You do not have permission to view the associated Asset.
7You cannot execute this command because your session has expired.
8You cannot execute this command because you are not logged in.
16You cannot execute this command because your password has expired.
20The DispatchTask was found, but the associated Asset was not found.
64The DispatchTask was not found by its unique identifier.
96The 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
PropertyTypeRequiredDescription
dispatchTaskParamIdalwaysIdentifier object to contain the DispatchTask's identifier.
dispatchTask.iduint64alwaysIdentifier given as input for the command.
reqIdint32?optionalIdentifier used by external system to correlate requests to responses.
Request message structure
restoreDispatchTask {
	"dispatchTask": {
		"id": number
	},
	"reqId": number
}
Response message description
PropertyTypeDescription
dispatchTaskRespAssetDeletedThe id, owning Asset id, owning Company id, and deleted state.
dispatchTask.assetuint64Identifier of the Asset to which this object belongs.
dispatchTask.companyuint64Identifier of the Company to which this object belongs.
dispatchTask.deletedbooleanFlag showing if the object is deleted.
dispatchTask.iduint64?Identifier given as input for the command.
dispatchTask.vArray.<uint32>
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response 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 CodeDescription
3The request does not contain a dispatchTask object, or it is invalid.
3The dispatchTask object does not contain an id, or it is invalid.
5You do not have permission to create DispatchTasks.
5You do not have permission to view the associated Asset.
7You cannot execute this command because your session has expired.
8You cannot execute this command because you are not logged in.
16You cannot execute this command because your password has expired.
20The DispatchTask was found, but the associated Asset was not found.
64The DispatchTask was not found by its unique identifier.
96The DispatchTask was found, but the associated Asset is suspended. Before using any Asset resources, it must be reactivated.
100The DispatchTask was found, but is not marked as deleted.

File Hosting

getDocument

Gets details of the specified Document.
Request message description
PropertyTypeRequiredDescription
documentParamIdalwaysAn object to contain the identifier of the Document.
document.iduint64alwaysIdentifier given as input for the command.
reqIdint32?optionalIdentifier used by external system to correlate requests to responses.
Request message structure
getDocument {
	"document": {
		"id": number
	},
	"reqId": number
}
Response message description
PropertyTypeDescription
documentDocumentThe requested Document.
document.bytesuint64The file-size on the disk.
document.companyuint64The company to which this file belongs.
document.expirydatetimeThe date and time this fill will be automatically purged from our system.
document.iduint64Unique identifier of this file.
document.mimestring
maximum-length: 50
The MIME type of the file.
document.namestring
maximum-length: 100
The file name of this file.
document.notesstringNotes about this file.
document.referencesObject.<string, string>
maximum-count: 10
maximum-length of keys: 20
maximum-length of values: 100
Name/value collections of custom fields used to refer to external systems.
document.srcstring
maximum-length: 200
The URL/path to find this file.
document.vArray.<uint32>Object version keys used to validate synchronization for all object properties.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response message structure
getDocumentResponse {
	"document": {
		"bytes": number,
		"company": number,
		"expiry": string,
		"id": number,
		"mime": string,
		"name": string,
		"notes": string,
		"references": {
			string: string
		},
		"src": string,
		"v": [
			number
		]
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}
Possible exceptions
Error CodeDescription
3The request does not contain a document object, or it is invalid.
3The document object does not contain an id, or it is invalid.
5You do not have permission to view this Document.
7You cannot execute this command because your session has expired.
8You cannot execute this command because you are not logged in.
16You cannot execute this command because your password has expired.
122The Document was not found by its unique identifier.

getDocumentsList

Gets the list of Documents for the specified Company.
Request message description
PropertyTypeRequiredDescription
companyParamIdalwaysAn object to contain the "id" of the Company.
company.iduint64alwaysIdentifier given as input for the command.
reqIdint32?optionalIdentifier used by external system to correlate requests to responses.
Request message structure
getDocumentsList {
	"company": {
		"id": number
	},
	"reqId": number
}
Response message description
PropertyTypeDescription
companyRespIdAn object to contain the "id" of the Company to which the array of Documents belong.
company.iduint64?Identifier given as input for the command.
documentsArray.<Document>The list of requested Documents.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response message structure
getDocumentsListResponse {
	"company": {
		"id": number
	},
	"documents": [
		{
			"bytes": number,
			"company": number,
			"expiry": string,
			"id": number,
			"mime": string,
			"name": string,
			"notes": string,
			"references": {
				string: string
			},
			"src": string,
			"v": [
				number
			]
		}
	],
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}
Possible exceptions
Error CodeDescription
2A communication error occurred.
If you receive this error, please contact technical support.
3The request does not contain a company object, or it is invalid.
3The company object does not contain an id, or it is invalid.
5You do not have permission to view Documents for this Company.
7You cannot execute this command because your session has expired.
8You cannot execute this command because you are not logged in.
16You cannot execute this command because your password has expired.
28The Company was not found by its unique identifier.

getIcon

Gets details of the specified Icon.
Request message description
PropertyTypeRequiredDescription
iconParamIdalwaysAn object to contain the "id" of the Icon.
icon.iduint64alwaysIdentifier given as input for the command.
reqIdint32?optionalIdentifier used by external system to correlate requests to responses.
Request message structure
getIcon {
	"icon": {
		"id": number
	},
	"reqId": number
}
Response message description
PropertyTypeDescription
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
iconIconThe requested Icon.
icon.badgeIconLabelWhere 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.alignstringDetermines which corner of the label is attached to the anchor.
icon.badge.anchorPointThe offset from the lat/long in pixels.
icon.badge.anchor.xdoubleHorizontal coordinate
icon.badge.anchor.ydoubleVertical coordinate
icon.badge.colourstringBackground colour of the label.
icon.categorystring
maximum-length: 100
A noun to describe the type of thing represented. Like Truck, Car, Trailer, Hot-Air Balloon, etc...
icon.companyuint64The company to which this icon belongs.
icon.globalbooleanIndicates whether this icon is available to child companies.
icon.glyphsArray.<IconGlyph>The images used to show the detail of this icon.
icon.iduint64Unique identifier of this icon.
icon.labelIconLabelDefinition for the name bubble above the icon on a map.
icon.label.alignstringDetermines which corner of the label is attached to the anchor.
icon.label.anchorPointThe offset from the lat/long in pixels.
icon.label.anchor.xdoubleHorizontal coordinate
icon.label.anchor.ydoubleVertical coordinate
icon.label.colourstringBackground colour of the label.
icon.namestring
maximum-length: 100
A specific adjective to describe the thing. Like Blue, Red, Empty, Full, etc...
icon.notesstringNotes.
icon.usageArray.<string>A list of things that this icon can be used to represent. Like asset, place, user, etc...
icon.vArray.<uint32>Object version keys used to validate synchronization for all object properties.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response 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,
		"usage": [
			string
		],
		"v": [
			number
		]
	},
	"message": string,
	"reqId": number
}
Possible exceptions
Error CodeDescription
3The request does not contain a icon object, or it is invalid.
3The icon object does not contain an id, or it is invalid.
5You do not have permission to view this Icon.
7You cannot execute this command because your session has expired.
8You cannot execute this command because you are not logged in.
16You cannot execute this command because your password has expired.
33The Icon was not found by its unique identifier.

getIconsList

Gets the list of Icons for the specified Company.
Request message description
PropertyTypeRequiredDefaultDescription
branchbooleanoptionalfalseWhen true the list of Icons from the given Company and all child-companies are returned. Otherwise, only Icons from the given Company are included.
companyParamIdalwaysAn object to contain the "id" of the Company.
company.iduint64alwaysIdentifier given as input for the command.
reqIdint32?optionalIdentifier used by external system to correlate requests to responses.
trunkbooleanoptionaltrueWhen 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
	},
	"reqId": number,
	"trunk": boolean
}
Response message description
PropertyTypeDescription
companyRespIdAn object to contain the "id" of the Company to which the array of Icons belong.
company.iduint64?Identifier given as input for the command.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
iconsArray.<Icon>The list of requested Icons.
messagestringAn English description of the error.
reqIdint32?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,
			"usage": [
				string
			],
			"v": [
				number
			]
		}
	],
	"message": string,
	"reqId": number
}
Possible exceptions
Error CodeDescription
3The request does not contain a company object, or it is invalid.
3The company object does not contain an id, or it is invalid.
5You do not have permission to view Icons for this Company.
7You cannot execute this command because your session has expired.
8You cannot execute this command because you are not logged in.
16You cannot execute this command because your password has expired.
28The Company was not found by its unique identifier.

getPicture

Gets details of the specified Picture.
Request message description
PropertyTypeRequiredDescription
pictureParamIdalwaysAn object to contain the "id" of the Picture.
picture.iduint64alwaysIdentifier given as input for the command.
reqIdint32?optionalIdentifier used by external system to correlate requests to responses.
Request message structure
getPicture {
	"picture": {
		"id": number
	},
	"reqId": number
}
Response message description
PropertyTypeDescription
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
picturePictureThe requested Picture.
picture.bytesuint64The file-size on the disk.
picture.companyuint64The company to which this image belongs.
picture.focalsArray.<Square>A list of focal points in the images like faces.
picture.iduint64Unique identifier of this image.
picture.namestring
maximum-length: 100
The file name of this image.
picture.notesstringNotes about this image.
picture.sizeSizeSize defined in pixels.
picture.size.heightdoubleHeight
picture.size.widthdoubleWidth
picture.srcstring
maximum-length: 200
The URL/path to find this image.
picture.usesuint32A count of the times this image was used for something (asset, contact, task, etc).
picture.vArray.<uint32>Object version keys used to validate synchronization for all object properties.
reqIdint32?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,
		"size": {
			"height": number,
			"width": number
		},
		"src": string,
		"uses": number,
		"v": [
			number
		]
	},
	"reqId": number
}
Possible exceptions
Error CodeDescription
3The request does not contain a picture object, or it is invalid.
3The picture object does not contain an id, or it is invalid.
5You do not have permission to view this Picture.
7You cannot execute this command because your session has expired.
8You cannot execute this command because you are not logged in.
16You cannot execute this command because your password has expired.
68The Picture was not found by its unique identifier.

getPicturesList

Gets the list of Pictures for the specified Company.
Request message description
PropertyTypeRequiredDefaultDescription
branchbooleanoptionalfalseWhen true the list of Pictures from the given Company and all child-companies are returned. Otherwise, only Pictures from the given Company are included.
companyParamIdalwaysAn object to contain the "id" of the Company.
company.iduint64alwaysIdentifier given as input for the command.
reqIdint32?optionalIdentifier used by external system to correlate requests to responses.
Request message structure
getPicturesList {
	"branch": boolean,
	"company": {
		"id": number
	},
	"reqId": number
}
Response message description
PropertyTypeDescription
companyRespIdAn object to contain the "id" of the Company to which the array of Pictures belong.
company.iduint64?Identifier given as input for the command.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
picturesArray.<Picture>The list of requested Pictures.
reqIdint32?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,
			"size": {
				"height": number,
				"width": number
			},
			"src": string,
			"uses": number,
			"v": [
				number
			]
		}
	],
	"reqId": number
}
Possible exceptions
Error CodeDescription
3The request does not contain a company object, or it is invalid.
3The company object does not contain an id, or it is invalid.
5You do not have permission to view Pictures for this Company.
7You cannot execute this command because your session has expired.
8You cannot execute this command because you are not logged in.
16You cannot execute this command because your password has expired.
28The 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
PropertyTypeRequiredDescription
documentObject.<string, ?>alwaysA simple object to contain the Document parameters.
document.companyuint64?createThe Company to which this Document belongs. After creation, this value is read-only.
document.expirydatetimeoptionalThe time at which the Document will automatically be purged from the system.
document.iduint64?updateThe unique identifier of the Document you want to update.
document.namestring
maximum-length: 100
createThe file name of this Document.
document.notesstringoptionalNotes about this Document.
document.referencesObject.<string, string>
maximum-count: 10
maximum-length of keys: 20
maximum-length of values: 100
optionalName/value collections of custom fields used to refer to external systems. If the value is null, the references are removed from the Document.
document.vArray.<int32>optional
reqIdint32?optionalIdentifier 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
PropertyTypeDescription
documentRespIdCompanyAn object which contains the "id" and "company" keys.
document.companyuint64Identifier of the Company to which this object belongs.
document.iduint64?Identifier given as input for the command.
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response message structure
mergeDocumentResponse {
	"document": {
		"company": number,
		"id": number
	},
	"errorCode": number,
	"errorDetails": {
		"kind": string
	},
	"message": string,
	"reqId": number
}
Possible exceptions
Error CodeDescription
2A communication error occurred.
If you receive this error, please contact technical support.
3The request does not contain a document object, or it is invalid.
3Not enough keys exist in the document object.
3The given document.expiry is too far into the future.
3During create: When creating a new Document, a company was not given.
3During create: When creating a new Document, a name was not given, or it is invalid.
3During create: When creating a new Document, the local path was not specified.
3During create: When creating a new Document, the bytes was invalid.
3During create: When creating a new Document, the mime was invalid.
3During update: When updating a Document, the id was invalid.
3During update: When updating a Document, the v was not an array, or contained too few numbers.
3During update: When updating a Document, the name was given as blank.
5You do not have permission to create a new Document.
5You do not have permission to update this Document.
6During update: When updating a Document, an incorrect v value was given as input.
7You cannot execute this command because your session has expired.
8You cannot execute this command because you are not logged in.
16You cannot execute this command because your password has expired.
122During update: The Document was not found by its unique identifier.
130During update: When updating a Document, the company can not be changed.

mergeIcon

Creates a new or updates an existing Icon.
Request message description
PropertyTypeRequiredDescription
iconObject.<string, ?>alwaysA simple object to contain the Icon parameters.
icon.categorystring
maximum-length: 100
optionalA noun to describe the type of thing represented. Like Truck, Car, Trailer, Hot-Air Balloon, etc...
icon.companyuint64?createThe Company to which these Icons belongs.
icon.globalbooleanoptionalIndicates whether this Icon is available to child companies.
icon.glyphsArray.<IconGlyph>optionalThe images used to show the detail of this Icon.
icon.iduint64?updateThe unique identifier of the Icon you want to update.
icon.labelIconLabeloptionalDefinition for the name bubble above the Icon on a map.
icon.label.alignstringoptionalDetermines which corner of the label is attached to the anchor.
icon.label.anchorPointoptionalThe offset from the lat/long in pixels.
icon.label.anchor.xdoubleoptionalHorizontal coordinate
icon.label.anchor.ydoubleoptionalVertical coordinate
icon.label.colourstringoptionalBackground colour of the label.
icon.namestring
maximum-length: 100
createA specific adjective to describe the thing. Like Blue, Red, Empty, Full, etc...
icon.notesstringoptionalNotes.
icon.usageArray.<string>optionalA list of things that this Icon can be used to represent. Like asset, place, user, etc...
icon.vArray.<int32>optional
reqIdint32?optionalIdentifier used by external system to correlate requests to responses.
Request message structure
mergeIcon {
	"icon": {
		"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
PropertyTypeDescription
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
iconRespIdCompanyAn object which contains the "id" and "company" keys when there is no error.
icon.companyuint64Identifier of the Company to which this object belongs.
icon.iduint64?Identifier given as input for the command.
messagestringAn English description of the error.
reqIdint32?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 CodeDescription
2A communication error occurred.
If you receive this error, please contact technical support.
3The request does not contain a icon object, or it is invalid.
3Not enough keys exist in the icon object.
3The icon.usage was invalid.
3During create: When creating a new Icon, a company was not given.
3During create: When creating a new Icon, a name was not given, or it is invalid.
3During update: When updating a Icon, the id was invalid.
3During update: When updating a Icon, the name was given as blank.
3During update: When updating a Icon, the v was not an array, or contained too few numbers.
3One of the icon.glyphs values is invalid.
Returns an ErrorDetailInput as the errorDetails..
5You do not have permission to create a new Icon.
5You do not have permission to update this Icon.
6During update: When updating a Icon, an incorrect v value was given as input.
7You cannot execute this command because your session has expired.
8You cannot execute this command because you are not logged in.
16You cannot execute this command because your password has expired.
33During update: The Icon was not found by its unique identifier.
130During update: When updating a Icon, the company can not be changed.

mergePicture

Creates a new or updates an existing Picture.
Request message description
PropertyTypeRequiredDescription
pictureObject.<string, ?>alwaysA simple object to contain the Picture parameters.
picture.companyuint64?createThe Company to which this Picture belongs. After creation, this value is read-only.
picture.focalsArray.<Square>optionalA list of focal points in the Picture like faces.
picture.iduint64?updateThe unique identifier of the Picture you want to update.
picture.namestring
maximum-length: 100
createThe file name of this Picture.
picture.notesstringoptionalNotes about this Picture.
picture.vArray.<int32>optional
reqIdint32?optionalIdentifier 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
PropertyTypeDescription
errorCodeErrorCodeThe unique, numeric error code when processing this request.
errorDetailsErrorDetailAn object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors.
messagestringAn English description of the error.
pictureRespIdCompanyAn object which contains the "id" and "company" keys when there is no error.
picture.companyuint64Identifier of the Company to which this object belongs.
picture.iduint64?Identifier given as input for the command.
reqIdint32?Identifier used by external system to correlate requests to responses.
Response message structure
mergePictureResponse {
	"errorCode": number,
	"errorDetails": {