REST Reference
- Download JSDoc Helper
- ©2023 Trak-iT Wireless Inc.
- Updated Friday June 16, 2023 05:07PM
- Version 5.22.0
- Beta end-point:
https://mindflayer.trakit.ca/
- Production end-point:
https://rest.trakit.ca/
Assets
Behaviours
Billing
Companies
Contacts
Dispatch
File Hosting
Hours of Service
Icons
Maintenance
Messaging
Places
Providers and Configurations
Reports
Self
Users and Groups
White-labelling
API Definitions
GET/timezones
Gets a list of Timezones.
Response description
Property | Type | Description |
---|---|---|
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
timezones | Array.<Timezone> | The list of valid system Timezones. |
Response structure
{ "errorCode": number, "errorDetails": { "kind": string }, "message": string, "reqId": number, "timezones": [ { "code": string, "dst": boolean, "name": string, "offset": number } ] }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
500 | 2 | System Timezone list could not be retrieved. If you receive this error, please contact technical support. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
GET/timezones/{code}
Gets details of the specified Timezone.
URL Parameters
Parameter | Type | Required | Description |
---|---|---|---|
code | string | required | Unique identifier of the Timezone. |
Response description
Property | Type | Description |
---|---|---|
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
timezone | Timezone | The requested Timezone. |
timezone | codified | Unique timezone code |
timezone | boolean | Indicates whether this timezone abides by daylight savings |
timezone | string | Common timezone name |
timezone | int16 | Minutes offset from GMT |
Response structure
{ "errorCode": number, "errorDetails": { "kind": string }, "message": string, "reqId": number, "timezone": { "code": string, "dst": boolean, "name": string, "offset": number } }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
400 | 3 | The request does not contain a timezone object, or it is invalid. |
400 | 3 | The timezone object does not contain a code, or it is invalid. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 62 | The Timezone was not found by its codified identifier. |
Assets
GET/assets?includeSuspended=boolean&includeMessages=boolean&includeTasks=boolean&includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number
This request is an alias of /companies/{your-company-id}/assets (when no additional query-string parameters are given) or /companies/{your-company-id}/assets?{keys=values} (when at least one additional query-string key/value is given).
URL Parameters
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
includeMessages | boolean | optional | false | False by default, but can be overridden. |
includeTasks | boolean | optional | false | False by default, but can be overridden. |
your-company-id | uint64 | aliased | {your-company-id} | Your own Company's identifier. |
PATCH/assets
Creates a new, or updates an existing Asset.
Response description
Property | Type | Description |
---|---|---|
asset | RespIdCompany | An object which contains the "id" and "company" keys. |
asset | uint64 | Identifier of the Company to which this object belongs. |
asset | uint64? | Identifier given as input for the command. |
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "asset": { "company": number, "id": number }, "errorCode": number, "errorDetails": { "kind": string }, "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
500 | 2 | A communication error occurred. If you receive this error, please contact technical support. |
400 | 3 | The request does not contain a asset object, or it is invalid. |
400 | 3 | No valid changes would be performed. |
400 | 3 | During create: When creating a new Asset, a name was not given. |
400 | 3 | During create: When creating a new Asset, a company was not given. |
400 | 3 | During create: When creating a new Asset, an icon was not given. |
400 | 3 | During create (for person): When creating a new Person, a contact was not given. |
400 | 3 | During update: When updating an Asset, the name was given as null or blank. |
400 | 3 | During update: When updating an Asset, the v was not an array, or contained too few numbers. |
400 | 3 | During create: The kind value is not a known AssetType. Returns an ErrorDetailEnum as the errorDetails .. |
400 | 3 | One of the asset.attributes names is invalid. Returns an ErrorDetailInput as the errorDetails .. |
400 | 3 | One of the asset.attributes values is not null or an object. Returns an ErrorDetailInput as the errorDetails .. |
400 | 3 | The asset.attributes object is given, but empty. Returns an ErrorDetailInput as the errorDetails .. |
400 | 3 | The asset.messagingAddress contains values that cannot be parsed as a phone number or email address. Returns an ErrorDetailInput as the errorDetails .. |
400 | 3 | One of the asset.pictures given in the array cannot be parsed, or is a value less than zero. Returns an ErrorDetailInput as the errorDetails .. |
400 | 3 | The asset.references were not provided as null or an object. Returns an ErrorDetailInput as the errorDetails .. |
400 | 3 | One of the asset.relationships given in the array cannot be parsed, or is a value less than zero. Returns an ErrorDetailInput as the errorDetails .. |
400 | 3 | During create: When creating a new Asset, too many asset.references were given as input. Returns an ErrorDetailMinMax as the errorDetails .. |
401 | 5 | You do not have permission to create a new Asset. |
401 | 5 | You do not have permission to update this Asset. |
400 | 6 | During update: When updating an Asset, an incorrect v value was given as input. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 20 | During update: When updating, the Asset was not found by its unique identifier. |
404 | 22 | One of the Assets given as input in the asset.relationships array was not found. Returns an ErrorDetailBadIds as the errorDetails .. |
404 | 31 | The asset.contact given as input was not found. |
404 | 33 | The asset.icon given as input was not found. |
404 | 69 | One of the asset.pictures given as input in the pictures array was not found. Returns an ErrorDetailBadIds as the errorDetails .. |
401 | 71 | During update: Changing the labels on this Asset in the requested way would grant you elevated access to it. Returns an ErrorDetailEscalation as the errorDetails .. |
403 | 96 | During update: When updating, the Asset is suspended. Before making changes to an Asset, it must be reactivated. |
409 | 130 | During update: When updating an Asset, the asset.company can not be changed. |
409 | 130 | During update: When updating an Asset, the asset.kind can not be changed. |
409 | 130 | During update: When updating an Asset, the resulting number of asset.references would be too high. |
DELETE/assets
Deletes an existing Asset.
Response description
Property | Type | Description |
---|---|---|
asset | RespDeleted | An object which contains the Asset's id, owning Company id, and deleted status. |
asset | uint64 | Identifier of the Company to which this object belongs. |
asset | boolean | Flag showing if the object is deleted. |
asset | uint64? | Identifier given as input for the command. |
asset | Array.<uint32> | |
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "asset": { "company": number, "deleted": boolean, "id": number, "v": [ number ] }, "errorCode": number, "errorDetails": { "kind": string }, "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
500 | 2 | A communication error occurred. If you receive this error, please contact technical support. |
400 | 3 | The request does not contain a asset object, or it is invalid. |
400 | 3 | The asset object does not contain an id, or it is invalid. |
401 | 5 | You do not have permission to delete this Asset. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 20 | The Asset was not found by its unique identifier. |
GET/assets/{assetId}?includeMessages=boolean&includeTasks=boolean&includeDeleted=boolean
Gets details of the specified Asset.
URL Parameters
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
assetId | uint64 | required | Unique identifier of the Asset. | |
includeDeleted | boolean | optional | When true, the command will also return deleted objects. | |
includeMessages | boolean | optional | false | When true, the command will also return AssetMessages for the asset. |
includeTasks | boolean | optional | false | When true, the command will also return the AssetDispatch for the asset. |
Response description
Property | Type | Description |
---|---|---|
asset | Asset | The requested Asset. |
asset | Object.<codified, AssetAttribute> for keys see: AssetAttribute.name | A list of attributes given to this asset by the connection device such as wiring state, VBus, etc. |
asset | uint64 see: Company.id | The company to which this asset belongs. |
asset | AssetDispatch | Current jobs dispatched and driving directions. |
asset | uint64 see: Company.id | The company to which this asset belongs. |
asset | Array.<DispatchDirection> | Driving directions and route path details. |
asset | uint64 see: Asset.id | Unique identifier of this asset. |
asset | Array.<uint64> see: DispatchJob | The current list of DispatchJobs assigned to the asset. |
asset | datetime | Timestamp from the last update to this AssetDispatch by a User, Machine, Asset, or an assigned DispatchJob. |
asset Deprecated | Array.<DispatchTask> | The current list of tasks assigned to this asset. |
asset | Array.<uint32> | Object version keys used to validate synchronization for all object properties. |
asset | uint64 see: Icon.id | The icon that represents this asset on the map and in lists. |
asset | uint64 | Unique identifier of this asset. |
asset | AssetType | Type of asset. |
asset | Array.<codified> for values see: LabelStyle.code | Codified label names. |
asset | Array.<AssetMessage> | A list of messages sent to or from this asset. |
asset | string maximum-length: 254 | The fall-back address which is used to send Messages if the asset is a Person and has no Contact phone or email. |
asset | string maximum-length: 100 | This thing's name. |
asset | string | Notes about it. |
asset | double | The cumulative distance travelled in kilometres. |
asset | Array.<uint64> for values see: Picture.id | A list of photos of this thing. |
asset | Object.<uint64, AssetPlaceStatus> for keys see: Place.id | The current state of this asset's interaction with known Places. |
asset | Position | The things GPS coordinates including speed, bearing, and street information. |
asset | uint32? | Threshold in meters for the accuracy of a position |
asset | string | The road segment description |
asset | double? | Distance in meters from the sea level |
asset | uint16? | Direction of travel |
asset | datetime | The Date/Time of the GPS reading |
asset | double? | Latitude |
asset | double? | Longitude |
asset | string | Provider Identifier |
asset | double? | Speed |
asset | double? | The posted speed limit for the road segment |
asset | StreetAddress | A better description of the current road-segment |
asset | string | City name. |
asset | string fixed length: 2 | Country code. Codes should be a value from ISO 3166-1 alpha-2. |
asset | boolean | Indicates that there is a toll for the current road segment. |
asset | string | House number. |
asset | string | Postal or zip code. |
asset | string fixed length: 2 | Province or state code. Codes should be a value from ISO 3166-2. |
asset | string | Region name. |
asset | string | Full street name. |
asset | Array.<string> for values see: Provider.id | The list of devices providing events for this asset. |
asset Deprecated | string maximum-length: 100 | A custom field used to refer to an external system. Use asset.references[AssetGeneral.REFERENCE] instead. |
asset | Object.<string, string> maximum-count: 10 maximum-length of keys: 20 maximum-length of values: 100 | Name/value collections of custom fields used to refer to external systems. |
asset | Array.<uint64> for values see: Asset.id | A list of assets related to this one; like a Person for a Vehicle (driver). |
asset | Array.<codified> for values see: LabelStyle.code | The codified status tag names. |
asset | Array.<int32> fixed count: 3 | Object version keys used to validate synchronization for all object properties. |
asset | int32 | The first element is for the AssetGeneral properties. |
asset | int32 | The second element is for the AssetAdvanced properties. |
asset | int32 | The third element is for the Asset.dispatch properties. |
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "asset": { "attributes": { string: { "asset": number, "complex": string, "dts": string, "global": boolean, "name": string, "provider": string, "raw": Object, "simple": string, "unit": string } }, "company": number, "dispatch": { "company": number, "directions": [ { "directions": [ { /* recursive DispatchDirection objects */ } ], "distance": number, "duration": string, "instructions": string, "job": number, "path": string, "step": number } ], "id": number, "jobs": [ number ], "lastDispatched": string, "tasks": [ { "address": string, "arrived": string, "asset": number, "attachments": [ number ], "company": number, "completed": string, "created": string, "duration": string, "eta": string, "id": number, "instructions": string, "latlng": { "lat": number, "lng": number }, "name": string, "notes": string, "place": number, "reference": string, "references": { string: string }, "signatory": string, "signature": boolean, "status": string, "v": [ number ] } ], "v": [ number ] }, "icon": number, "id": number, "kind": string, "labels": [ string ], "messages": [ { "asset": number, "body": string, "company": number, "delivered": string, "folder": string, "from": string, "id": number, "incoming": boolean, "kind": string, "processed": string, "readBy": string, "status": string, "subject": string, "to": string, "user": string, "v": [ number ] } ], "messagingAddress": string, "name": string, "notes": string, "odometer": number, "pictures": [ number ], "places": { string: { "enter": string, "kind": string, "latest": string } }, "position": { "accuracy": number, "address": string, "altitude": number, "bearing": number, "dts": string, "lat": number, "lng": number, "origin": string, "speed": number, "speedLimit": number, "streetAddress": { "city": string, "country": string, "isToll": boolean, "number": string, "postal": string, "province": string, "region": string, "street": string } }, "providers": [ string ], "reference": string, "references": { string: string }, "relationships": [ number ], "tags": [ string ], "v": [ number ] }, "errorCode": number, "errorDetails": { "kind": string }, "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
400 | 3 | The request does not contain a asset object, or it is invalid. |
400 | 3 | The asset object does not contain an id, or it is invalid. |
401 | 5 | You do not have permission to view this Asset. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 20 | The Asset was not found by its unique identifier. |
POST/assets/{assetId}
Creates a new, or updates an existing Asset.
URL Parameters
Parameter | Type | Required | Description |
---|---|---|---|
assetId | uint64? | optional | Unique identifier of the Asset. This value is optional, and ignored by the command. |
HTTP Request body description
Property | Type | Required | Description |
---|---|---|---|
asset | Object.<string, ?> | always | A simple object to contain the Asset parameters. |
asset | Object.<string, AssetAttribute> | optional | Allows you to add, remove, and replace attributes. For each AssetAttribute in the attributes object, the value will be replaced on the Asset. If value is null, the attribute is removed from the Asset. If the key in the attributes object is different from the codified(AssetAttribute.name) in the object, the attribute of the key is removed from the Asset, and one of the codified name is added to the Asset. If a new value or null is not provided for a current attribute, no change is made. |
asset | colour maximum-length: 22 | optional | The pretty-pretty colour of this Vehicle or Trailer.
Only applicable if asset.kind is AssetType.vehicle or AssetType.trailer. |
asset | uint64? | create | The identifier of the Company to which this Asset belongs. After creation, this value is read-only. |
asset | uint64? | create (for person) | The contact card details for this Asset.
Only applicable if asset.kind is AssetType.person. |
asset | double? | optional | The number of hours the engine has been running for this Vehicle.
Only applicable if asset.kind is AssetType.vehicle. |
asset | uint64? see: Icon.id | create | The identifier of the Icon used to represent this Asset in the UI. |
asset | uint64? | update | The unique identifier of the Asset you want to update. |
asset | AssetType? | create | The kind of Asset being created. After creation, this value is read-only. |
asset | Array.<codified> for values see: LabelStyle.code | optional | A list of codified label names to categorize/organize this Asset. |
asset | string | optional | The manufacturer of this Vehicle or Trailer.
Only applicable if asset.kind is AssetType.vehicle or AssetType.trailer. |
asset | string | optional | The email address or phone number of this Asset when a Person's Contact card is blank, or the Provider's PND is not installed. |
asset | string | optional | The model of this Vehicle or Trailer.
Only applicable if asset.kind is AssetType.vehicle or AssetType.trailer. |
asset | string maximum-length: 100 | create | Name for the Asset. |
asset | string | optional | Notes for the Asset. |
asset | double? | optional | The distance travelled by this Asset. Can be a GPS odometer, OBD-II odometer, or other depending on scripts. |
asset | Array.<uint64> for values see: Picture.id | optional | The identifiers of Pictures of this Asset. |
asset | string | optional | The license plate of this Vehicle or Trailer.
Only applicable if asset.kind is AssetType.vehicle or AssetType.trailer. |
asset | Object.<string, string> | optional | Name/value collections of custom fields used to refer to external systems. If the value is null, the references are removed from the Asset. |
asset | Array.<uint64> for values see: Asset.id | optional | A list of related asset identifiers like a driver for a Vehicle, or Trailer for a truck. |
asset | string | optional | The manufacturer's identification number of this Trailer.
Only applicable if asset.kind is AssetType.vehicle. |
asset | Array.<string> | optional | Replaces the Asset's status tags with the given list of codified tags. |
asset | Array.<int32> | optional | |
asset | string | optional | The Vehicle Identification Number of this Vehicle.
Only applicable if asset.kind is AssetType.trailer. |
asset | uint16? | optional | The year this Vehicle or Trailer was built.
Only applicable if asset.kind is AssetType.vehicle or AssetType.trailer. |
reqId | int32? | optional | Identifier used by external system to correlate requests to responses. |
HTTP Request body structure
{ "asset": { "attributes": { string: { "asset": number, "complex": string, "dts": string, "global": boolean, "name": string, "provider": string, "raw": Object, "simple": string, "unit": string } }, "colour": string, "company": number, "contact": number, "engineHours": number, "icon": number, "id": number, "kind": string, "labels": [ string ], "make": string, "messagingAddress": string, "model": string, "name": string, "notes": string, "odometer": number, "pictures": [ number ], "plate": string, "references": { string: string }, "relationships": [ number ], "serial": string, "tags": [ string ], "v": [ number ], "vin": string, "year": number }, "reqId": number }
Response description
Property | Type | Description |
---|---|---|
asset | RespIdCompany | An object which contains the "id" and "company" keys. |
asset | uint64 | Identifier of the Company to which this object belongs. |
asset | uint64? | Identifier given as input for the command. |
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "asset": { "company": number, "id": number }, "errorCode": number, "errorDetails": { "kind": string }, "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
500 | 2 | A communication error occurred. If you receive this error, please contact technical support. |
400 | 3 | The request does not contain a asset object, or it is invalid. |
400 | 3 | No valid changes would be performed. |
400 | 3 | During create: When creating a new Asset, a name was not given. |
400 | 3 | During create: When creating a new Asset, a company was not given. |
400 | 3 | During create: When creating a new Asset, an icon was not given. |
400 | 3 | During create (for person): When creating a new Person, a contact was not given. |
400 | 3 | During update: When updating an Asset, the name was given as null or blank. |
400 | 3 | During update: When updating an Asset, the v was not an array, or contained too few numbers. |
400 | 3 | During create: The kind value is not a known AssetType. Returns an ErrorDetailEnum as the errorDetails .. |
400 | 3 | One of the asset.attributes names is invalid. Returns an ErrorDetailInput as the errorDetails .. |
400 | 3 | One of the asset.attributes values is not null or an object. Returns an ErrorDetailInput as the errorDetails .. |
400 | 3 | The asset.attributes object is given, but empty. Returns an ErrorDetailInput as the errorDetails .. |
400 | 3 | The asset.messagingAddress contains values that cannot be parsed as a phone number or email address. Returns an ErrorDetailInput as the errorDetails .. |
400 | 3 | One of the asset.pictures given in the array cannot be parsed, or is a value less than zero. Returns an ErrorDetailInput as the errorDetails .. |
400 | 3 | The asset.references were not provided as null or an object. Returns an ErrorDetailInput as the errorDetails .. |
400 | 3 | One of the asset.relationships given in the array cannot be parsed, or is a value less than zero. Returns an ErrorDetailInput as the errorDetails .. |
400 | 3 | During create: When creating a new Asset, too many asset.references were given as input. Returns an ErrorDetailMinMax as the errorDetails .. |
401 | 5 | You do not have permission to create a new Asset. |
401 | 5 | You do not have permission to update this Asset. |
400 | 6 | During update: When updating an Asset, an incorrect v value was given as input. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 20 | During update: When updating, the Asset was not found by its unique identifier. |
404 | 22 | One of the Assets given as input in the asset.relationships array was not found. Returns an ErrorDetailBadIds as the errorDetails .. |
404 | 31 | The asset.contact given as input was not found. |
404 | 33 | The asset.icon given as input was not found. |
404 | 69 | One of the asset.pictures given as input in the pictures array was not found. Returns an ErrorDetailBadIds as the errorDetails .. |
401 | 71 | During update: Changing the labels on this Asset in the requested way would grant you elevated access to it. Returns an ErrorDetailEscalation as the errorDetails .. |
403 | 96 | During update: When updating, the Asset is suspended. Before making changes to an Asset, it must be reactivated. |
409 | 130 | During update: When updating an Asset, the asset.company can not be changed. |
409 | 130 | During update: When updating an Asset, the asset.kind can not be changed. |
409 | 130 | During update: When updating an Asset, the resulting number of asset.references would be too high. |
DELETE/assets/{assetId}
Deletes an existing Asset.
URL Parameters
Parameter | Type | Required | Description |
---|---|---|---|
assetId | uint64 | required | Unique identifier of the Asset. |
Response description
Property | Type | Description |
---|---|---|
asset | RespDeleted | An object which contains the Asset's id, owning Company id, and deleted status. |
asset | uint64 | Identifier of the Company to which this object belongs. |
asset | boolean | Flag showing if the object is deleted. |
asset | uint64? | Identifier given as input for the command. |
asset | Array.<uint32> | |
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "asset": { "company": number, "deleted": boolean, "id": number, "v": [ number ] }, "errorCode": number, "errorDetails": { "kind": string }, "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
500 | 2 | A communication error occurred. If you receive this error, please contact technical support. |
400 | 3 | The request does not contain a asset object, or it is invalid. |
400 | 3 | The asset object does not contain an id, or it is invalid. |
401 | 5 | You do not have permission to delete this Asset. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 20 | The Asset was not found by its unique identifier. |
PATCH/assets/{assetId}/restore
Restores the specified Asset.
URL Parameters
Parameter | Type | Required | Description |
---|---|---|---|
assetId | uint64 | required | Unique identifier of the Asset. |
Response description
Property | Type | Description |
---|---|---|
asset | RespDeleted | An object which contains the Asset's id, owning Company id, and deleted status. |
asset | uint64 | Identifier of the Company to which this object belongs. |
asset | boolean | Flag showing if the object is deleted. |
asset | uint64? | Identifier given as input for the command. |
asset | Array.<uint32> | |
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "asset": { "company": number, "deleted": boolean, "id": number, "v": [ number ] }, "errorCode": number, "errorDetails": { "kind": string }, "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
500 | 2 | A communication error occurred. If you receive this error, please contact technical support. |
400 | 3 | The request does not contain a asset object, or it is invalid. |
400 | 3 | The asset object does not contain an id, or it is invalid. |
401 | 5 | You do not have permission to restore this Asset. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 20 | The Asset was not found by its unique identifier. |
400 | 21 | The Asset was found, but is not marked as deleted. |
PATCH/assets/{assetId}/revive
Revives (disables suspension on) an existing Asset.
URL Parameters
Parameter | Type | Required | Description |
---|---|---|---|
assetId | uint64 | required | Unique identifier of the Asset. |
Response description
Property | Type | Description |
---|---|---|
asset | RespSuspended | An object which contains the Asset's unique identifier and suspended status. |
asset | uint64 | Identifier of the Company to which this object belongs. |
asset | uint64? | Identifier given as input for the command. |
asset | boolean | Flag showing if the object is suspended. |
asset | Array.<uint32> | |
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "asset": { "company": number, "id": number, "suspended": boolean, "v": [ number ] }, "errorCode": number, "errorDetails": { "kind": string }, "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
500 | 2 | A communication error occurred. If you receive this error, please contact technical support. |
400 | 3 | The request does not contain a asset object, or it is invalid. |
400 | 3 | The asset object does not contain an id, or it is invalid. |
401 | 5 | You do not have permission to revive this Asset. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 20 | The Asset was not found by its unique identifier. |
403 | 97 | The Asset was found, but is not marked as suspended. |
PATCH/assets/{assetId}/suspend
Suspends an existing Asset.
URL Parameters
Parameter | Type | Required | Description |
---|---|---|---|
assetId | uint64 | required | Unique identifier of the Asset. |
Response description
Property | Type | Description |
---|---|---|
asset | RespSuspended | An object which contains the Asset's unique identifier and suspended status. |
asset | uint64 | Identifier of the Company to which this object belongs. |
asset | uint64? | Identifier given as input for the command. |
asset | boolean | Flag showing if the object is suspended. |
asset | Array.<uint32> | |
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "asset": { "company": number, "id": number, "suspended": boolean, "v": [ number ] }, "errorCode": number, "errorDetails": { "kind": string }, "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
500 | 2 | A communication error occurred. If you receive this error, please contact technical support. |
400 | 3 | The request does not contain a asset object, or it is invalid. |
400 | 3 | The asset object does not contain an id, or it is invalid. |
401 | 5 | You do not have permission to suspended this Asset. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 20 | The Asset was not found by its unique identifier. |
403 | 96 | The Asset was not found, but it is already marked as suspended. |
403 | 97 | The Asset was previously revived within the minimum period. Returns an ErrorDetailLocked as the errorDetails .. |
PATCH/assets/revive
Revives (disables suspension on) an existing Asset.
Response description
Property | Type | Description |
---|---|---|
asset | RespSuspended | An object which contains the Asset's unique identifier and suspended status. |
asset | uint64 | Identifier of the Company to which this object belongs. |
asset | uint64? | Identifier given as input for the command. |
asset | boolean | Flag showing if the object is suspended. |
asset | Array.<uint32> | |
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "asset": { "company": number, "id": number, "suspended": boolean, "v": [ number ] }, "errorCode": number, "errorDetails": { "kind": string }, "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
500 | 2 | A communication error occurred. If you receive this error, please contact technical support. |
400 | 3 | The request does not contain a asset object, or it is invalid. |
400 | 3 | The asset object does not contain an id, or it is invalid. |
401 | 5 | You do not have permission to revive this Asset. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 20 | The Asset was not found by its unique identifier. |
403 | 97 | The Asset was found, but is not marked as suspended. |
PATCH/assets/suspend
Suspends an existing Asset.
Response description
Property | Type | Description |
---|---|---|
asset | RespSuspended | An object which contains the Asset's unique identifier and suspended status. |
asset | uint64 | Identifier of the Company to which this object belongs. |
asset | uint64? | Identifier given as input for the command. |
asset | boolean | Flag showing if the object is suspended. |
asset | Array.<uint32> | |
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "asset": { "company": number, "id": number, "suspended": boolean, "v": [ number ] }, "errorCode": number, "errorDetails": { "kind": string }, "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
500 | 2 | A communication error occurred. If you receive this error, please contact technical support. |
400 | 3 | The request does not contain a asset object, or it is invalid. |
400 | 3 | The asset object does not contain an id, or it is invalid. |
401 | 5 | You do not have permission to suspended this Asset. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 20 | The Asset was not found by its unique identifier. |
403 | 96 | The Asset was not found, but it is already marked as suspended. |
403 | 97 | The Asset was previously revived within the minimum period. Returns an ErrorDetailLocked as the errorDetails .. |
GET/assets ?labels={string}&includeSuspended=boolean&includeMessages=boolean&includeTasks=boolean&includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number
This request is an alias of /companies/{your-company-id}/assets?labels={labels}.
URL Parameters
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
labels | string | optional | Labels to match the DispatchJob. | |
your-company-id | uint64 | aliased | {your-company-id} | Your own Company's identifier. |
GET/companies/{companyId}/assets?includeSuspended=boolean&includeMessages=boolean&includeTasks=boolean&includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number
URL Parameters
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
companyId | uint64 | required | Unique identifier of the Company. | |
highest | uint64? | optional | The largest valued id objects to retrieve. | |
includeArchive | boolean | optional | When true, the command will also return archived objects. | |
includeDeleted | boolean | optional | When true, the command will also return deleted objects. | |
includeMessages | boolean | optional | false | When true, the command will also return AssetMessages for the asset. |
includeSuspended | boolean | optional | true | When true (default), the command will also return Assets marked as Asset.suspended. |
includeTasks | boolean | optional | false | When true, the command will also return the DispatchTasks for the asset. |
limit | uint16? | optional | Maximum number of objects in this response. | |
lowest | uint64? | optional | The smallest valued id objects to retrieve. |
Response description
Property | Type | Description |
---|---|---|
assets | Array.<Asset> | The list of requested Assets. |
company | RespId | An object to contain the "id" of the Company to which the array of Assets belong. |
company | uint64? | Identifier given as input for the command. |
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "assets": [ { "attributes": { string: { "asset": number, "complex": string, "dts": string, "global": boolean, "name": string, "provider": string, "raw": Object, "simple": string, "unit": string } }, "company": number, "dispatch": { "company": number, "directions": [ { "directions": [ { /* recursive DispatchDirection objects */ } ], "distance": number, "duration": string, "instructions": string, "job": number, "path": string, "step": number } ], "id": number, "jobs": [ number ], "lastDispatched": string, "tasks": [ { "address": string, "arrived": string, "asset": number, "attachments": [ number ], "company": number, "completed": string, "created": string, "duration": string, "eta": string, "id": number, "instructions": string, "latlng": { "lat": number, "lng": number }, "name": string, "notes": string, "place": number, "reference": string, "references": { string: string }, "signatory": string, "signature": boolean, "status": string, "v": [ number ] } ], "v": [ number ] }, "icon": number, "id": number, "kind": string, "labels": [ string ], "messages": [ { "asset": number, "body": string, "company": number, "delivered": string, "folder": string, "from": string, "id": number, "incoming": boolean, "kind": string, "processed": string, "readBy": string, "status": string, "subject": string, "to": string, "user": string, "v": [ number ] } ], "messagingAddress": string, "name": string, "notes": string, "odometer": number, "pictures": [ number ], "places": { string: { "enter": string, "kind": string, "latest": string } }, "position": { "accuracy": number, "address": string, "altitude": number, "bearing": number, "dts": string, "lat": number, "lng": number, "origin": string, "speed": number, "speedLimit": number, "streetAddress": { "city": string, "country": string, "isToll": boolean, "number": string, "postal": string, "province": string, "region": string, "street": string } }, "providers": [ string ], "reference": string, "references": { string: string }, "relationships": [ number ], "tags": [ string ], "v": [ number ] } ], "company": { "id": number }, "errorCode": number, "errorDetails": { "kind": string }, "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
400 | 3 | The request does not contain a company object, or it is invalid. |
400 | 3 | The company object does not contain an id, or it is invalid. |
401 | 5 | You do not have permission to view any Assets for this Company. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 28 | The Company was not found by its unique identifier. |
GET/companies/{companyId}/assets ?{keys=values}?includeSuspended=boolean&includeMessages=boolean&includeTasks=boolean&includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number&{keys=values}
Gets the list of Assets for the specified Company only if one of the specified Asset.references fields match.
If no references are specified, it will match any Asset with no references.
If a reference value is null, it will match any Asset without that reference key.
URL Parameters
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
companyId | uint64 | required | Unique identifier of the Company. | |
highest | uint64? | optional | The largest valued id objects to retrieve. | |
includeArchive | boolean | optional | When true, the command will also return archived objects. | |
includeDeleted | boolean | optional | When true, the command will also return deleted objects. | |
includeMessages | boolean | optional | false | When true, the command will also return AssetMessages for the asset. |
includeSuspended | boolean | optional | true | When true (default), the command will also return Assets marked as Asset.suspended. |
includeTasks | boolean | optional | false | When true, the command will also return the DispatchTasks for the asset. |
limit | uint16? | optional | Maximum number of objects in this response. | |
lowest | uint64? | optional | The smallest valued id objects to retrieve. |
Response description
Property | Type | Description |
---|---|---|
assets | Array.<Asset> | The list of requested Assets. |
company | RespId | An object to contain the "id" of the Company to which the array of Assets belong. |
company | uint64? | Identifier given as input for the command. |
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
message | string | An English description of the error. |
references | Object.<string, string> | The reference string given as input. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "assets": [ { "attributes": { string: { "asset": number, "complex": string, "dts": string, "global": boolean, "name": string, "provider": string, "raw": Object, "simple": string, "unit": string } }, "company": number, "dispatch": { "company": number, "directions": [ { "directions": [ { /* recursive DispatchDirection objects */ } ], "distance": number, "duration": string, "instructions": string, "job": number, "path": string, "step": number } ], "id": number, "jobs": [ number ], "lastDispatched": string, "tasks": [ { "address": string, "arrived": string, "asset": number, "attachments": [ number ], "company": number, "completed": string, "created": string, "duration": string, "eta": string, "id": number, "instructions": string, "latlng": { "lat": number, "lng": number }, "name": string, "notes": string, "place": number, "reference": string, "references": { string: string }, "signatory": string, "signature": boolean, "status": string, "v": [ number ] } ], "v": [ number ] }, "icon": number, "id": number, "kind": string, "labels": [ string ], "messages": [ { "asset": number, "body": string, "company": number, "delivered": string, "folder": string, "from": string, "id": number, "incoming": boolean, "kind": string, "processed": string, "readBy": string, "status": string, "subject": string, "to": string, "user": string, "v": [ number ] } ], "messagingAddress": string, "name": string, "notes": string, "odometer": number, "pictures": [ number ], "places": { string: { "enter": string, "kind": string, "latest": string } }, "position": { "accuracy": number, "address": string, "altitude": number, "bearing": number, "dts": string, "lat": number, "lng": number, "origin": string, "speed": number, "speedLimit": number, "streetAddress": { "city": string, "country": string, "isToll": boolean, "number": string, "postal": string, "province": string, "region": string, "street": string } }, "providers": [ string ], "reference": string, "references": { string: string }, "relationships": [ number ], "tags": [ string ], "v": [ number ] } ], "company": { "id": number }, "errorCode": number, "errorDetails": { "kind": string }, "message": string, "references": { string: string }, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
400 | 3 | The request does not contain a company object, or it is invalid. |
400 | 3 | The company object does not contain an id, or it is invalid. |
400 | 3 | The references is not an object, or it is invalid. |
401 | 5 | You do not have permission to view any Assets for this Company. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 28 | The Company was not found by its unique identifier. |
GET/companies/{companyId}/assets ?labels={string}&includeSuspended=boolean&includeMessages=boolean&includeTasks=boolean&includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number
Gets the list of Assets for the specified Company only if the Asset.labels matches all of the given labels.
URL Parameters
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
companyId | uint64 | required | Unique identifier of the Company. | |
highest | uint64? | optional | The largest valued id objects to retrieve. | |
includeArchive | boolean | optional | When true, the command will also return archived objects. | |
includeDeleted | boolean | optional | When true, the command will also return deleted objects. | |
includeMessages | boolean | optional | false | When true, the command will also return AssetMessages for the asset. |
includeSuspended | boolean | optional | true | When true (default), the command will also return Assets marked as Asset.suspended. |
includeTasks | boolean | optional | false | When true, the command will also return the DispatchTasks for the asset. |
labels | string | required | Labels to match the DispatchJob. | |
limit | uint16? | optional | Maximum number of objects in this response. | |
lowest | uint64? | optional | The smallest valued id objects to retrieve. |
Response description
Property | Type | Description |
---|---|---|
assets | Array.<Asset> | The list of requested Assets. |
company | RespId | An object to contain the "id" of the Company to which the array of Assets belong. |
company | uint64? | Identifier given as input for the command. |
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
labels | Array.<string> | The labels given as input. |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "assets": [ { "attributes": { string: { "asset": number, "complex": string, "dts": string, "global": boolean, "name": string, "provider": string, "raw": Object, "simple": string, "unit": string } }, "company": number, "dispatch": { "company": number, "directions": [ { "directions": [ { /* recursive DispatchDirection objects */ } ], "distance": number, "duration": string, "instructions": string, "job": number, "path": string, "step": number } ], "id": number, "jobs": [ number ], "lastDispatched": string, "tasks": [ { "address": string, "arrived": string, "asset": number, "attachments": [ number ], "company": number, "completed": string, "created": string, "duration": string, "eta": string, "id": number, "instructions": string, "latlng": { "lat": number, "lng": number }, "name": string, "notes": string, "place": number, "reference": string, "references": { string: string }, "signatory": string, "signature": boolean, "status": string, "v": [ number ] } ], "v": [ number ] }, "icon": number, "id": number, "kind": string, "labels": [ string ], "messages": [ { "asset": number, "body": string, "company": number, "delivered": string, "folder": string, "from": string, "id": number, "incoming": boolean, "kind": string, "processed": string, "readBy": string, "status": string, "subject": string, "to": string, "user": string, "v": [ number ] } ], "messagingAddress": string, "name": string, "notes": string, "odometer": number, "pictures": [ number ], "places": { string: { "enter": string, "kind": string, "latest": string } }, "position": { "accuracy": number, "address": string, "altitude": number, "bearing": number, "dts": string, "lat": number, "lng": number, "origin": string, "speed": number, "speedLimit": number, "streetAddress": { "city": string, "country": string, "isToll": boolean, "number": string, "postal": string, "province": string, "region": string, "street": string } }, "providers": [ string ], "reference": string, "references": { string: string }, "relationships": [ number ], "tags": [ string ], "v": [ number ] } ], "company": { "id": number }, "errorCode": number, "errorDetails": { "kind": string }, "labels": [ string ], "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
400 | 3 | The request does not contain a company object, or it is invalid. |
400 | 3 | The company object does not contain an id, or it is invalid. |
400 | 3 | The labels is not an array. |
401 | 5 | You do not have permission to view any Assets for this Company. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 28 | The Company was not found by its unique identifier. |
GET/companies/{companyId}/assets ?reference={string}&includeSuspended=boolean&includeMessages=boolean&includeTasks=boolean&includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number
URL Parameters
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
companyId | uint64 | required | Unique identifier of the Company. | |
highest | uint64? | optional | The largest valued id objects to retrieve. | |
includeArchive | boolean | optional | When true, the command will also return archived objects. | |
includeDeleted | boolean | optional | When true, the command will also return deleted objects. | |
includeMessages | boolean | optional | false | When true, the command will also return AssetMessages for the asset. |
includeSuspended | boolean | optional | true | When true (default), the command will also return Assets marked as Asset.suspended. |
includeTasks | boolean | optional | false | When true, the command will also return the DispatchTasks for the asset. |
limit | uint16? | optional | Maximum number of objects in this response. | |
lowest | uint64? | optional | The smallest valued id objects to retrieve. | |
reference | string | required | Value to search in the asset.reference["Reference"] field |
Response description
Property | Type | Description |
---|---|---|
assets | Array.<Asset> | The list of requested Assets. |
company | RespId | An object to contain the "id" of the Company to which the array of Assets belong. |
company | uint64? | Identifier given as input for the command. |
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
message | string | An English description of the error. |
reference | string | The reference string given as input. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "assets": [ { "attributes": { string: { "asset": number, "complex": string, "dts": string, "global": boolean, "name": string, "provider": string, "raw": Object, "simple": string, "unit": string } }, "company": number, "dispatch": { "company": number, "directions": [ { "directions": [ { /* recursive DispatchDirection objects */ } ], "distance": number, "duration": string, "instructions": string, "job": number, "path": string, "step": number } ], "id": number, "jobs": [ number ], "lastDispatched": string, "tasks": [ { "address": string, "arrived": string, "asset": number, "attachments": [ number ], "company": number, "completed": string, "created": string, "duration": string, "eta": string, "id": number, "instructions": string, "latlng": { "lat": number, "lng": number }, "name": string, "notes": string, "place": number, "reference": string, "references": { string: string }, "signatory": string, "signature": boolean, "status": string, "v": [ number ] } ], "v": [ number ] }, "icon": number, "id": number, "kind": string, "labels": [ string ], "messages": [ { "asset": number, "body": string, "company": number, "delivered": string, "folder": string, "from": string, "id": number, "incoming": boolean, "kind": string, "processed": string, "readBy": string, "status": string, "subject": string, "to": string, "user": string, "v": [ number ] } ], "messagingAddress": string, "name": string, "notes": string, "odometer": number, "pictures": [ number ], "places": { string: { "enter": string, "kind": string, "latest": string } }, "position": { "accuracy": number, "address": string, "altitude": number, "bearing": number, "dts": string, "lat": number, "lng": number, "origin": string, "speed": number, "speedLimit": number, "streetAddress": { "city": string, "country": string, "isToll": boolean, "number": string, "postal": string, "province": string, "region": string, "street": string } }, "providers": [ string ], "reference": string, "references": { string: string }, "relationships": [ number ], "tags": [ string ], "v": [ number ] } ], "company": { "id": number }, "errorCode": number, "errorDetails": { "kind": string }, "message": string, "reference": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
400 | 3 | The request does not contain a company object, or it is invalid. |
400 | 3 | The company object does not contain an id, or it is invalid. |
400 | 3 | The reference is blank or null. |
401 | 5 | You do not have permission to view any Assets for this Company. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 28 | The Company was not found by its unique identifier. |
Behaviours
GET/behaviours?includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number
This request is an alias of /companies/{your-company-id}/behaviours/.
URL Parameters
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
your-company-id | uint64 | aliased | {your-company-id} | Your own Company's identifier. |
PATCH/behaviours
Creates a new or updates an existing Behaviour.
Response description
Property | Type | Description |
---|---|---|
behaviour | RespIdScript | An object which contains the "id", "company", and "script" keys when there is no error. |
behaviour | uint64 | Identifier of the Company to which this object belongs. |
behaviour | uint64? | Identifier given as input for the command. |
behaviour | uint64 | Identifier of the script to which this object belongs. |
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "behaviour": { "company": number, "id": number, "script": number }, "errorCode": number, "errorDetails": { "kind": string }, "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
500 | 2 | A communication error occurred. If you receive this error, please contact technical support. |
400 | 3 | The request does not contain a behaviour object, or it is invalid. |
400 | 3 | Not enough keys exist in the behaviour object. |
400 | 3 | During create: When creating a new Behaviour, a name was not given, or it is invalid. |
400 | 3 | During create: When creating a new Behaviour, a script was not given. |
400 | 3 | During create: When creating a new Behaviour, a company was not given. |
400 | 3 | During update: When updating a Behaviour, the id was invalid. |
400 | 3 | During update: When updating a Behaviour, the name was given as blank. |
400 | 3 | During update: When updating a Behaviour, the v was not an array, or contained too few numbers. |
400 | 3 | The targets was given as null or blank. The targets must always have a value, or you can not send the targets key. Returns an ErrorDetailInput as the errorDetails .. |
400 | 3 | One of the behaviour.parameters was invalid. Returns an ErrorDetailInput as the errorDetails .. |
400 | 3 | One of the behaviour.parameters keys was blank or white-space. Returns an ErrorDetailInput as the errorDetails .. |
401 | 5 | You do not have permission to create a new Behaviour. |
401 | 5 | You do not have permission to update this Behaviour. |
400 | 6 | During update: When updating a Behaviour, an incorrect v value was given as input. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 23 | During update: The BehaviourScript was not found by its unique identifier. |
404 | 26 | During update: The Behaviour was not found by its unique identifier. |
409 | 130 | There is one or more missing or invalid parameters required by the BehaviourScript. Returns an ErrorDetailBadKeys as the errorDetails .. |
409 | 130 | During update: When updating a Behaviour, the behaviour.script can not be changed. Returns an ErrorDetailBadKeys as the errorDetails .. |
409 | 130 | During update: When updating a Behaviour, the behaviour.company can not be changed. Returns an ErrorDetailBadKeys as the errorDetails .. |
DELETE/behaviours
Deletes a Behaviour.
Response description
Property | Type | Description |
---|---|---|
behaviour | RespDeleted | An object which contains the Behaviour's id, owning Company id, and deleted status. |
behaviour | uint64 | Identifier of the Company to which this object belongs. |
behaviour | boolean | Flag showing if the object is deleted. |
behaviour | uint64? | Identifier given as input for the command. |
behaviour | Array.<uint32> | |
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "behaviour": { "company": number, "deleted": boolean, "id": number, "v": [ number ] }, "errorCode": number, "errorDetails": { "kind": string }, "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
500 | 2 | A communication error occurred. If you receive this error, please contact technical support. |
400 | 3 | The request does not contain a behaviour object, or it is invalid. |
400 | 3 | The behaviour object does not contain an id, or it is invalid. |
401 | 5 | You do not have permission to delete this Behaviour. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 26 | The Behaviour was not found by its unique identifier. |
GET/behaviours/{behaviourId}?includeDeleted=boolean
Gets details of the specified Behaviour.
URL Parameters
Parameter | Type | Required | Description |
---|---|---|---|
behaviourId | uint64 | required | Unique identifier of the Behaviour. |
includeDeleted | boolean | optional | When true, the command will also return deleted objects. |
Response description
Property | Type | Description |
---|---|---|
behaviour | Behaviour | The requested Behaviour. |
behaviour | uint64 see: Company.id | The company to which this behaviour belongs. |
behaviour | expression | A search pattern used to filter the providers which can implement this behaviour. |
behaviour | uint64 | Unique identifier of this behaviour. |
behaviour | string maximum-length: 100 | The name of this behaviour. |
behaviour | string | Notes. |
behaviour | Object.<string, BehaviourParameter> | The list of defined variable name/value pairs for the script requires. |
behaviour | byte | The priority flag allows you to define an execution order for all behaviours for a provider. |
behaviour | uint64 see: BehaviourScript.id | The script which this behaviour implements. |
behaviour | expression | The search pattern used to target the assets which will embed this behaviour in their execution context. |
behaviour | Array.<uint32> | Object version keys used to validate synchronization for all object properties. |
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "behaviour": { "company": number, "filters": string, "id": number, "name": string, "notes": string, "parameters": { string: { "context": string, "notes": string, "type": string, "value": string } }, "priority": number, "script": number, "targets": string, "v": [ number ] }, "errorCode": number, "errorDetails": { "kind": string }, "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
400 | 3 | The request does not contain a behaviour object, or it is invalid. |
400 | 3 | The behaviour object does not contain an id, or it is invalid. |
401 | 5 | You do not have permission to view this Behaviour. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 26 | The Behaviour was not found by its unique identifier. |
POST/behaviours/{behaviourId}
Creates a new or updates an existing Behaviour.
URL Parameters
Parameter | Type | Required | Description |
---|---|---|---|
behaviourId | uint64? | optional | Unique identifier of the Behaviour. This value is optional, and ignored by the command. |
HTTP Request body description
Property | Type | Required | Description |
---|---|---|---|
behaviour | Object.<string, ?> | always | A simple object to contain the Behaviour parameters. |
behaviour | uint64? | create | |
behaviour | expression | optional | A search pattern used to select the assets which will embed this Behaviour in their execution context. |
behaviour | uint64? | update | The unique identifier of the Behaviour you want to update. |
behaviour | string maximum-length: 100 | create | Name for the Behaviour. |
behaviour | string | optional | Notes for the Behaviour. |
behaviour | Object.<string, BehaviourParameter> | optional | The values needed to implement the script. Each key in this object is the name of a required script argument. |
behaviour | byte? | optional | The order in which this Behaviour is executed. |
behaviour | uint64? | create | Identifier of the BehaviourScript to which this Behaviour belongs. After creation, this value is read-only. |
behaviour | expression | optional | A search pattern used to select the providers which can implement this Behaviour. |
behaviour | Array.<int32> | optional | |
reqId | int32? | optional | Identifier used by external system to correlate requests to responses. |
HTTP Request body structure
{ "behaviour": { "company": number, "filters": string, "id": number, "name": string, "notes": string, "parameters": { string: { "context": string, "notes": string, "type": string, "value": string } }, "priority": number, "script": number, "targets": string, "v": [ number ] }, "reqId": number }
Response description
Property | Type | Description |
---|---|---|
behaviour | RespIdScript | An object which contains the "id", "company", and "script" keys when there is no error. |
behaviour | uint64 | Identifier of the Company to which this object belongs. |
behaviour | uint64? | Identifier given as input for the command. |
behaviour | uint64 | Identifier of the script to which this object belongs. |
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "behaviour": { "company": number, "id": number, "script": number }, "errorCode": number, "errorDetails": { "kind": string }, "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
500 | 2 | A communication error occurred. If you receive this error, please contact technical support. |
400 | 3 | The request does not contain a behaviour object, or it is invalid. |
400 | 3 | Not enough keys exist in the behaviour object. |
400 | 3 | During create: When creating a new Behaviour, a name was not given, or it is invalid. |
400 | 3 | During create: When creating a new Behaviour, a script was not given. |
400 | 3 | During create: When creating a new Behaviour, a company was not given. |
400 | 3 | During update: When updating a Behaviour, the id was invalid. |
400 | 3 | During update: When updating a Behaviour, the name was given as blank. |
400 | 3 | During update: When updating a Behaviour, the v was not an array, or contained too few numbers. |
400 | 3 | The targets was given as null or blank. The targets must always have a value, or you can not send the targets key. Returns an ErrorDetailInput as the errorDetails .. |
400 | 3 | One of the behaviour.parameters was invalid. Returns an ErrorDetailInput as the errorDetails .. |
400 | 3 | One of the behaviour.parameters keys was blank or white-space. Returns an ErrorDetailInput as the errorDetails .. |
401 | 5 | You do not have permission to create a new Behaviour. |
401 | 5 | You do not have permission to update this Behaviour. |
400 | 6 | During update: When updating a Behaviour, an incorrect v value was given as input. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 23 | During update: The BehaviourScript was not found by its unique identifier. |
404 | 26 | During update: The Behaviour was not found by its unique identifier. |
409 | 130 | There is one or more missing or invalid parameters required by the BehaviourScript. Returns an ErrorDetailBadKeys as the errorDetails .. |
409 | 130 | During update: When updating a Behaviour, the behaviour.script can not be changed. Returns an ErrorDetailBadKeys as the errorDetails .. |
409 | 130 | During update: When updating a Behaviour, the behaviour.company can not be changed. Returns an ErrorDetailBadKeys as the errorDetails .. |
DELETE/behaviours/{behaviourId}
Deletes a Behaviour.
URL Parameters
Parameter | Type | Required | Description |
---|---|---|---|
behaviourId | uint64 | required | Unique identifier of the Behaviour. |
Response description
Property | Type | Description |
---|---|---|
behaviour | RespDeleted | An object which contains the Behaviour's id, owning Company id, and deleted status. |
behaviour | uint64 | Identifier of the Company to which this object belongs. |
behaviour | boolean | Flag showing if the object is deleted. |
behaviour | uint64? | Identifier given as input for the command. |
behaviour | Array.<uint32> | |
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "behaviour": { "company": number, "deleted": boolean, "id": number, "v": [ number ] }, "errorCode": number, "errorDetails": { "kind": string }, "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
500 | 2 | A communication error occurred. If you receive this error, please contact technical support. |
400 | 3 | The request does not contain a behaviour object, or it is invalid. |
400 | 3 | The behaviour object does not contain an id, or it is invalid. |
401 | 5 | You do not have permission to delete this Behaviour. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 26 | The Behaviour was not found by its unique identifier. |
GET/behaviours/{behaviourId}/logs?includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number
Gets the list of BehaviourLog for the specified Behaviour.
URL Parameters
Parameter | Type | Required | Description |
---|---|---|---|
behaviourId | uint64 | required | Unique identifier of the Behaviour. |
highest | uint64? | optional | The largest valued id objects to retrieve. |
includeArchive | boolean | optional | When true, the command will also return archived objects. |
includeDeleted | boolean | optional | When true, the command will also return deleted objects. |
limit | uint16? | optional | Maximum number of objects in this response. |
lowest | uint64? | optional | The smallest valued id objects to retrieve. |
Response description
Property | Type | Description |
---|---|---|
behaviour | RespIdScript | An object to contain the "id" of the Behaviour to which the array of BehaviourLogs belong. |
behaviour | uint64 | Identifier of the Company to which this object belongs. |
behaviour | uint64? | Identifier given as input for the command. |
behaviour | uint64 | Identifier of the script to which this object belongs. |
behaviourLogs | Array.<BehaviourLog> | The list of requested BehaviourLogs. |
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "behaviour": { "company": number, "id": number, "script": number }, "behaviourLogs": [ { "asset": number, "behaviour": number, "character": number, "company": number, "dts": string, "id": number, "kind": string, "line": number, "message": string, "script": number, "v": [ number ] } ], "errorCode": number, "errorDetails": { "kind": string }, "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
500 | 2 | A communication error occurred. If you receive this error, please contact technical support. |
400 | 3 | The request does not contain a behaviour object, or it is invalid. |
400 | 3 | The behaviour object does not contain an id, or it is invalid. |
401 | 5 | You do not have permission to view BehaviourLogs for this Behaviour. |
401 | 5 | You do not have permission to view Behaviours for this Company. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 26 | The Behaviour was not found by its unique identifier. |
DELETE/behaviours/{behaviourId}/logs?includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number
Gets the list of BehaviourLogs for the specified Behaviour.
URL Parameters
Parameter | Type | Required | Description |
---|---|---|---|
behaviourId | uint64 | required | Unique identifier of the Behaviour. |
highest | uint64? | optional | The largest valued id objects to retrieve. |
includeArchive | boolean | optional | When true, the command will also return archived objects. |
includeDeleted | boolean | optional | When true, the command will also return deleted objects. |
limit | uint16? | optional | Maximum number of objects in this response. |
lowest | uint64? | optional | The smallest valued id objects to retrieve. |
Response description
Property | Type | Description |
---|---|---|
behaviour | RespIdScript | An object to contain the "id" of the Behaviour to which the array of BehaviourLogs belong. |
behaviour | uint64 | Identifier of the Company to which this object belongs. |
behaviour | uint64? | Identifier given as input for the command. |
behaviour | uint64 | Identifier of the script to which this object belongs. |
count | int32 | The total number of behaviour logs cleared. |
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "behaviour": { "company": number, "id": number, "script": number }, "count": number, "errorCode": number, "errorDetails": { "kind": string }, "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
500 | 2 | A communication error occurred. If you receive this error, please contact technical support. |
400 | 3 | The request does not contain a behaviour object, or it is invalid. |
400 | 3 | The behaviour object does not contain an id, or it is invalid. |
401 | 5 | You do not have permission to view BehaviourLogs for this Behaviour. |
401 | 5 | You do not have permission to clear Behaviours for this Company. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 26 | The Behaviour was not found by its unique identifier. |
PATCH/behaviours/{behaviourId}/restore
Restores a deleted Behaviour.
URL Parameters
Parameter | Type | Required | Description |
---|---|---|---|
behaviourId | uint64 | required | Unique identifier of the Behaviour. |
Response description
Property | Type | Description |
---|---|---|
behaviour | RespDeleted | An object which contains the Behaviour's id, owning Company id, and deleted status. |
behaviour | uint64 | Identifier of the Company to which this object belongs. |
behaviour | boolean | Flag showing if the object is deleted. |
behaviour | uint64? | Identifier given as input for the command. |
behaviour | Array.<uint32> | |
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "behaviour": { "company": number, "deleted": boolean, "id": number, "v": [ number ] }, "errorCode": number, "errorDetails": { "kind": string }, "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
500 | 2 | A communication error occurred. If you receive this error, please contact technical support. |
400 | 3 | The request does not contain a behaviour object, or it is invalid. |
400 | 3 | The behaviour object does not contain an id, or it is invalid. |
401 | 5 | You do not have permission to restore this Behaviour. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 26 | The Behaviour was not found by its unique identifier. |
400 | 27 | The Behaviour was found, but is not marked as deleted. |
GET/behaviours/logs ?asset={uint64}&includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number
Gets the list of BehaviourLogs for the specified Asset.
URL Parameters
Parameter | Type | Required | Description |
---|---|---|---|
asset | uint64 | required | Unique identifier of the Asset. |
highest | uint64? | optional | The largest valued id objects to retrieve. |
includeArchive | boolean | optional | When true, the command will also return archived objects. |
includeDeleted | boolean | optional | When true, the command will also return deleted objects. |
limit | uint16? | optional | Maximum number of objects in this response. |
lowest | uint64? | optional | The smallest valued id objects to retrieve. |
Response description
Property | Type | Description |
---|---|---|
asset | RespIdCompany | An object to contain the "id" of the Asset to which the array of BehaviourLogs relates. |
asset | uint64 | Identifier of the Company to which this object belongs. |
asset | uint64? | Identifier given as input for the command. |
behaviourLogs | Array.<BehaviourLog> | The list of requested BehaviourLogs. |
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "asset": { "company": number, "id": number }, "behaviourLogs": [ { "asset": number, "behaviour": number, "character": number, "company": number, "dts": string, "id": number, "kind": string, "line": number, "message": string, "script": number, "v": [ number ] } ], "errorCode": number, "errorDetails": { "kind": string }, "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
500 | 2 | A communication error occurred. If you receive this error, please contact technical support. |
400 | 3 | The request does not contain a asset object, or it is invalid. |
400 | 3 | The asset object does not contain an id, or it is invalid. |
401 | 5 | You do not have permission to view this Asset. |
401 | 5 | You do not have permission to view BehaviourLogs for this Asset's Company. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 20 | The Asset was not found by its unique identifier. |
DELETE/behaviours/logs ?asset={uint64}&includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number
Gets the list of BehaviourLogs for the specified Asset.
URL Parameters
Parameter | Type | Required | Description |
---|---|---|---|
asset | uint64 | required | Unique identifier of the Asset. |
highest | uint64? | optional | The largest valued id objects to retrieve. |
includeArchive | boolean | optional | When true, the command will also return archived objects. |
includeDeleted | boolean | optional | When true, the command will also return deleted objects. |
limit | uint16? | optional | Maximum number of objects in this response. |
lowest | uint64? | optional | The smallest valued id objects to retrieve. |
Response description
Property | Type | Description |
---|---|---|
asset | RespIdCompany | An object to contain the "id" of the Asset to which the array of BehaviourLogs relates. |
asset | uint64 | Identifier of the Company to which this object belongs. |
asset | uint64? | Identifier given as input for the command. |
count | int32 | The total number of behaviour logs cleared. |
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "asset": { "company": number, "id": number }, "count": number, "errorCode": number, "errorDetails": { "kind": string }, "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
500 | 2 | A communication error occurred. If you receive this error, please contact technical support. |
400 | 3 | The request does not contain a asset object, or it is invalid. |
400 | 3 | The asset object does not contain an id, or it is invalid. |
401 | 5 | You do not have permission to view this Asset. |
401 | 5 | You do not have permission to clear Behaviours for this Asset. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 20 | The Asset was not found by its unique identifier. |
GET/behaviours/scripts?tree=boolean&includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number
This request is an alias of /companies/{your-company-id}/behaviours/scripts?tree=true.
URL Parameters
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
tree | boolean | optional | true | Defaults to true for this alias. |
your-company-id | uint64 | aliased | {your-company-id} | Your own Company's identifier. |
PATCH/behaviours/scripts
Creates a new or updates an existing BehaviourScript.
Response description
Property | Type | Description |
---|---|---|
behaviourScript | RespIdCompany | An object which contains the "id" and "company" keys when there is no error. |
behaviourScript | uint64 | Identifier of the Company to which this object belongs. |
behaviourScript | uint64? | Identifier given as input for the command. |
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "behaviourScript": { "company": number, "id": number }, "errorCode": number, "errorDetails": { "kind": string }, "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
500 | 2 | A communication error occurred. If you receive this error, please contact technical support. |
400 | 3 | The request does not contain a behaviourScript object, or it is invalid. |
400 | 3 | Not enough keys exist in the behaviourScript object. |
400 | 3 | During create: When creating a new BehaviourScript, a name was not given, or it is invalid. |
400 | 3 | During create: When creating a new BehaviourScript, a company was not given. |
400 | 3 | During create: When creating a new BehaviourScript, the source was not given, or it is blank. |
400 | 3 | During update: When updating a BehaviourScript, the id was invalid. |
400 | 3 | During update: When updating a BehaviourScript, the name was given as blank. |
400 | 3 | During update: When updating a BehaviourScript, the v was not an array, or contained too few numbers. |
400 | 3 | One of the behaviourScript.parameters default values' was not valid. Returns an ErrorDetailBadKeys as the errorDetails .. |
400 | 3 | One of the behaviourScript.parameters was invalid. Returns an ErrorDetailInput as the errorDetails .. |
400 | 3 | One of the behaviourScript.parameters keys was blank or white-space. Returns an ErrorDetailInput as the errorDetails .. |
401 | 5 | You do not have permission to create a new BehaviourScript. |
401 | 5 | You do not have permission to update this BehaviourScript. |
400 | 6 | During update: When updating a BehaviourScript, an incorrect v value was given as input. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 23 | During update: The BehaviourScript was not found by its unique identifier. |
409 | 25 | During update: When updating a BehaviourScript which is marked as global, but is being set as private, but is implemented by Behaviours from child companies.. Returns an ErrorDetailCount as the errorDetails .. |
409 | 130 | During update: When updating a BehaviourScript, the behaviourScript.company can not be changed. |
DELETE/behaviours/scripts
Deletes an existing BehaviourScript.
Response description
Property | Type | Description |
---|---|---|
behaviourScript | RespDeleted | An object which contains the BehaviourScript's id, owning Company id, and deleted status. |
behaviourScript | uint64 | Identifier of the Company to which this object belongs. |
behaviourScript | boolean | Flag showing if the object is deleted. |
behaviourScript | uint64? | Identifier given as input for the command. |
behaviourScript | Array.<uint32> | |
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "behaviourScript": { "company": number, "deleted": boolean, "id": number, "v": [ number ] }, "errorCode": number, "errorDetails": { "kind": string }, "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
500 | 2 | A communication error occurred. If you receive this error, please contact technical support. |
400 | 3 | The request does not contain a behaviourScript object, or it is invalid. |
400 | 3 | The behaviourScript object does not contain an id, or it is invalid. |
401 | 5 | You do not have permission to delete this BehaviourScript. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 23 | The BehaviourScript was not found by its unique identifier. |
409 | 25 | This BehaviourScript is still being used by one of more Behaviours. Returns an ErrorDetailCount as the errorDetails .. |
GET/behaviours/scripts/{scriptId}?includeDeleted=boolean
Gets details of the specified BehaviourScript.
URL Parameters
Parameter | Type | Required | Description |
---|---|---|---|
includeDeleted | boolean | optional | When true, the command will also return deleted objects. |
scriptId | uint64 | required | Unique identifier of the BehaviourScript. |
Response description
Property | Type | Description |
---|---|---|
behaviourScript | BehaviourScript | The requested BehaviourScript. |
behaviourScript | uint64 see: Company.id | The company to which this script belongs. |
behaviourScript | boolean | Flag set by the compiler if this code compiles |
behaviourScript | colour maximum-length: 22 | The background colour given to this script for easy visual identification. |
behaviourScript | expression | A list of targeting expressions. These expressions are defaults for derived Behaviours. |
behaviourScript | boolean | Indicates whether this script is available to child companies. |
behaviourScript | codified maximum-length: 22 | The codified graphic name given to this script for easy visual identification. |
behaviourScript | uint64 | Unique identifier of this script. |
behaviourScript | string maximum-length: 100 | The nickname given to this script. |
behaviourScript | string | Usage notes and instructions for users on how best to setup this script. |
behaviourScript | Object.<string, BehaviourParameter> | Listed parameters for the Behaviour function. |
behaviourScript | string maximum-length: 8060 | The source code. |
behaviourScript | colour maximum-length: 22 | The text/graphic colour given to this script for easy visual identification. |
behaviourScript | Array.<uint32> | Object version keys used to validate synchronization for all object properties. |
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "behaviourScript": { "company": number, "compiles": boolean, "fill": string, "filters": string, "global": boolean, "graphic": string, "id": number, "name": string, "notes": string, "parameters": { string: { "context": string, "notes": string, "type": string, "value": string } }, "source": string, "stroke": string, "v": [ number ] }, "errorCode": number, "errorDetails": { "kind": string }, "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
400 | 3 | The request does not contain a behaviourScript object, or it is invalid. |
400 | 3 | The behaviourScript object does not contain an id, or it is invalid. |
401 | 5 | You do not have permission to view this BehaviourScript. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 23 | The BehaviourScript was not found by its unique identifier. |
POST/behaviours/scripts/{scriptId}
Creates a new or updates an existing BehaviourScript.
URL Parameters
Parameter | Type | Required | Description |
---|---|---|---|
scriptId | uint64? | optional | Unique identifier of the BehaviourScript. This value is optional, and ignored by the command. |
HTTP Request body description
Property | Type | Required | Description |
---|---|---|---|
behaviourScript | Object.<string, ?> | always | A simple object to contain the BehaviourScript parameters. |
behaviourScript | uint64? | create | Identifier of the Company to which this BehaviourScript belongs. After creation, this value is read-only. |
behaviourScript | string | optional | Background and fill colour in the UI. |
behaviourScript | expression | optional | A search pattern used to select the providers. |
behaviourScript | boolean | optional | When set to true, this Company as well as all child companies will be able to implement this BehaviourScript for that companies assets. |
behaviourScript | string | optional | The name of the symbol shown in the UI. |
behaviourScript | uint64? | update | The unique identifier of the BehaviourScript you want to update. |
behaviourScript | string maximum-length: 100 | create | Name for the BehaviourScript. |
behaviourScript | string | optional | Notes for the BehaviourScript. |
behaviourScript | Object.<string, BehaviourParameter> | optional | The defined arguments for this BehaviourScript. Each key in the object is the name of an argument. |
behaviourScript | string | create | Source code of the BehaviourScript. |
behaviourScript | string | optional | Text and outline colour in the UI. |
behaviourScript | Array.<int32> | optional | |
reqId | int32? | optional | Identifier used by external system to correlate requests to responses. |
HTTP Request body structure
{ "behaviourScript": { "company": number, "fill": string, "filters": string, "global": boolean, "graphic": string, "id": number, "name": string, "notes": string, "parameters": { string: { "context": string, "notes": string, "type": string, "value": string } }, "source": string, "stroke": string, "v": [ number ] }, "reqId": number }
Response description
Property | Type | Description |
---|---|---|
behaviourScript | RespIdCompany | An object which contains the "id" and "company" keys when there is no error. |
behaviourScript | uint64 | Identifier of the Company to which this object belongs. |
behaviourScript | uint64? | Identifier given as input for the command. |
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "behaviourScript": { "company": number, "id": number }, "errorCode": number, "errorDetails": { "kind": string }, "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
500 | 2 | A communication error occurred. If you receive this error, please contact technical support. |
400 | 3 | The request does not contain a behaviourScript object, or it is invalid. |
400 | 3 | Not enough keys exist in the behaviourScript object. |
400 | 3 | During create: When creating a new BehaviourScript, a name was not given, or it is invalid. |
400 | 3 | During create: When creating a new BehaviourScript, a company was not given. |
400 | 3 | During create: When creating a new BehaviourScript, the source was not given, or it is blank. |
400 | 3 | During update: When updating a BehaviourScript, the id was invalid. |
400 | 3 | During update: When updating a BehaviourScript, the name was given as blank. |
400 | 3 | During update: When updating a BehaviourScript, the v was not an array, or contained too few numbers. |
400 | 3 | One of the behaviourScript.parameters default values' was not valid. Returns an ErrorDetailBadKeys as the errorDetails .. |
400 | 3 | One of the behaviourScript.parameters was invalid. Returns an ErrorDetailInput as the errorDetails .. |
400 | 3 | One of the behaviourScript.parameters keys was blank or white-space. Returns an ErrorDetailInput as the errorDetails .. |
401 | 5 | You do not have permission to create a new BehaviourScript. |
401 | 5 | You do not have permission to update this BehaviourScript. |
400 | 6 | During update: When updating a BehaviourScript, an incorrect v value was given as input. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 23 | During update: The BehaviourScript was not found by its unique identifier. |
409 | 25 | During update: When updating a BehaviourScript which is marked as global, but is being set as private, but is implemented by Behaviours from child companies.. Returns an ErrorDetailCount as the errorDetails .. |
409 | 130 | During update: When updating a BehaviourScript, the behaviourScript.company can not be changed. |
DELETE/behaviours/scripts/{scriptId}
Deletes an existing BehaviourScript.
URL Parameters
Parameter | Type | Required | Description |
---|---|---|---|
scriptId | uint64 | required | Unique identifier of the BehaviourScript. |
Response description
Property | Type | Description |
---|---|---|
behaviourScript | RespDeleted | An object which contains the BehaviourScript's id, owning Company id, and deleted status. |
behaviourScript | uint64 | Identifier of the Company to which this object belongs. |
behaviourScript | boolean | Flag showing if the object is deleted. |
behaviourScript | uint64? | Identifier given as input for the command. |
behaviourScript | Array.<uint32> | |
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "behaviourScript": { "company": number, "deleted": boolean, "id": number, "v": [ number ] }, "errorCode": number, "errorDetails": { "kind": string }, "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
500 | 2 | A communication error occurred. If you receive this error, please contact technical support. |
400 | 3 | The request does not contain a behaviourScript object, or it is invalid. |
400 | 3 | The behaviourScript object does not contain an id, or it is invalid. |
401 | 5 | You do not have permission to delete this BehaviourScript. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 23 | The BehaviourScript was not found by its unique identifier. |
409 | 25 | This BehaviourScript is still being used by one of more Behaviours. Returns an ErrorDetailCount as the errorDetails .. |
GET/behaviours/scripts/{scriptId}/logs?includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number
Gets the list of BehaviourLogs for the specified BehaviourScript.
URL Parameters
Parameter | Type | Required | Description |
---|---|---|---|
highest | uint64? | optional | The largest valued id objects to retrieve. |
includeArchive | boolean | optional | When true, the command will also return archived objects. |
includeDeleted | boolean | optional | When true, the command will also return deleted objects. |
limit | uint16? | optional | Maximum number of objects in this response. |
lowest | uint64? | optional | The smallest valued id objects to retrieve. |
scriptId | uint64 | required | Unique identifier of the BehaviourScript. |
Response description
Property | Type | Description |
---|---|---|
behaviourLogs | Array.<BehaviourLog> | The list of requested BehaviourLogs. |
behaviourScript | RespIdCompany | An object to contain the "id" of the BehaviourScript to which the array of BehaviourLogs belong. |
behaviourScript | uint64 | Identifier of the Company to which this object belongs. |
behaviourScript | uint64? | Identifier given as input for the command. |
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "behaviourLogs": [ { "asset": number, "behaviour": number, "character": number, "company": number, "dts": string, "id": number, "kind": string, "line": number, "message": string, "script": number, "v": [ number ] } ], "behaviourScript": { "company": number, "id": number }, "errorCode": number, "errorDetails": { "kind": string }, "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
500 | 2 | A communication error occurred. If you receive this error, please contact technical support. |
400 | 3 | The request does not contain a behaviourScript object, or it is invalid. |
400 | 3 | The behaviourScript object does not contain an id, or it is invalid. |
401 | 5 | You do not have permission to view BehaviourLogs for the BehaviourScript's Company. |
401 | 5 | You do not have permission to view BehaviourScripts for this Company. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 23 | The BehaviourScript was not found by its unique identifier. |
DELETE/behaviours/scripts/{scriptId}/logs?includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number
Gets the list of BehaviourLogs for the specified BehaviourScript.
URL Parameters
Parameter | Type | Required | Description |
---|---|---|---|
highest | uint64? | optional | The largest valued id objects to retrieve. |
includeArchive | boolean | optional | When true, the command will also return archived objects. |
includeDeleted | boolean | optional | When true, the command will also return deleted objects. |
limit | uint16? | optional | Maximum number of objects in this response. |
lowest | uint64? | optional | The smallest valued id objects to retrieve. |
scriptId | uint64 | required | Unique identifier of the BehaviourScript. |
Response description
Property | Type | Description |
---|---|---|
behaviourScript | RespIdCompany | An object to contain the "id" of the BehaviourScript to which the array of BehaviourLogs belong. |
behaviourScript | uint64 | Identifier of the Company to which this object belongs. |
behaviourScript | uint64? | Identifier given as input for the command. |
count | int32 | The total number of behaviour logs cleared. |
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "behaviourScript": { "company": number, "id": number }, "count": number, "errorCode": number, "errorDetails": { "kind": string }, "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
500 | 2 | A communication error occurred. If you receive this error, please contact technical support. |
400 | 3 | The request does not contain a behaviourScript object, or it is invalid. |
400 | 3 | The behaviourScript object does not contain an id, or it is invalid. |
401 | 5 | You do not have permission to view BehaviourLogs for the BehaviourScript's Company. |
401 | 5 | You do not have permission to clear behaviours for this BehaviourScript. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 23 | The BehaviourScript was not found by its unique identifier. |
PATCH/behaviours/scripts/{scriptId}/restore
Restores the specified BehaviourScript.
URL Parameters
Parameter | Type | Required | Description |
---|---|---|---|
scriptId | uint64 | required | Unique identifier of the BehaviourScript. |
Response description
Property | Type | Description |
---|---|---|
behaviourScript | RespDeleted | An object which contains the BehaviourScript's id, owning Company id, and deleted status. |
behaviourScript | uint64 | Identifier of the Company to which this object belongs. |
behaviourScript | boolean | Flag showing if the object is deleted. |
behaviourScript | uint64? | Identifier given as input for the command. |
behaviourScript | Array.<uint32> | |
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "behaviourScript": { "company": number, "deleted": boolean, "id": number, "v": [ number ] }, "errorCode": number, "errorDetails": { "kind": string }, "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
500 | 2 | A communication error occurred. If you receive this error, please contact technical support. |
400 | 3 | The request does not contain a behaviourScript object, or it is invalid. |
400 | 3 | The behaviourScript object does not contain an id, or it is invalid. |
401 | 5 | You do not have permission to restore this BehaviourScript. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 23 | The BehaviourScript was not found by its unique identifier. |
400 | 24 | The BehaviourScript was found, but is not marked as deleted. |
GET/behaviours ?script={uint64}&includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number
URL Parameters
Parameter | Type | Required | Description |
---|---|---|---|
highest | uint64? | optional | The largest valued id objects to retrieve. |
includeArchive | boolean | optional | When true, the command will also return archived objects. |
includeDeleted | boolean | optional | When true, the command will also return deleted objects. |
limit | uint16? | optional | Maximum number of objects in this response. |
lowest | uint64? | optional | The smallest valued id objects to retrieve. |
script | uint64 | required | Unique identifier of the BehaviourScript. |
Response description
Property | Type | Description |
---|---|---|
behaviours | Array.<Behaviour> | The list of reqested Behaviours. |
behaviourScript | RespIdCompany | An object to contain the "id" of the Company to which the array of Behaviours belong. |
behaviourScript | uint64 | Identifier of the Company to which this object belongs. |
behaviourScript | uint64? | Identifier given as input for the command. |
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "behaviours": [ { "company": number, "filters": string, "id": number, "name": string, "notes": string, "parameters": { string: { "context": string, "notes": string, "type": string, "value": string } }, "priority": number, "script": number, "targets": string, "v": [ number ] } ], "behaviourScript": { "company": number, "id": number }, "errorCode": number, "errorDetails": { "kind": string }, "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
500 | 2 | A communication error occurred. If you receive this error, please contact technical support. |
400 | 3 | The request does not contain a behaviourScript object, or it is invalid. |
400 | 3 | The behaviourScript object does not contain an id, or it is invalid. |
401 | 5 | You do not have permission to view Behaviours for this Company. |
401 | 5 | You do not have permission to view BehaviourScripts for this Company. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 23 | The BehaviourScript was not found by its unique identifier. |
GET/companies/{companyId}/behaviours?includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number
URL Parameters
Parameter | Type | Required | Description |
---|---|---|---|
companyId | uint64 | required | Unique identifier of the Company. |
highest | uint64? | optional | The largest valued id objects to retrieve. |
includeArchive | boolean | optional | When true, the command will also return archived objects. |
includeDeleted | boolean | optional | When true, the command will also return deleted objects. |
limit | uint16? | optional | Maximum number of objects in this response. |
lowest | uint64? | optional | The smallest valued id objects to retrieve. |
Response description
Property | Type | Description |
---|---|---|
behaviours | Array.<Behaviour> | The list of reqested Behaviours. |
company | RespId | An object to contain the "id" of the Company to which the array of Behaviours belong. |
company | uint64? | Identifier given as input for the command. |
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "behaviours": [ { "company": number, "filters": string, "id": number, "name": string, "notes": string, "parameters": { string: { "context": string, "notes": string, "type": string, "value": string } }, "priority": number, "script": number, "targets": string, "v": [ number ] } ], "company": { "id": number }, "errorCode": number, "errorDetails": { "kind": string }, "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
500 | 2 | A communication error occurred. If you receive this error, please contact technical support. |
400 | 3 | The request does not contain a company object, or it is invalid. |
400 | 3 | The company object does not contain an id, or it is invalid. |
401 | 5 | You do not have permission to view this Company. |
401 | 5 | You do not have permission to view Behaviours for this Company. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 28 | The Company was not found by its unique identifier. |
GET/companies/{companyId}/behaviours/scripts?tree=boolean&includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number
Gets the list of BehaviourScripts for the specified Company.
URL Parameters
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
companyId | uint64 | required | Unique identifier of the Company | |
highest | uint64? | optional | The largest valued id objects to retrieve. | |
includeArchive | boolean | optional | When true, the command will also return archived objects. | |
includeDeleted | boolean | optional | When true, the command will also return deleted objects. | |
limit | uint16? | optional | Maximum number of objects in this response. | |
lowest | uint64? | optional | The smallest valued id objects to retrieve. | |
tree | boolean | optional | true | When true (default) the getter to retrieve the given Company's list of BehaviourScripts as well as any publicly available BehaviourScripts for the Company's parent(s). |
Response description
Property | Type | Description |
---|---|---|
behaviourScripts | Array.<BehaviourScript> | The list of requested BehaviourScripts. |
company | RespId | An object to contain the "id" of the Company to which the array of BehaviourScripts belong. |
company | uint64? | Identifier given as input for the command. |
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "behaviourScripts": [ { "company": number, "compiles": boolean, "fill": string, "filters": string, "global": boolean, "graphic": string, "id": number, "name": string, "notes": string, "parameters": { string: { "context": string, "notes": string, "type": string, "value": string } }, "source": string, "stroke": string, "v": [ number ] } ], "company": { "id": number }, "errorCode": number, "errorDetails": { "kind": string }, "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
500 | 2 | A communication error occurred. If you receive this error, please contact technical support. |
400 | 3 | The request does not contain a company object, or it is invalid. |
400 | 3 | The company object does not contain an id, or it is invalid. |
401 | 5 | You do not have permission to view BehaviourScripts for this Company. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 28 | The Company was not found by its unique identifier. |
Billing
GET/billing/profiles?includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number
This request is an alias of /companies/{your-company-id}/billing/profiles.
URL Parameters
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
your-company-id | uint64 | aliased | {your-company-id} | Your own Company's identifier. |
PATCH/billing/profiles
Creates new or updates an existing BillingProfile.
Response description
Property | Type | Description |
---|---|---|
billingProfile | RespIdCompany | An object which contains the "id", "company", and "profile" keys. |
billingProfile | uint64 | Identifier of the Company to which this object belongs. |
billingProfile | uint64? | Identifier given as input for the command. |
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "billingProfile": { "company": number, "id": number }, "errorCode": number, "errorDetails": { "kind": string }, "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
500 | 2 | A communication error occurred. If you receive this error, please contact technical support. |
400 | 3 | The request does not contain a billingProfile object, or it is invalid. |
400 | 3 | Not enough keys exist in the billingProfile object. |
400 | 3 | The messages are invalid. |
400 | 3 | The cycle is invalid. |
400 | 3 | The currency is invalid. |
400 | 3 | The cycleStart date is invalid. |
400 | 3 | The cycleEnd date is invalid. |
400 | 3 | During create: When creating a new BillingProfile, start date is invalid. |
400 | 3 | During create: When creating a new BillingProfile, end date is invalid. |
400 | 3 | During create: When creating a new BillingProfile, kind is invalid. |
400 | 3 | During create: When creating a new BillingProfile, a name was not given, or it is invalid. |
400 | 3 | During create: When creating a new BillingProfile, company is invalid. |
400 | 3 | During create: When creating a new BillingProfile, target is invalid. |
400 | 3 | During create: When creating a new BillingProfile, billee is invalid. |
400 | 3 | During update: When updating a BillingProfile, the name was invalid. |
400 | 3 | During update: When updating a BillingProfile, the v was invalid. |
401 | 5 | During create: You do not have permission to create new BillingProfile. |
401 | 5 | During update: You do not have permission to update BillingProfile. |
400 | 6 | During update: When updating a BillingProfile, the v was not an array, or contained too few numbers. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 28 | The company was not found by its unique identifier. |
404 | 28 | The target was not found by its unique identifier. |
404 | 28 | The billee was not found by its unique identifier. |
404 | 111 | The BillingProfile was not found by its unique identifier. If you receive this error, please contact technical support. |
409 | 130 | During update: When updating a BillingProfile, the billingProfile.company can not be changed. |
DELETE/billing/profiles
Deletes an existing BillingProfile.
Response description
Property | Type | Description |
---|---|---|
billingProfile | RespDeleted | An object which contains the BillingProfile's unique identifier and deleted status. |
billingProfile | uint64 | Identifier of the Company to which this object belongs. |
billingProfile | boolean | Flag showing if the object is deleted. |
billingProfile | uint64? | Identifier given as input for the command. |
billingProfile | Array.<uint32> | |
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "billingProfile": { "company": number, "deleted": boolean, "id": number, "v": [ number ] }, "errorCode": number, "errorDetails": { "kind": string }, "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
500 | 2 | A communication error occurred, the BillingProfile was not deleted. If you receive this error, please contact technical support. |
400 | 3 | The request does not contain a billingProfile object, or it is invalid. |
400 | 3 | The requested billingProfile id was invalid. |
401 | 5 | You do not have permission to delete this Company's BillingProfiles. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 111 | The BillingProfile was not found by its unique identifier. |
GET/billing/profiles/{profileId}?includeDeleted=boolean
Gets details of the specified BillingProfile.
URL Parameters
Parameter | Type | Required | Description |
---|---|---|---|
includeDeleted | boolean | optional | When true, the command will also return deleted objects. |
profileId | uint64 | required | Unique identifier of the BillingProfile. |
Response description
Property | Type | Description |
---|---|---|
billingProfile | BillingProfile | The requested BillingProfile. |
billingProfile | uint64 see: Company.id | Unique identifier of the Company receiving the bill. Most of the time, this value is the same as the target. |
billingProfile | uint64 see: Company.id | Unique identifier of the Company that owns this profile and is sending the bill. |
billingProfile | BillingCurrency | kind of money |
billingProfile | BillingCycle | Repeating cycle used for generating bills |
billingProfile | datetime | When should the cycle end (customer cancelled) |
billingProfile | boolean | Pro-rated, or post-dated. |
billingProfile | datetime | When is the first day of the billing cycle |
billingProfile | boolean | Are the Google services available to be proxied by the service? |
billingProfile | uint64 | Unique identifier of this billing profile |
billingProfile | Array.<BillableSmsProfile> | SMS messaging tiers |
billingProfile | string maximum-length: 254 | The name for this profile |
billingProfile | string maximum-length: 1000 | Notes about the billing profile for the billee or target. |
billingProfile | uint64 see: Company.id | Unique identifier of the Company to which this rule pertains. |
billingProfile | Array.<uint32> | Object version keys used to validate synchronization for all object properties. |
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "billingProfile": { "billee": number, "company": number, "currency": string, "cycle": string, "cycleEnd": string, "cyclePostDated": boolean, "cycleStart": string, "googleServicesEnabled": boolean, "id": number, "messages": [ { "amount": number, "limit": number } ], "name": string, "notes": string, "target": number, "v": [ number ] }, "errorCode": number, "errorDetails": { "kind": string }, "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
400 | 3 | The request does not contain a billingProfile object, or it is invalid. |
400 | 3 | The requested billingProfile id was invalid. |
401 | 5 | You do not have permission to view this Company's BillingProfiles. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 111 | The BillingProfile was not found by its unique identifier. |
POST/billing/profiles/{profileId}
Creates new or updates an existing BillingProfile.
URL Parameters
Parameter | Type | Required | Description |
---|---|---|---|
profileId | uint64? | optional | Unique identifier of the BillingProfile. This value is optional, and ignored by the command. |
HTTP Request body description
Property | Type | Required | Description |
---|---|---|---|
billingProfile | Object.<string, ?> | always | A simple object to contain the BillingProfile parameters. |
billingProfile | uint64? | optional | Unique identifier of the Company receiving the bill. |
billingProfile | uint64? | optional | Unique identifier of the Company that owns this BillingProfile and is sending the bill. |
billingProfile | BillingCurrency? | optional | Kind of money. |
billingProfile | BillingCycle? | optional | Repeating cycle used for generating bills. |
billingProfile | datetime | optional | When should the cycle end (customer cancelled); null means it never ends. |
billingProfile | boolean | optional | Pro-rated, or post-dated. |
billingProfile | datetime | optional | When is the first day of the billing cycle. |
billingProfile | boolean | optional | Are the Google services available to be proxied by the service? |
billingProfile | uint64? | optional | Unique identifier of the BillingProfile you want to update. |
billingProfile | Array.<BillableSmsProfile> | optional | SMS messaging tiers. |
billingProfile | string | optional | Name for the BillingProfile |
billingProfile | string | optional | Notes about the BillingProfile for the billee or target. |
billingProfile | uint64? | optional | Unique identifier of the Company to which this rule pertains. |
billingProfile | Array.<int32> | optional | |
reqId | int32? | optional | Identifier used by external system to correlate requests to responses. |
HTTP Request body structure
{ "billingProfile": { "billee": number, "company": number, "currency": string, "cycle": string, "cycleEnd": string, "cyclePostDated": boolean, "cycleStart": string, "googleServicesEnabled": boolean, "id": number, "messages": [ { "amount": number, "limit": number } ], "name": string, "notes": string, "target": number, "v": [ number ] }, "reqId": number }
Response description
Property | Type | Description |
---|---|---|
billingProfile | RespIdCompany | An object which contains the "id", "company", and "profile" keys. |
billingProfile | uint64 | Identifier of the Company to which this object belongs. |
billingProfile | uint64? | Identifier given as input for the command. |
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "billingProfile": { "company": number, "id": number }, "errorCode": number, "errorDetails": { "kind": string }, "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
500 | 2 | A communication error occurred. If you receive this error, please contact technical support. |
400 | 3 | The request does not contain a billingProfile object, or it is invalid. |
400 | 3 | Not enough keys exist in the billingProfile object. |
400 | 3 | The messages are invalid. |
400 | 3 | The cycle is invalid. |
400 | 3 | The currency is invalid. |
400 | 3 | The cycleStart date is invalid. |
400 | 3 | The cycleEnd date is invalid. |
400 | 3 | During create: When creating a new BillingProfile, start date is invalid. |
400 | 3 | During create: When creating a new BillingProfile, end date is invalid. |
400 | 3 | During create: When creating a new BillingProfile, kind is invalid. |
400 | 3 | During create: When creating a new BillingProfile, a name was not given, or it is invalid. |
400 | 3 | During create: When creating a new BillingProfile, company is invalid. |
400 | 3 | During create: When creating a new BillingProfile, target is invalid. |
400 | 3 | During create: When creating a new BillingProfile, billee is invalid. |
400 | 3 | During update: When updating a BillingProfile, the name was invalid. |
400 | 3 | During update: When updating a BillingProfile, the v was invalid. |
401 | 5 | During create: You do not have permission to create new BillingProfile. |
401 | 5 | During update: You do not have permission to update BillingProfile. |
400 | 6 | During update: When updating a BillingProfile, the v was not an array, or contained too few numbers. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 28 | The company was not found by its unique identifier. |
404 | 28 | The target was not found by its unique identifier. |
404 | 28 | The billee was not found by its unique identifier. |
404 | 111 | The BillingProfile was not found by its unique identifier. If you receive this error, please contact technical support. |
409 | 130 | During update: When updating a BillingProfile, the billingProfile.company can not be changed. |
DELETE/billing/profiles/{profileId}
Deletes an existing BillingProfile.
URL Parameters
Parameter | Type | Required | Description |
---|---|---|---|
profileId | uint64 | required | Unique identifier of the BillingProfile. |
Response description
Property | Type | Description |
---|---|---|
billingProfile | RespDeleted | An object which contains the BillingProfile's unique identifier and deleted status. |
billingProfile | uint64 | Identifier of the Company to which this object belongs. |
billingProfile | boolean | Flag showing if the object is deleted. |
billingProfile | uint64? | Identifier given as input for the command. |
billingProfile | Array.<uint32> | |
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "billingProfile": { "company": number, "deleted": boolean, "id": number, "v": [ number ] }, "errorCode": number, "errorDetails": { "kind": string }, "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
500 | 2 | A communication error occurred, the BillingProfile was not deleted. If you receive this error, please contact technical support. |
400 | 3 | The request does not contain a billingProfile object, or it is invalid. |
400 | 3 | The requested billingProfile id was invalid. |
401 | 5 | You do not have permission to delete this Company's BillingProfiles. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 111 | The BillingProfile was not found by its unique identifier. |
GET/billing/profiles/{profileId}/licenses?includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number
Gets the list of BillableHostingLicenses for the specified BillingProfile.
URL Parameters
Parameter | Type | Required | Description |
---|---|---|---|
highest | uint64? | optional | The largest valued id objects to retrieve. |
includeArchive | boolean | optional | When true, the command will also return archived objects. |
includeDeleted | boolean | optional | When true, the command will also return deleted objects. |
limit | uint16? | optional | Maximum number of objects in this response. |
lowest | uint64? | optional | The smallest valued id objects to retrieve. |
profileId | uint64 | required | Unique identifier of the BillingProfile. |
Response description
Property | Type | Description |
---|---|---|
billingProfile | RespIdCompany | An object to contain the "id" of the BillingProfile to which the array of BillableHostingLicenses belong. |
billingProfile | uint64 | Identifier of the Company to which this object belongs. |
billingProfile | uint64? | Identifier given as input for the command. |
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
hostingLicenses | Array.<BillableHostingLicense> | The list of BillableHostingLicenses. |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "billingProfile": { "company": number, "id": number }, "errorCode": number, "errorDetails": { "kind": string }, "hostingLicenses": [ { "amount": number, "company": number, "end": string, "id": number, "kind": string, "limit": number, "name": string, "notes": string, "profile": number, "reference": string, "sku": string, "start": string, "suspended": boolean, "targets": string, "v": [ number ] } ], "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
500 | 2 | A communication error occurred. If you receive this error, please contact technical support. |
400 | 3 | The request does not contain a billingProfile object, or it is invalid. |
400 | 3 | The billingProfile object does not contain an id, or it is invalid. |
401 | 5 | You do not have permission to view this Company's BillableHostingLicenses. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 28 | The Company was not found by its unique identifier. If you receive this error, please contact technical support. |
404 | 111 | The BillingProfile was not found by its unique identifier. |
GET/billing/profiles/{profileId}/reports?includeDeleted=boolean&includeArchive=boolean&limit=number&after=string&before=string
Gets the list of BillingReports for the specified BillingProfile.
URL Parameters
Parameter | Type | Required | Description |
---|---|---|---|
after | datetime | optional | A timestamp for the earliest objects (by dts) to retrieve. |
before | datetime | optional | A timestamp for the latest objects (by dts) to retrieve. |
includeArchive | boolean | optional | When true, the command will also return archived objects. |
includeDeleted | boolean | optional | When true, the command will also return deleted objects. |
limit | uint16? | optional | Maximum number of objects in this response. |
profileId | uint64 | required | Unique identifier of the BillingProfile. |
Response description
Property | Type | Description |
---|---|---|
billingProfile | RespIdCompany | An object to contain the "id" of the BillingProfile to which the array of BillableHostingRules belong. |
billingProfile | uint64 | Identifier of the Company to which this object belongs. |
billingProfile | uint64? | Identifier given as input for the command. |
billingReports | Array.<BillingReport> | The list of requested BillingReports. |
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "billingProfile": { "company": number, "id": number }, "billingReports": [ { "billee": number, "breakdown": [ { "licenses": [ { "billableDays": number, "cost": number, "created": string, "deleted": string, "firmware": string, "kind": string, "name": string, "notes": string, "phoneNumber": number, "provider": string, "total": number } ], "services": [ { "asset": number, "billableDays": number, "cost": number, "created": string, "deleted": string, "kind": string, "labels": [ string ], "name": string, "notes": string, "phoneNumbers": [ number ], "providers": [ string ], "restored": string, "revived": string, "suspended": string, "suspendedCost": number, "suspendedDays": number, "total": number, "updatedDts": string } ], "target": number } ], "company": number, "currency": string, "endDate": string, "error": string, "id": number, "name": string, "notes": string, "profile": number, "startDate": string, "status": string, "summary": [ { "hosting": [ { "cost": number, "count": number, "sku": string, "total": number } ], "name": string, "notes": string, "parent": number, "target": number } ], "total": number, "v": [ number ] } ], "errorCode": number, "errorDetails": { "kind": string }, "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
500 | 2 | A communication error occurred. If you receive this error, please contact technical support. |
400 | 3 | The request does not contain a billingProfile object, or it is invalid. |
400 | 3 | The billingProfile object does not contain an id, or it is invalid. |
401 | 5 | You do not have permission to view this Company's BillingReports. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 28 | The Company was not found by its unique identifier. |
404 | 111 | The BillingProfile was not found by its unique identifier. |
PATCH/billing/profiles/{profileId}/restore
Restores the specified BillingProfile to its previous version.
URL Parameters
Parameter | Type | Required | Description |
---|---|---|---|
profileId | uint64 | required | Unique identifier of the BillingProfile. |
Response description
Property | Type | Description |
---|---|---|
billingProfile | RespDeleted | An object which contains the BillingProfile's unique identifier and deleted status. |
billingProfile | uint64 | Identifier of the Company to which this object belongs. |
billingProfile | boolean | Flag showing if the object is deleted. |
billingProfile | uint64? | Identifier given as input for the command. |
billingProfile | Array.<uint32> | |
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "billingProfile": { "company": number, "deleted": boolean, "id": number, "v": [ number ] }, "errorCode": number, "errorDetails": { "kind": string }, "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
500 | 2 | A communication error occurred. If you receive this error, please contact technical support. |
400 | 3 | The request does not contain a billingProfile object, or it is invalid. |
400 | 3 | The requested billingProfile id was invalid. |
401 | 5 | You do not have permission to restore BillingProfiles. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 111 | The BillingProfile was not found by its unique identifier. |
400 | 112 | The BillingProfile was found, but is not marked as deleted. |
GET/billing/profiles/{profileId}/rules?includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number
Gets the list of BillableHostingRule for the specified BillingProfile.
URL Parameters
Parameter | Type | Required | Description |
---|---|---|---|
highest | uint64? | optional | The largest valued id objects to retrieve. |
includeArchive | boolean | optional | When true, the command will also return archived objects. |
includeDeleted | boolean | optional | When true, the command will also return deleted objects. |
limit | uint16? | optional | Maximum number of objects in this response. |
lowest | uint64? | optional | The smallest valued id objects to retrieve. |
profileId | uint64 | required | Unique identifier of the BillingProfile. |
Response description
Property | Type | Description |
---|---|---|
billingProfile | RespIdCompany | An object to contain the "id" of the BillingProfile to which the array of BillableHostingRules belong. |
billingProfile | uint64 | Identifier of the Company to which this object belongs. |
billingProfile | uint64? | Identifier given as input for the command. |
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
hostingRules | Array.<BillableHostingRule> | The list of requested BillableHostingRules. |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "billingProfile": { "company": number, "id": number }, "errorCode": number, "errorDetails": { "kind": string }, "hostingRules": [ { "amount": number, "company": number, "end": string, "id": number, "limit": number, "name": string, "notes": string, "profile": number, "reference": string, "service": string, "sku": string, "start": string, "suspended": boolean, "targets": string, "v": [ number ] } ], "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
500 | 2 | A communication error occurred. If you receive this error, please contact technical support. |
400 | 3 | The request does not contain a billingProfile object, or it is invalid. |
400 | 3 | The billingProfile object does not contain an id, or it is invalid. |
401 | 5 | You do not have permission to view this Company's BillableHostingRules. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 28 | The Company was not found by its unique identifier. If you receive this error, please contact technical support. |
404 | 111 | The BillingProfile was not found by its unique identifier. |
PATCH/billing/profiles/licenses
Creates new or updates an existing BillableHostingLicense.
Response description
Property | Type | Description |
---|---|---|
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
hostingLicense | RespIdBillingProfile | An object which contains the "id", "company", and "profile" keys. |
hostingLicense | uint64 | Identifier of the Company to which this object belongs. |
hostingLicense | uint64? | Identifier given as input for the command. |
hostingLicense | uint64 | Identifier of the BillingProfile to which this object belongs |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "errorCode": number, "errorDetails": { "kind": string }, "hostingLicense": { "company": number, "id": number, "profile": number }, "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
500 | 2 | A communication error occurred. If you receive this error, please contact technical support. |
400 | 3 | The request does not contain a hostingLicense object, or it is invalid. |
400 | 3 | Not enough keys exist in the hostingLicense object. |
400 | 3 | During create: When creating a new BillableHostingLicense, start date is invalid. |
400 | 3 | During create: When creating a new BillableHostingLicense, end date is invalid. |
400 | 3 | During create: When creating a new BillableHostingLicense, kind is invalid. |
400 | 3 | During create: When creating a new BillableHostingLicense, a name was not given, or it is invalid. |
400 | 3 | During create: When creating a new BillableHostingLicense, profile is invalid. |
400 | 3 | During update: When updating a BillableHostingLicense, the name was invalid. |
400 | 3 | During update: When updating a BillableHostingLicense, the v was invalid. |
401 | 5 | During create: You do not have permission to create new BillableHostingLicenses. |
401 | 5 | During update: You do not have permission to update BillableHostingLicenses. |
400 | 6 | During update: When updating a BillableHostingLicense, the v was not an array, or contained too few numbers. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 111 | The BillingProfile was not found by its unique identifier. If you receive this error, please contact technical support. |
404 | 117 | During update: The BillableHostingLicense was not found by its unique identifier. |
409 | 130 | During update: When updating a BillableHostingLicense, the hostingLicense.profile can not be changed. |
DELETE/billing/profiles/licenses
Deletes an existing BillableHostingLicense.
Response description
Property | Type | Description |
---|---|---|
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
hostingLicense | RespDeleted | An object which contains the BillableHostingLicense's unique identifier and deleted status. |
hostingLicense | uint64 | Identifier of the Company to which this object belongs. |
hostingLicense | boolean | Flag showing if the object is deleted. |
hostingLicense | uint64? | Identifier given as input for the command. |
hostingLicense | Array.<uint32> | |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "errorCode": number, "errorDetails": { "kind": string }, "hostingLicense": { "company": number, "deleted": boolean, "id": number, "v": [ number ] }, "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
500 | 2 | A communication error occurred, the BillableHostingLicense was not deleted. If you receive this error, please contact technical support. |
400 | 3 | The request does not contain a hostingLicense object, or it is invalid. |
400 | 3 | The requested hostingLicense id was invalid. |
401 | 5 | You do not have permission to delete this Company's BillableHostingLicenses. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 117 | The BillableHostingLicense was not found by its unique identifier. |
GET/billing/profiles/licenses/{licenseId}?includeDeleted=boolean
Gets details of the specified BillableHostingLicense.
URL Parameters
Parameter | Type | Required | Description |
---|---|---|---|
includeDeleted | boolean | optional | When true, the command will also return deleted objects. |
licenseId | uint64 | required | Unique identifier of the BillableHostingLicense. |
Response description
Property | Type | Description |
---|---|---|
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
hostingLicense | BillableHostingLicense | The requested BillableHostingLicense. |
hostingLicense | double | Cost per cycle for this plan |
hostingLicense | uint64 see: Company.id | Unique identifier of the Company that owns this hosting rule. |
hostingLicense | datetime | Date this billing rule is applied until; null means it never ends. These dates are used to determine how much of the cycle is billed. |
hostingLicense | uint64 | Unique identifier of this hosting rule. |
hostingLicense | BillableLicenseType | The type of hardware license |
hostingLicense | uint32? | The number of units to which this billing rule applies. Should be a non-zero value; null means unlimited |
hostingLicense | string maximum-length: 254 | The name of this billing rule. |
hostingLicense | string | Notes about billing this rule. |
hostingLicense | uint64 see: BillingProfile.id | Unique identifier of this rule's billing profile. |
hostingLicense | string maximum-length: 100 | A custom field used to refer to an external system. Examples are a cost codes, SOCs, discount plans... |
hostingLicense | string maximum-length: 20 | SKU or SOC code |
hostingLicense | datetime | Date this billing rule takes effect. These dates are used to determine how much of the cycle is billed. |
hostingLicense | boolean | Does this hosting rule apply to suspended resources |
hostingLicense | expression | Which assets are targeted by this hosting rule |
hostingLicense | Array.<uint32> | Object version keys used to validate synchronization for all object properties. |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "errorCode": number, "errorDetails": { "kind": string }, "hostingLicense": { "amount": number, "company": number, "end": string, "id": number, "kind": string, "limit": number, "name": string, "notes": string, "profile": number, "reference": string, "sku": string, "start": string, "suspended": boolean, "targets": string, "v": [ number ] }, "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
400 | 3 | The request does not contain a hostingLicense object, or it is invalid. |
400 | 3 | The requested hostingLicense id was invalid. |
401 | 5 | You do not have permission to view this Company's BillableHostingLicenses. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 117 | The BillableHostingLicense was not found by its unique identifier. |
POST/billing/profiles/licenses/{licenseId}
Creates new or updates an existing BillableHostingLicense.
URL Parameters
Parameter | Type | Required | Description |
---|---|---|---|
licenseId | uint64? | optional | Unique identifier of the BillableHostingLicense. This value is optional, and ignored by the command. |
HTTP Request body description
Property | Type | Required | Description |
---|---|---|---|
hostingLicense | Object.<string, ?> | always | A simple object to contain the BillableHostingLicense parameters. |
hostingLicense | double? | optional | Cost per cycle for this plan |
hostingLicense | datetime | optional | Date this BillableHostingLicense is applied until; null means it never ends. |
hostingLicense | uint64? | update | Unique identifier of the BillableHostingLicense you want to update. |
hostingLicense | BillableLicenseType? | create | The type of hardware BillableLicenseType. |
hostingLicense | uint32? | optional | The number of units to which this BillableHostingLicense applies. Should be a non-zero value; null means unlimited |
hostingLicense | string | create | Name for the BillableHostingLicense |
hostingLicense | string | optional | Notes about the BillableHostingLicense. |
hostingLicense | uint64? | create | Unique identifier of this BillableHostingLicense's BillingProfile. |
hostingLicense | string | optional | A custom field used to refer to an external system. Examples are a cost codes, SOCs, discount plans... |
hostingLicense | datetime | optional | Date this BillableHostingLicense takes effect. |
hostingLicense | boolean | optional | Does this BillableHostingLicense apply to suspended resources |
hostingLicense | expression | optional | Which assets are targetted by this BillableHostingLicense |
hostingLicense | Array.<int32> | optional | |
reqId | int32? | optional | Identifier used by external system to correlate requests to responses. |
HTTP Request body structure
{ "hostingLicense": { "amount": number, "end": string, "id": number, "kind": string, "limit": number, "name": string, "notes": string, "profile": number, "reference": string, "start": string, "suspended": boolean, "targets": string, "v": [ number ] }, "reqId": number }
Response description
Property | Type | Description |
---|---|---|
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
hostingLicense | RespIdBillingProfile | An object which contains the "id", "company", and "profile" keys. |
hostingLicense | uint64 | Identifier of the Company to which this object belongs. |
hostingLicense | uint64? | Identifier given as input for the command. |
hostingLicense | uint64 | Identifier of the BillingProfile to which this object belongs |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "errorCode": number, "errorDetails": { "kind": string }, "hostingLicense": { "company": number, "id": number, "profile": number }, "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
500 | 2 | A communication error occurred. If you receive this error, please contact technical support. |
400 | 3 | The request does not contain a hostingLicense object, or it is invalid. |
400 | 3 | Not enough keys exist in the hostingLicense object. |
400 | 3 | During create: When creating a new BillableHostingLicense, start date is invalid. |
400 | 3 | During create: When creating a new BillableHostingLicense, end date is invalid. |
400 | 3 | During create: When creating a new BillableHostingLicense, kind is invalid. |
400 | 3 | During create: When creating a new BillableHostingLicense, a name was not given, or it is invalid. |
400 | 3 | During create: When creating a new BillableHostingLicense, profile is invalid. |
400 | 3 | During update: When updating a BillableHostingLicense, the name was invalid. |
400 | 3 | During update: When updating a BillableHostingLicense, the v was invalid. |
401 | 5 | During create: You do not have permission to create new BillableHostingLicenses. |
401 | 5 | During update: You do not have permission to update BillableHostingLicenses. |
400 | 6 | During update: When updating a BillableHostingLicense, the v was not an array, or contained too few numbers. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 111 | The BillingProfile was not found by its unique identifier. If you receive this error, please contact technical support. |
404 | 117 | During update: The BillableHostingLicense was not found by its unique identifier. |
409 | 130 | During update: When updating a BillableHostingLicense, the hostingLicense.profile can not be changed. |
DELETE/billing/profiles/licenses/{licenseId}
Deletes an existing BillableHostingLicense.
URL Parameters
Parameter | Type | Required | Description |
---|---|---|---|
licenseId | uint64 | required | Unique identifier of the BillableHostingLicense. |
Response description
Property | Type | Description |
---|---|---|
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
hostingLicense | RespDeleted | An object which contains the BillableHostingLicense's unique identifier and deleted status. |
hostingLicense | uint64 | Identifier of the Company to which this object belongs. |
hostingLicense | boolean | Flag showing if the object is deleted. |
hostingLicense | uint64? | Identifier given as input for the command. |
hostingLicense | Array.<uint32> | |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "errorCode": number, "errorDetails": { "kind": string }, "hostingLicense": { "company": number, "deleted": boolean, "id": number, "v": [ number ] }, "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
500 | 2 | A communication error occurred, the BillableHostingLicense was not deleted. If you receive this error, please contact technical support. |
400 | 3 | The request does not contain a hostingLicense object, or it is invalid. |
400 | 3 | The requested hostingLicense id was invalid. |
401 | 5 | You do not have permission to delete this Company's BillableHostingLicenses. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 117 | The BillableHostingLicense was not found by its unique identifier. |
PATCH/billing/profiles/licenses/{licenseId}/restore
Restores the specified BillableHostingLicense to its previous version.
URL Parameters
Parameter | Type | Required | Description |
---|---|---|---|
licenseId | uint64 | required | Unique identifier of the BillableHostingLicense. |
Response description
Property | Type | Description |
---|---|---|
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
hostingLicense | RespDeleted | An object which contains the BillableHostingLicense's unique identifier and deleted status. |
hostingLicense | uint64 | Identifier of the Company to which this object belongs. |
hostingLicense | boolean | Flag showing if the object is deleted. |
hostingLicense | uint64? | Identifier given as input for the command. |
hostingLicense | Array.<uint32> | |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "errorCode": number, "errorDetails": { "kind": string }, "hostingLicense": { "company": number, "deleted": boolean, "id": number, "v": [ number ] }, "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
500 | 2 | A communication error occurred. If you receive this error, please contact technical support. |
400 | 3 | The request does not contain a hostingLicense object, or it is invalid. |
400 | 3 | The requested hostingLicense id was invalid. |
401 | 5 | You do not have permission to delete BillableHostingLicenses. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 117 | The BillableHostingLicense was not found by its unique identifier. |
400 | 118 | The BillableHostingLicense was found, but is not marked as deleted. |
GET/billing/profiles/reports?includeDeleted=boolean&includeArchive=boolean&limit=number&after=string&before=string
This request is an alias of /companies/{your-company-id}/billing/profiles/reports.
URL Parameters
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
your-company-id | uint64 | aliased | {your-company-id} | Your own Company's identifier. |
DELETE/billing/profiles/reports
Deletes an existing BillingReport.
Response description
Property | Type | Description |
---|---|---|
billingReport | RespDeleted | An object which contains the BillingReport's unique identifier and deleted status. |
billingReport | uint64 | Identifier of the Company to which this object belongs. |
billingReport | boolean | Flag showing if the object is deleted. |
billingReport | uint64? | Identifier given as input for the command. |
billingReport | Array.<uint32> | |
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "billingReport": { "company": number, "deleted": boolean, "id": number, "v": [ number ] }, "errorCode": number, "errorDetails": { "kind": string }, "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
500 | 2 | A communication error occurred, the BillingReport was not deleted. If you receive this error, please contact technical support. |
400 | 3 | The request does not contain a billingReport object, or it is invalid. |
400 | 3 | The requested billingReport id was invalid. |
401 | 5 | You do not have permission to delete this Company's BillingReports. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 119 | The BillingReport was not found by its unique identifier. |
GET/billing/profiles/reports/{reportId}?includeDeleted=boolean
Gets details of the specified BillingReport.
URL Parameters
Parameter | Type | Required | Description |
---|---|---|---|
includeDeleted | boolean | optional | When true, the command will also return deleted objects. |
reportId | uint64 | required | Unique identifier of the BillingReport. |
Response description
Property | Type | Description |
---|---|---|
billingReport | BillingReport | The requested BillingReport. |
billingReport | uint64 see: Company.id | Unique identifier of the Company receiving the bill. |
billingReport | Array.<BillingReportBreakdown> | Individual amounts per company, used to calculate the results of the report. |
billingReport | uint64 see: Company.id | The company to which this report belongs and is sending the bill. |
billingReport | BillingCurrency | Currency being billed in |
billingReport | datetime | Last day of the billing cycle |
billingReport | string see: BillingReportStatus maximum-length: 250 | A field which contains report error details if the BillingReport.status is BillingReportStatus.failed. |
billingReport | uint64 | Unique identifier |
billingReport | string maximum-length: 100 | Name of this report. |
billingReport | string | Notes about this report. |
billingReport | uint64 see: BillingProfile.id | The profile to which this report belongs |
billingReport | datetime | First day of the billing cycle |
billingReport | BillingReportStatus | The processing status of this report. |
billingReport | Array.<BillingReportSummary> | Summary contains totals per target for this billee |
billingReport | double | Total amount being billed. |
billingReport | Array.<uint32> | Object version keys used to validate synchronization for all object properties. |
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "billingReport": { "billee": number, "breakdown": [ { "licenses": [ { "billableDays": number, "cost": number, "created": string, "deleted": string, "firmware": string, "kind": string, "name": string, "notes": string, "phoneNumber": number, "provider": string, "total": number } ], "services": [ { "asset": number, "billableDays": number, "cost": number, "created": string, "deleted": string, "kind": string, "labels": [ string ], "name": string, "notes": string, "phoneNumbers": [ number ], "providers": [ string ], "restored": string, "revived": string, "suspended": string, "suspendedCost": number, "suspendedDays": number, "total": number, "updatedDts": string } ], "target": number } ], "company": number, "currency": string, "endDate": string, "error": string, "id": number, "name": string, "notes": string, "profile": number, "startDate": string, "status": string, "summary": [ { "hosting": [ { "cost": number, "count": number, "sku": string, "total": number } ], "name": string, "notes": string, "parent": number, "target": number } ], "total": number, "v": [ number ] }, "errorCode": number, "errorDetails": { "kind": string }, "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
400 | 3 | The request does not contain a billingReport object, or it is invalid. |
400 | 3 | The requested billingReport id was invalid. |
401 | 5 | You do not have permission to view this Company's BillingReports. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 119 | The BillingReport was not found by its unique identifier. |
DELETE/billing/profiles/reports/{reportId}
Deletes an existing BillingReport.
URL Parameters
Parameter | Type | Required | Description |
---|---|---|---|
reportId | uint64 | required | Unique identifier of the BillingReport. |
Response description
Property | Type | Description |
---|---|---|
billingReport | RespDeleted | An object which contains the BillingReport's unique identifier and deleted status. |
billingReport | uint64 | Identifier of the Company to which this object belongs. |
billingReport | boolean | Flag showing if the object is deleted. |
billingReport | uint64? | Identifier given as input for the command. |
billingReport | Array.<uint32> | |
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "billingReport": { "company": number, "deleted": boolean, "id": number, "v": [ number ] }, "errorCode": number, "errorDetails": { "kind": string }, "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
500 | 2 | A communication error occurred, the BillingReport was not deleted. If you receive this error, please contact technical support. |
400 | 3 | The request does not contain a billingReport object, or it is invalid. |
400 | 3 | The requested billingReport id was invalid. |
401 | 5 | You do not have permission to delete this Company's BillingReports. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 119 | The BillingReport was not found by its unique identifier. |
PATCH/billing/profiles/reports/{reportId}/restore
Restores the specified BillingReport to its previous version.
URL Parameters
Parameter | Type | Required | Description |
---|---|---|---|
reportId | uint64 | required | Unique identifier of the BillingReport. |
Response description
Property | Type | Description |
---|---|---|
billingReport | RespDeleted | An object which contains the BillingReport's unique identifier and deleted status. |
billingReport | uint64 | Identifier of the Company to which this object belongs. |
billingReport | boolean | Flag showing if the object is deleted. |
billingReport | uint64? | Identifier given as input for the command. |
billingReport | Array.<uint32> | |
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "billingReport": { "company": number, "deleted": boolean, "id": number, "v": [ number ] }, "errorCode": number, "errorDetails": { "kind": string }, "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
500 | 2 | A communication error occurred. If you receive this error, please contact technical support. |
400 | 3 | The request does not contain a billingReport object, or it is invalid. |
400 | 3 | The requested billingReport id was invalid. |
401 | 5 | You do not have permission to restore BillingReports. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 119 | The BillingReport was not found by its unique identifier. |
400 | 120 | The BillingReport was found, but is not marked as deleted. |
PATCH/billing/profiles/rules
Creates new or updates an existing BillableHostingRule.
Response description
Property | Type | Description |
---|---|---|
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
hostingRule | RespIdBillingProfile | An object which contains the "id", "company", and "profile" keys. |
hostingRule | uint64 | Identifier of the Company to which this object belongs. |
hostingRule | uint64? | Identifier given as input for the command. |
hostingRule | uint64 | Identifier of the BillingProfile to which this object belongs |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "errorCode": number, "errorDetails": { "kind": string }, "hostingRule": { "company": number, "id": number, "profile": number }, "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
500 | 2 | A communication error occurred. If you receive this error, please contact technical support. |
400 | 3 | The request does not contain a hostingRule object, or it is invalid. |
400 | 3 | Not enough keys exist in the hostingRule object. |
400 | 3 | During create: When creating a new BillableHostingRule, start date is invalid. |
400 | 3 | During create: When creating a new BillableHostingRule, end date is invalid. |
400 | 3 | During create: When creating a new BillableHostingRule, a name was not given, or it is invalid. |
400 | 3 | During create: When creating a new BillableHostingRule, profile is invalid. |
400 | 3 | During create: When creating a new BillableHostingRule, service is invalid. |
400 | 3 | During update: When updating a BillableHostingRule, the name was invalid. |
400 | 3 | During update: When updating a BillableHostingRule, the v was invalid. |
401 | 5 | During create: You do not have permission to create new BillableHostingRules. |
401 | 5 | During update: You do not have permission to update BillableHostingRules. |
400 | 6 | During update: When updating a BillableHostingRule, the v was not an array, or contained too few numbers. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 111 | The BillingProfile was not found by its unique identifier. If you receive this error, please contact technical support. |
404 | 113 | During update: The BillableHostingRule was not found by its unique identifier. |
409 | 130 | During update: When updating a BillableHostingRule, the hostingRule.profile can not be changed. |
DELETE/billing/profiles/rules
Deletes an existing BillableHostingRule.
Response description
Property | Type | Description |
---|---|---|
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
hostingRule | RespDeleted | An object which contains the BillableHostingRule's unique identifier and deleted status. |
hostingRule | uint64 | Identifier of the Company to which this object belongs. |
hostingRule | boolean | Flag showing if the object is deleted. |
hostingRule | uint64? | Identifier given as input for the command. |
hostingRule | Array.<uint32> | |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "errorCode": number, "errorDetails": { "kind": string }, "hostingRule": { "company": number, "deleted": boolean, "id": number, "v": [ number ] }, "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
500 | 2 | A communication error occurred, the BillableHostingRule was not deleted. If you receive this error, please contact technical support. |
400 | 3 | The request does not contain a hostingRule object, or it is invalid. |
400 | 3 | The requested hostingRule id was invalid. |
401 | 5 | You do not have permission to delete this Company's BillableHostingRules. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 113 | The BillableHostingRule was not found by its unique identifier. |
GET/billing/profiles/rules/{ruleId}?includeDeleted=boolean
Gets details of the specified BillableHostingRule.
URL Parameters
Parameter | Type | Required | Description |
---|---|---|---|
includeDeleted | boolean | optional | When true, the command will also return deleted objects. |
ruleId | uint64 | required | Unique identifier of the BillableHostingRule. |
Response description
Property | Type | Description |
---|---|---|
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
hostingRule | BillableHostingRule | The requested BillableHostingRule. |
hostingRule | double | Cost per cycle for this plan |
hostingRule | uint64 see: Company.id | Unique identifier of the Company that owns this hosting rule. |
hostingRule | datetime | Date this billing rule is applied until; null means it never ends. These dates are used to determine how much of the cycle is billed. |
hostingRule | uint64 | Unique identifier of this hosting rule. |
hostingRule | uint32? | The number of units to which this billing rule applies. Should be a non-zero value; null means unlimited |
hostingRule | string maximum-length: 254 | The name of this billing rule. |
hostingRule | string | Notes about billing this rule. |
hostingRule | uint64 see: BillingProfile.id | Unique identifier of this rule's billing profile. |
hostingRule | string maximum-length: 100 | A custom field used to refer to an external system. Examples are a cost codes, SOCs, discount plans... |
hostingRule | BillableHostingType | The type of service being billed. |
hostingRule | string maximum-length: 20 | SKU or SOC code |
hostingRule | datetime | Date this billing rule takes effect. These dates are used to determine how much of the cycle is billed. |
hostingRule | boolean | Does this hosting rule apply to suspended resources |
hostingRule | expression | Which assets are targeted by this hosting rule |
hostingRule | Array.<uint32> | Object version keys used to validate synchronization for all object properties. |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "errorCode": number, "errorDetails": { "kind": string }, "hostingRule": { "amount": number, "company": number, "end": string, "id": number, "limit": number, "name": string, "notes": string, "profile": number, "reference": string, "service": string, "sku": string, "start": string, "suspended": boolean, "targets": string, "v": [ number ] }, "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
400 | 3 | The request does not contain a hostingRule object, or it is invalid. |
400 | 3 | The requested hostingRule id was invalid. |
401 | 5 | You do not have permission to view this Company's BillableHostingRules. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 113 | The BillableHostingRule was not found by its unique identifier. |
POST/billing/profiles/rules/{ruleId}
Creates new or updates an existing BillableHostingRule.
URL Parameters
Parameter | Type | Required | Description |
---|---|---|---|
ruleId | uint64? | optional | Unique identifier of the BillableHostingRule. This value is optional, and ignored by the command. |
HTTP Request body description
Property | Type | Required | Description |
---|---|---|---|
hostingRule | Object.<string, ?> | always | A simple object to contain the BillableHostingRule parameters. |
hostingRule | double? | optional | Cost per cycle for this plan |
hostingRule | datetime | create | Date this BillableHostingRule is applied until; null means it never ends. |
hostingRule | uint64? | update | Unique identifier of the BillableHostingRule you want to update. |
hostingRule | uint32? | optional | The number of units to which this BillableHostingRule applies. Should be a non-zero value; null means unlimited |
hostingRule | string | create | Name for the BillableHostingRule |
hostingRule | string | optional | Notes about the BillableHostingRule. |
hostingRule | uint64? | create | Unique identifier of this BillableHostingRule's BillingProfile. |
hostingRule | string | optional | A custom field used to refer to an external system. Examples are a cost codes, SOCs, discount plans... |
hostingRule | BillableHostingType? | create | The type of service being billed. |
hostingRule | datetime | create | Date this BillableHostingRule takes effect. |
hostingRule | boolean | optional | Does this BillableHostingRule apply to suspended resources |
hostingRule | expression | optional | Which assets are targetted by this BillableHostingRule |
hostingRule | Array.<int32> | optional | |
reqId | int32? | optional | Identifier used by external system to correlate requests to responses. |
HTTP Request body structure
{ "hostingRule": { "amount": number, "end": string, "id": number, "limit": number, "name": string, "notes": string, "profile": number, "reference": string, "service": string, "start": string, "suspended": boolean, "targets": string, "v": [ number ] }, "reqId": number }
Response description
Property | Type | Description |
---|---|---|
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
hostingRule | RespIdBillingProfile | An object which contains the "id", "company", and "profile" keys. |
hostingRule | uint64 | Identifier of the Company to which this object belongs. |
hostingRule | uint64? | Identifier given as input for the command. |
hostingRule | uint64 | Identifier of the BillingProfile to which this object belongs |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "errorCode": number, "errorDetails": { "kind": string }, "hostingRule": { "company": number, "id": number, "profile": number }, "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
500 | 2 | A communication error occurred. If you receive this error, please contact technical support. |
400 | 3 | The request does not contain a hostingRule object, or it is invalid. |
400 | 3 | Not enough keys exist in the hostingRule object. |
400 | 3 | During create: When creating a new BillableHostingRule, start date is invalid. |
400 | 3 | During create: When creating a new BillableHostingRule, end date is invalid. |
400 | 3 | During create: When creating a new BillableHostingRule, a name was not given, or it is invalid. |
400 | 3 | During create: When creating a new BillableHostingRule, profile is invalid. |
400 | 3 | During create: When creating a new BillableHostingRule, service is invalid. |
400 | 3 | During update: When updating a BillableHostingRule, the name was invalid. |
400 | 3 | During update: When updating a BillableHostingRule, the v was invalid. |
401 | 5 | During create: You do not have permission to create new BillableHostingRules. |
401 | 5 | During update: You do not have permission to update BillableHostingRules. |
400 | 6 | During update: When updating a BillableHostingRule, the v was not an array, or contained too few numbers. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 111 | The BillingProfile was not found by its unique identifier. If you receive this error, please contact technical support. |
404 | 113 | During update: The BillableHostingRule was not found by its unique identifier. |
409 | 130 | During update: When updating a BillableHostingRule, the hostingRule.profile can not be changed. |
DELETE/billing/profiles/rules/{ruleId}
Deletes an existing BillableHostingRule.
URL Parameters
Parameter | Type | Required | Description |
---|---|---|---|
ruleId | uint64 | required | Unique identifier of the BillableHostingRule. |
Response description
Property | Type | Description |
---|---|---|
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
hostingRule | RespDeleted | An object which contains the BillableHostingRule's unique identifier and deleted status. |
hostingRule | uint64 | Identifier of the Company to which this object belongs. |
hostingRule | boolean | Flag showing if the object is deleted. |
hostingRule | uint64? | Identifier given as input for the command. |
hostingRule | Array.<uint32> | |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "errorCode": number, "errorDetails": { "kind": string }, "hostingRule": { "company": number, "deleted": boolean, "id": number, "v": [ number ] }, "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
500 | 2 | A communication error occurred, the BillableHostingRule was not deleted. If you receive this error, please contact technical support. |
400 | 3 | The request does not contain a hostingRule object, or it is invalid. |
400 | 3 | The requested hostingRule id was invalid. |
401 | 5 | You do not have permission to delete this Company's BillableHostingRules. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 113 | The BillableHostingRule was not found by its unique identifier. |
PATCH/billing/profiles/rules/{ruleId}/restore
Restores the specified BillableHostingRule to its previous version.
URL Parameters
Parameter | Type | Required | Description |
---|---|---|---|
ruleId | uint64 | required | Unique identifier of the BillableHostingRule. |
Response description
Property | Type | Description |
---|---|---|
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
hostingRule | RespDeleted | An object which contains the BillableHostingRule's unique identifier and deleted status. |
hostingRule | uint64 | Identifier of the Company to which this object belongs. |
hostingRule | boolean | Flag showing if the object is deleted. |
hostingRule | uint64? | Identifier given as input for the command. |
hostingRule | Array.<uint32> | |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "errorCode": number, "errorDetails": { "kind": string }, "hostingRule": { "company": number, "deleted": boolean, "id": number, "v": [ number ] }, "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
500 | 2 | A communication error occurred. If you receive this error, please contact technical support. |
400 | 3 | The request does not contain a hostingRule object, or it is invalid. |
400 | 3 | The requested hostingRule id was invalid. |
401 | 5 | You do not have permission to restore BillableHostingRules. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 113 | The BillableHostingRule was not found by its unique identifier. |
400 | 114 | The BillableHostingRule was found, but is not marked as deleted. |
GET/companies/{companyId}/billing/profiles?includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number
Gets the list of BillingProfiles for the specified Company.
URL Parameters
Parameter | Type | Required | Description |
---|---|---|---|
companyId | uint64 | required | Unique identifier of the Company. |
highest | uint64? | optional | The largest valued id objects to retrieve. |
includeArchive | boolean | optional | When true, the command will also return archived objects. |
includeDeleted | boolean | optional | When true, the command will also return deleted objects. |
limit | uint16? | optional | Maximum number of objects in this response. |
lowest | uint64? | optional | The smallest valued id objects to retrieve. |
Response description
Property | Type | Description |
---|---|---|
billingProfiles | Array.<BillingProfile> | The list of requested BillingProfiles. |
company | RespId | An object to contain the "id" of the Company to which the array of BillingProfiles belong. |
company | uint64? | Identifier given as input for the command. |
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "billingProfiles": [ { "billee": number, "company": number, "currency": string, "cycle": string, "cycleEnd": string, "cyclePostDated": boolean, "cycleStart": string, "googleServicesEnabled": boolean, "id": number, "messages": [ { "amount": number, "limit": number } ], "name": string, "notes": string, "target": number, "v": [ number ] } ], "company": { "id": number }, "errorCode": number, "errorDetails": { "kind": string }, "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
500 | 2 | A communication error occurred. If you receive this error, please contact technical support. |
400 | 3 | The request does not contain a company object, or it is invalid. |
400 | 3 | The company object does not contain an id, or it is invalid. |
401 | 5 | You do not have permission to view this Company's BillingProfiles. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 28 | The Company was not found by its unique identifier. |
GET/companies/{companyId}/billing/profiles/reports?includeDeleted=boolean&includeArchive=boolean&limit=number&after=string&before=string
Gets the list of BillingReports for the specified Company.
URL Parameters
Parameter | Type | Required | Description |
---|---|---|---|
after | datetime | optional | A timestamp for the earliest objects (by dts) to retrieve. |
before | datetime | optional | A timestamp for the latest objects (by dts) to retrieve. |
companyId | uint64 | required | Unique identifier of the Company. |
includeArchive | boolean | optional | When true, the command will also return archived objects. |
includeDeleted | boolean | optional | When true, the command will also return deleted objects. |
limit | uint16? | optional | Maximum number of objects in this response. |
Response description
Property | Type | Description |
---|---|---|
billingReports | Array.<BillingReport> | The list of requested BillingReports. |
company | RespId | An object to contain the "id" of the Company to which the array of BillingReports belong. |
company | uint64? | Identifier given as input for the command. |
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "billingReports": [ { "billee": number, "breakdown": [ { "licenses": [ { "billableDays": number, "cost": number, "created": string, "deleted": string, "firmware": string, "kind": string, "name": string, "notes": string, "phoneNumber": number, "provider": string, "total": number } ], "services": [ { "asset": number, "billableDays": number, "cost": number, "created": string, "deleted": string, "kind": string, "labels": [ string ], "name": string, "notes": string, "phoneNumbers": [ number ], "providers": [ string ], "restored": string, "revived": string, "suspended": string, "suspendedCost": number, "suspendedDays": number, "total": number, "updatedDts": string } ], "target": number } ], "company": number, "currency": string, "endDate": string, "error": string, "id": number, "name": string, "notes": string, "profile": number, "startDate": string, "status": string, "summary": [ { "hosting": [ { "cost": number, "count": number, "sku": string, "total": number } ], "name": string, "notes": string, "parent": number, "target": number } ], "total": number, "v": [ number ] } ], "company": { "id": number }, "errorCode": number, "errorDetails": { "kind": string }, "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
500 | 2 | A communication error occurred. If you receive this error, please contact technical support. |
400 | 3 | The request does not contain a company object, or it is invalid. |
400 | 3 | The company object does not contain an id, or it is invalid. |
401 | 5 | You do not have permission to view this Company's BillingReports. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 28 | The Company was not found by its unique identifier. |
Companies
GET/companies?tree=boolean&includeParent=boolean&includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number
This request is an alias of /companies/{your-company-id}/tree?tree=false&includeParent=true (when no additional query-string parameters are given) or /companies/{your-company-id}/tree?tree=false&includeParent=true?{keys=values} (when at least one additional query-string key/value is given).
URL Parameters
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
includeParent | boolean | optional | true | Defaults to true for this alias. |
tree | boolean | optional | false | Defaults to false for this alias. |
your-company-id | uint64 | aliased | {your-company-id} | Your own Company's identifier. |
PATCH/companies
Creates a new or updates an existing Company.
Response description
Property | Type | Description |
---|---|---|
company | RespIdParent | An object which contains the "id" and "parent" keys. |
company | uint64? | Identifier given as input for the command. |
company | uint64? | Identifier of the parent to which this company belongs |
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "company": { "id": number, "parent": number }, "errorCode": number, "errorDetails": { "kind": string }, "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
500 | 2 | A communication error occurred. If you receive this error, please contact technical support. |
400 | 3 | The request does not contain a company object, or it is invalid. |
400 | 3 | No valid changes would be performed. |
400 | 3 | One of the keys in the company.labels object is blank. |
400 | 3 | One of the values in the company.labels object is not valid. |
400 | 3 | One of the keys in the company.tags object is blank. |
400 | 3 | One of the values in the company.tags object is not valid. |
400 | 3 | One of the keys in the company.directory object is blank. |
400 | 3 | One of the values in the company.directory object is not an array. |
400 | 3 | One of the arrays in the company.directory object contains an invalid value. |
400 | 3 | One of the values in the company.sessionPolicy.applications array contains an invalid regular expression. |
400 | 3 | One of the values in the company.sessionPolicy.ipv4Ranges array contains an invalid IP address or CIDR range. |
400 | 3 | The given value for the company.sessionPolicy.multiUser is invalid. |
400 | 3 | The given value for the company.sessionPolicy.expireTimeout is invalid. |
400 | 3 | The given value for the company.sessionPolicy.maxSessions is invalid. |
400 | 3 | The given value for the company.passwordPolicy.minimumLength is invalid. |
400 | 3 | The given value for the company.passwordPolicy.expireMode is invalid. |
400 | 3 | The given value for the company.passwordPolicy.expireThreshold is invalid. |
400 | 3 | The company.passwordPolicy.expireThreshold is zero, and the company.passwordPolicy.expireMode is anything but PasswordExpiryMode.never. |
400 | 3 | The company.references were not provided as null or an object. |
400 | 3 | During create: When creating a new Company, a name was not given. |
400 | 3 | During create: When creating a new Company, a parent was not given. |
400 | 3 | During update: When updating a Company, the name was given as null or blank. |
400 | 3 | During update: When updating a Company, the v was not an array, or contained too few numbers. |
400 | 3 | During create: When creating a new Company, too many company.references were given as input. Returns an ErrorDetailMinMax as the errorDetails .. |
401 | 5 | You do not have permission to create a new Company. |
401 | 5 | You do not have permission to update the CompanyGeneral. |
401 | 5 | You do not have permission to update the CompanyDirectory. |
401 | 5 | You do not have permission to update the CompanyStyles. |
401 | 5 | You do not have permission to update the CompanyPolicies. |
400 | 6 | During update: When updating a Company, an incorrect v value was given as input. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 28 | During update: The Company was not found by its unique identifier. |
409 | 130 | The given parent cannot be the same as the Company id. Returns an ErrorDetailParent as the errorDetails .. |
409 | 130 | The given parent would create a circular reference in the Company tree. Returns an ErrorDetailParent as the errorDetails .. |
409 | 130 | During update: When updating an Company, the resulting number of company.references would be too high. Returns an ErrorDetailParent as the errorDetails .. |
DELETE/companies
Deletes an existing Company.
Response description
Property | Type | Description |
---|---|---|
company | RespParentDeleted | An object which contains the Company's unique identifier and deleted status. |
company | boolean | Flag showing if the object is deleted. |
company | uint64? | Identifier given as input for the command. |
company | uint64 | Identifier of the parent to which the Company is a child. |
company | Array.<uint32> | |
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "company": { "deleted": boolean, "id": number, "parent": number, "v": [ number ] }, "errorCode": number, "errorDetails": { "kind": string }, "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
500 | 2 | A communication error occurred. If you receive this error, please contact technical support. |
400 | 3 | The request does not contain a company object, or it is invalid. |
400 | 3 | The company object does not contain an id, or it is invalid. |
401 | 5 | You do not have permission to delete this Company. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 28 | The Company was not found by its unique identifier. |
GET/companies/{companyId}?includeDeleted=boolean
Gets details of the specified Company.
URL Parameters
Parameter | Type | Required | Description |
---|---|---|---|
companyId | uint64 | required | Unique identifier of the Company. |
includeDeleted | boolean | optional | When true, the command will also return deleted objects. |
Response description
Property | Type | Description |
---|---|---|
company | Company | The requested Company. |
company | Object.<string, Array.<uint64>> for value-values see: Contact.id | The list of Contacts from this and other companies broken down by contact role. |
company | uint64 | Unique identifier of the Company. |
company | Object.<codified, LabelStyle> for keys see: LabelStyle.code | The styles for labels added to Assets, Places, and other things. |
company | string maximum-length: 100 | The organizational name. |
company | string | Notes. |
company | uint64 see: Company.id | The unique identifier of this company's parent organization. |
company | PasswordPolicy | The password complexity and expiry policy. |
company | PasswordExpiryMode | Defines how passwords expire. |
company | byte | The threshold for expiry. |
company | boolean | Do passwords require alphabetical characters. |
company | boolean | Do passwords require numeric characters. |
company | boolean | Do passwords require non-alphanumeric characters. |
company | boolean | Do passwords require upper-case and lower-case letters. |
company | byte | The minimum number of characters required. |
company | Object.<string, string> maximum-count: 10 maximum-length of keys: 20 maximum-length of values: 100 | Name/value collections of custom fields used to refer to external systems. |
company | CompanyReseller | If this company is a reseller, then they have their own theme, support and billing information. |
company | Object.<string, uint64> see: Contact.id maximum-count of keys: 100 for values see: Contact.id | A list of Contacts for company specific things like Technical Support, Billing, etc... |
company | string maximum-length: 100 | The URN and path to the instance of v4. It does not contain the protocol because all instances are required to be HTTPS. |
company | string maximum-length: 200 | The name of the icon file used for browser bookmarks. |
company | Object.<string, ColourStyle> maximum-length of keys: 25 | Colours used as templates for status tags, labels, and places. |
company | Object.<string, codified> maximum-length of keys: 25 maximum-length of values: 30 | A list of symbol names and their corresponding FontAwesome icon names. |
company | string maximum-length: 200 | The name of the image uploaded as the logo (used for collapsed/mobile view). |
company | uint64 see: Company.id | Unique identifier of the Company. |
company | Array.<codified> maximum-length of values: 5 | A list of supported languages for your customers. |
company | string maximum-length: 200 | The name of the image uploaded as the logo (used for regular view). |
company | NotificationServerEmail | The server used for notification and conversational email messages sent and received by the system. |
company | string | The domain or IP address of the incoming email server. |
company | string | The username used to login to the incoming email server. |
company | uint32 | IMAP message sequence number so only recent messages are retrieved. |
company | uint16 | The port number of the incoming email server. |
company | boolean | Is the incoming email server using a secure SSL/TLS connection (it should). |
company | string | The type of incoming protocol to use (IMAP or POP3). |
company | string | The domain or IP address of the outgoing email server. |
company | string | The username used to login to the outgoing email server. |
company | uint16 | The port number of the outgoing email server. |
company | An optional field which can be set as the "sent from" and/or "reply-to" address. | |
company | boolean | Is the outgoing email server using a secure SSL/TLS connection (it should). |
company | string | The type of outgoing protocol to use (only SMTP). |
company | NotificationServerSms | Definition for load-balanced outbound SMS numbers for the reseller. |
company | uint16 | A per-number/per-day limit on the amount of Notifications sent. |
company | Object.<string, Array.<phone>> fixed length of keys: 2 | All phone numbers listed by the country (using two-digit ISO 3166-1 alpha-2 country codes) they each serve. |
company | uint64 see: Company.id | The unique identifier of this company's parent organization. |
company | string | The body of the email sent to a user requesting a password reset. |
company | boolean | |
company | string | The subject of the email sent to a user requesting a password reset. |
company | string maximum-length: 150 | The name of the branded service being provided to the seller's customers. |
company | string | A preamble to the general terms and conditions offered by Fleet Freedom. |
company | datetime | The date and time when the terms were updated. This will promt users who are logging-in to re-agree to the new terms |
company | Array.<uint32> | Object version keys used to validate synchronization for all object properties. |
company | Object.<string, colour> maximum-length of keys: 25 maximum-length of values: 22 | Themed colours used in the web-based UI. |
company | SessionPolicy | The session lifetime policy. |
company | Array.<string> | The list of applications users are allowed to use to create sessions. |
company | uint16 | The lifetime duration of a session in minutes. |
company | boolean | Defines whether a session should be automatically killed when the connection breaks. |
company | Array.<ipv4> maximum-length of values: 19 | Restrict session creation to only the provided IPv4 ranges (using CIDR slash-notation). Leave blank for Internet access. |
company | byte | The maximum number of sessions allowed per user. |
company | SessionMultiUser | Defines the behaviour of the system when a user creates multiple sessions. |
company | Object.<codified, LabelStyle> for keys see: LabelStyle.code | The styles for status tags added to Assets. |
company | Array.<UserGroup> | A list of user groups that belong to this company. A user can only belong to groups from their own company. |
company | Array.<int32> fixed count: 6 | Object version keys used to validate synchronization for all object properties. |
company | int32 | The first element is for the general properties |
company | int32 | The second element is not used (yet) |
company | int32 | The third element is not used (yet) |
company | int32 | The fourth element is for the style properties |
company | int32 | The fifth element is for the policy properties |
company | int32 | The sixth element is for the reseller properties |
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "company": { "directory": { string: [ number ] }, "id": number, "labels": { string: { "code": string, "fill": string, "graphic": string, "name": string, "notes": string, "stroke": string } }, "name": string, "notes": string, "parent": number, "passwordPolicy": { "expireMode": string, "expireThreshold": number, "includeLetters": boolean, "includeNumbers": boolean, "includeSpecial": boolean, "includeUpperLower": boolean, "minimumLength": number }, "references": { string: string }, "reseller": { "contactInfo": { string: number }, "domain": string, "favourite": string, "gamut": { string: { "fill": string, "stroke": string } }, "graphics": { string: string }, "icon": string, "id": number, "languages": [ string ], "logo": string, "notifyEmail": { "incomingAddress": string, "incomingLogin": string, "incomingMessageNumber": number, "incomingPort": number, "incomingSecure": boolean, "incomingType": string, "outgoingAddress": string, "outgoingLogin": string, "outgoingPort": number, "outgoingReplyTo": string, "outgoingSecure": boolean, "outgoingType": string }, "notifySms": { "notifyLimit": number, "phoneNumbers": { string: [ number ] } }, "parent": number, "recoverBody": string, "recoverIsHtml": boolean, "recoverSubject": string, "serviceName": string, "termsPreamble": string, "termsUpdated": string, "v": [ number ], "website": { string: string } }, "sessionPolicy": { "applications": [ string ], "expireTimeout": number, "idleAllowed": boolean, "ipv4Ranges": [ string ], "maxSessions": number, "multiUser": string }, "tags": { string: { "code": string, "fill": string, "graphic": string, "name": string, "notes": string, "stroke": string } }, "userGroups": [ { "company": number, "id": number, "name": string, "notes": string, "permissions": [ { "company": number, "kind": string, "labels": [ string ], "level": string, "method": string, "type": string } ], "v": [ number ] } ], "v": [ number ] }, "errorCode": number, "errorDetails": { "kind": string }, "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
400 | 3 | The request does not contain a company object, or it is invalid. |
400 | 3 | The company object does not contain an id, or it is invalid. |
401 | 5 | You do not have permission to view this Company. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 28 | The Company was not found by its unique identifier. |
POST/companies/{companyId}
Creates a new or updates an existing Company.
URL Parameters
Parameter | Type | Required | Description |
---|---|---|---|
companyId | uint64? | optional | Unique identifier of the Company. This value is optional, and ignored by the command. |
HTTP Request body description
Property | Type | Required | Description |
---|---|---|---|
company | Object.<string, ?> | always | A simple object to contain the company parameters. |
company | Object.<string, Array.<uint64>> for value-values see: Contact.id | optional | The list of Contacts from this and other companies broken down by contact role. |
company | uint64? | update | Unique identifier of the Company. |
company | Object.<string, LabelStyle> | optional | The styles for labels added to Assets, Places, and other things. |
company | string maximum-length: 100 | create | The organizational name. |
company | string | optional | Notes. |
company | uint64? | create | The unique identifier of this company's parent organization. |
company | Object.<string, ?> | always | The password complexity and expiry policy. |
company | PasswordExpiryMode? | optional | Defines how passwords expire. |
company | byte? | optional | The threshold for expiry (in days). |
company | boolean | optional | Do passwords require alphabetical characters. |
company | boolean | optional | Do passwords require numeric characters. |
company | boolean | optional | Do passwords require non-alphanumeric characters. |
company | boolean | optional | Do passwords require upper-case and lower-case letters. |
company | byte? | optional | The minimum number of characters required. |
company | Object.<string, string> | optional | Name/value collections of custom fields used to refer to external systems. If the value is null, the references are removed from the Company. |
company | Object.<string, ?> | always | The session lifetime policy. |
company | Array.<string> | optional | The list of applications users are allowed to use to create sessions. |
company | uint16? | optional | The lifetime duration of a session in minutes. |
company | boolean | optional | Defines whether a session should be automatically killed when the connection breaks. |
company | Array.<ipv4> maximum-length of values: 19 | optional | Restrict session creation to only the provided IPv4 ranges (using CIDR slash-notation). Leave blank for Internet access. |
company | byte? | optional | The maximum number of sessions allowed per user. |
company | SessionMultiUser? | optional | Defines the behaviour of the system when a user creates multiple sessions. |
company | Object.<string, LabelStyle> | optional | The styles for status tags added to Assets. |
company | Array.<int32> | optional | |
reqId | int32? | optional | Identifier used by external system to correlate requests to responses. |
HTTP Request body structure
{ "company": { "directory": { string: [ number ] }, "id": number, "labels": { string: { "code": string, "fill": string, "graphic": string, "name": string, "notes": string, "stroke": string } }, "name": string, "notes": string, "parent": number, "passwordPolicy": { "expireMode": string, "expireThreshold": number, "includeLetters": boolean, "includeNumbers": boolean, "includeSpecial": boolean, "includeUpperLower": boolean, "minimumLength": number }, "references": { string: string }, "sessionPolicy": { "applications": [ string ], "expireTimeout": number, "idleAllowed": boolean, "ipv4Ranges": [ string ], "maxSessions": number, "multiUser": string }, "tags": { string: { "code": string, "fill": string, "graphic": string, "name": string, "notes": string, "stroke": string } }, "v": [ number ] }, "reqId": number }
Response description
Property | Type | Description |
---|---|---|
company | RespIdParent | An object which contains the "id" and "parent" keys. |
company | uint64? | Identifier given as input for the command. |
company | uint64? | Identifier of the parent to which this company belongs |
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "company": { "id": number, "parent": number }, "errorCode": number, "errorDetails": { "kind": string }, "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
500 | 2 | A communication error occurred. If you receive this error, please contact technical support. |
400 | 3 | The request does not contain a company object, or it is invalid. |
400 | 3 | No valid changes would be performed. |
400 | 3 | One of the keys in the company.labels object is blank. |
400 | 3 | One of the values in the company.labels object is not valid. |
400 | 3 | One of the keys in the company.tags object is blank. |
400 | 3 | One of the values in the company.tags object is not valid. |
400 | 3 | One of the keys in the company.directory object is blank. |
400 | 3 | One of the values in the company.directory object is not an array. |
400 | 3 | One of the arrays in the company.directory object contains an invalid value. |
400 | 3 | One of the values in the company.sessionPolicy.applications array contains an invalid regular expression. |
400 | 3 | One of the values in the company.sessionPolicy.ipv4Ranges array contains an invalid IP address or CIDR range. |
400 | 3 | The given value for the company.sessionPolicy.multiUser is invalid. |
400 | 3 | The given value for the company.sessionPolicy.expireTimeout is invalid. |
400 | 3 | The given value for the company.sessionPolicy.maxSessions is invalid. |
400 | 3 | The given value for the company.passwordPolicy.minimumLength is invalid. |
400 | 3 | The given value for the company.passwordPolicy.expireMode is invalid. |
400 | 3 | The given value for the company.passwordPolicy.expireThreshold is invalid. |
400 | 3 | The company.passwordPolicy.expireThreshold is zero, and the company.passwordPolicy.expireMode is anything but PasswordExpiryMode.never. |
400 | 3 | The company.references were not provided as null or an object. |
400 | 3 | During create: When creating a new Company, a name was not given. |
400 | 3 | During create: When creating a new Company, a parent was not given. |
400 | 3 | During update: When updating a Company, the name was given as null or blank. |
400 | 3 | During update: When updating a Company, the v was not an array, or contained too few numbers. |
400 | 3 | During create: When creating a new Company, too many company.references were given as input. Returns an ErrorDetailMinMax as the errorDetails .. |
401 | 5 | You do not have permission to create a new Company. |
401 | 5 | You do not have permission to update the CompanyGeneral. |
401 | 5 | You do not have permission to update the CompanyDirectory. |
401 | 5 | You do not have permission to update the CompanyStyles. |
401 | 5 | You do not have permission to update the CompanyPolicies. |
400 | 6 | During update: When updating a Company, an incorrect v value was given as input. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 28 | During update: The Company was not found by its unique identifier. |
409 | 130 | The given parent cannot be the same as the Company id. Returns an ErrorDetailParent as the errorDetails .. |
409 | 130 | The given parent would create a circular reference in the Company tree. Returns an ErrorDetailParent as the errorDetails .. |
409 | 130 | During update: When updating an Company, the resulting number of company.references would be too high. Returns an ErrorDetailParent as the errorDetails .. |
DELETE/companies/{companyId}
Deletes an existing Company.
URL Parameters
Parameter | Type | Required | Description |
---|---|---|---|
companyId | uint64 | required | Unique identifier of the Company. |
Response description
Property | Type | Description |
---|---|---|
company | RespParentDeleted | An object which contains the Company's unique identifier and deleted status. |
company | boolean | Flag showing if the object is deleted. |
company | uint64? | Identifier given as input for the command. |
company | uint64 | Identifier of the parent to which the Company is a child. |
company | Array.<uint32> | |
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "company": { "deleted": boolean, "id": number, "parent": number, "v": [ number ] }, "errorCode": number, "errorDetails": { "kind": string }, "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
500 | 2 | A communication error occurred. If you receive this error, please contact technical support. |
400 | 3 | The request does not contain a company object, or it is invalid. |
400 | 3 | The company object does not contain an id, or it is invalid. |
401 | 5 | You do not have permission to delete this Company. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 28 | The Company was not found by its unique identifier. |
PATCH/companies/{companyId}/restore
Restores the specified Company.
URL Parameters
Parameter | Type | Required | Description |
---|---|---|---|
companyId | uint64 | required | Unique identifier of the Company. |
Response description
Property | Type | Description |
---|---|---|
company | RespParentDeleted | An object which contains the Company's unique identifier and deleted status. |
company | boolean | Flag showing if the object is deleted. |
company | uint64? | Identifier given as input for the command. |
company | uint64 | Identifier of the parent to which the Company is a child. |
company | Array.<uint32> | |
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "company": { "deleted": boolean, "id": number, "parent": number, "v": [ number ] }, "errorCode": number, "errorDetails": { "kind": string }, "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
500 | 2 | A communication error occurred. If you receive this error, please contact technical support. |
400 | 3 | The request does not contain a company object, or it is invalid. |
400 | 3 | The company object does not contain an id, or it is invalid. |
401 | 5 | You do not have permission to restore this Company. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 28 | The Company was not found by its unique identifier. |
400 | 29 | The Company was found, but is not marked as deleted. |
GET/companies/{companyId}/tree?tree=boolean&includeParent=boolean&includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number
Gets the list of child-companies for the specified Company.
By default the full tree of companies is returned, but this can be overridden using tree.
By default it does not include the parent Company, but this can be overridden using includeParent.
URL Parameters
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
companyId | uint64 | required | Unique identifier of the Company. | |
highest | uint64? | optional | The largest valued id objects to retrieve. | |
includeArchive | boolean | optional | When true, the command will also return archived objects. | |
includeDeleted | boolean | optional | When true, the command will also return deleted objects. | |
includeParent | boolean | optional | false | |
limit | uint16? | optional | Maximum number of objects in this response. | |
lowest | uint64? | optional | The smallest valued id objects to retrieve. | |
tree | boolean | optional | true | When set to true, the parent Company is included in the results. |
Response description
Property | Type | Description |
---|---|---|
companies | Array.<CompanyGeneral> | The list of requested companies. |
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "companies": [ { "id": number, "name": string, "notes": string, "parent": number, "references": { string: string }, "v": [ number ] } ], "errorCode": number, "errorDetails": { "kind": string }, "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
400 | 3 | The request does not contain a company object, or it is invalid. |
400 | 3 | The company object does not contain an id, or it is invalid. |
401 | 5 | You do not have permission to view this Company or child companies. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 28 | The Company was not found by its unique identifier. |
GET/companies/{companyId}/tree ?{keys=values}?tree=boolean&includeParent=boolean&includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number&{keys=values}
Gets the list of companies only if one of the specified Company.references fields match.
If no references are specified, it will match any Company with no references.
If a reference value is null, it will match any Company without that reference key.
By default the full tree of companies is returned, but this can be overridden using tree.
By default it does not include the parent Company, but this can be overridden using includeParent.
URL Parameters
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
companyId | uint64 | required | Unique identifier of the Company. | |
highest | uint64? | optional | The largest valued id objects to retrieve. | |
includeArchive | boolean | optional | When true, the command will also return archived objects. | |
includeDeleted | boolean | optional | When true, the command will also return deleted objects. | |
includeParent | boolean | optional | false | |
limit | uint16? | optional | Maximum number of objects in this response. | |
lowest | uint64? | optional | The smallest valued id objects to retrieve. | |
tree | boolean | optional | true | When set to true, the parent Company is included in the results. |
Response description
Property | Type | Description |
---|---|---|
companies | Array.<CompanyGeneral> | The list of requested companies. |
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
message | string | An English description of the error. |
references | Object.<string, string> | The reference string given as input. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "companies": [ { "id": number, "name": string, "notes": string, "parent": number, "references": { string: string }, "v": [ number ] } ], "errorCode": number, "errorDetails": { "kind": string }, "message": string, "references": { string: string }, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
400 | 3 | The request does not contain a company object, or it is invalid. |
400 | 3 | The company object does not contain an id, or it is invalid. |
400 | 3 | The references is not an object, or it is invalid. |
401 | 5 | You do not have permission to view this Company or child companies. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 28 | The Company was not found by its unique identifier. |
GET/companies/tree?tree=boolean&includeParent=boolean&includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number
This request is an alias of /companies/{your-company-id}/tree?tree=true&includeParent=true (when no additional query-string parameters are given) or /companies/{your-company-id}/tree?tree=true&includeParent=true?{keys=values} (when at least one additional query-string key/value is given).
URL Parameters
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
includeParent | boolean | optional | true | Defaults to true for this alias. |
tree | boolean | optional | true | Defaults to true for this alias. |
your-company-id | uint64 | aliased | {your-company-id} | Your own Company's identifier. |
Contacts
GET/companies/{companyId}/contacts?includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number
URL Parameters
Parameter | Type | Required | Description |
---|---|---|---|
companyId | uint64 | required | Unique identifier of the Company. |
highest | uint64? | optional | The largest valued id objects to retrieve. |
includeArchive | boolean | optional | When true, the command will also return archived objects. |
includeDeleted | boolean | optional | When true, the command will also return deleted objects. |
limit | uint16? | optional | Maximum number of objects in this response. |
lowest | uint64? | optional | The smallest valued id objects to retrieve. |
Response description
Property | Type | Description |
---|---|---|
company | RespId | An object to contain the "id" of the Company to which the array of Contacts belong. |
company | uint64? | Identifier given as input for the command. |
contacts | Array.<Contact> | The list of requested Contacts. |
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "company": { "id": number }, "contacts": [ { "addresses": { string: string }, "company": number, "dates": { string: string }, "emails": { string: string }, "id": number, "name": string, "notes": string, "options": { string: string }, "otherNames": { string: string }, "phones": { string: number }, "pictures": [ number ], "roles": [ string ], "urls": { string: string }, "v": [ number ] } ], "errorCode": number, "errorDetails": { "kind": string }, "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
500 | 2 | A communication error occurred. If you receive this error, please contact technical support. |
400 | 3 | The request does not contain a company object, or it is invalid. |
400 | 3 | The company object does not contain an id, or it is invalid. |
401 | 5 | You do not have permission to view Contacts for this Company. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 28 | The Company was not found by its unique identifier. |
GET/contacts?includeDeleted=boolean&includeArchive=boolean&limit=number&lowest=number&highest=number
This request is an alias of /companies/{your-company-id}/contacts/.
URL Parameters
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
your-company-id | uint64 | aliased | {your-company-id} | Your own Company's identifier. |
PATCH/contacts
Creates a new or updates an existing Contact.
Response description
Property | Type | Description |
---|---|---|
contact | RespIdCompany | An object which contains the "id" and "company" keys when there is no error. |
contact | uint64 | Identifier of the Company to which this object belongs. |
contact | uint64? | Identifier given as input for the command. |
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "contact": { "company": number, "id": number }, "errorCode": number, "errorDetails": { "kind": string }, "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
500 | 2 | A communication error occurred. If you receive this error, please contact technical support. |
400 | 3 | The request does not contain a contact object, or it is invalid. |
400 | 3 | Not enough keys exist in the contact object. |
400 | 3 | During create: When creating a new Contact, a company was not given. |
400 | 3 | During create: When creating a new Contact, a name was not given, or it is invalid. |
400 | 3 | During update: When updating a Contact, the id was invalid. |
400 | 3 | During update: When updating a Contact, the name was given as blank. |
400 | 3 | During update: When updating a Contact, the v was not an array, or contained too few numbers. |
400 | 3 | One of the contact.otherNames keys or values is invalid. Returns an ErrorDetailInput as the errorDetails .. |
400 | 3 | One of the contact.emails keys or values is invalid. Returns an ErrorDetailInput as the errorDetails .. |
400 | 3 | One of the contact.phones keys or values is invalid. Returns an ErrorDetailInput as the errorDetails .. |
400 | 3 | One of the contact.addresses keys or values is invalid. Returns an ErrorDetailInput as the errorDetails .. |
400 | 3 | One of the contact.urls keys or values is invalid. Returns an ErrorDetailInput as the errorDetails .. |
400 | 3 | One of the contact.dates keys or values is invalid. Returns an ErrorDetailInput as the errorDetails .. |
400 | 3 | One of the contact.options keys or values is invalid. Returns an ErrorDetailInput as the errorDetails .. |
400 | 3 | One of the contact.pictures values is invalid. Returns an ErrorDetailInput as the errorDetails .. |
401 | 5 | You do not have permission to create a new Contact. |
401 | 5 | You do not have permission to update this Contact. |
400 | 6 | During update: When updating a Contact, an incorrect v value was given as input. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 31 | During update: The Contact was not found by its unique identifier. |
404 | 69 | One of the contact.pictures given as input in the Pictures array was not found. Returns an ErrorDetailBadIds as the errorDetails .. |
409 | 130 | During update: When updating a Contact, the company was provided as a different value. |
DELETE/contacts
Deletes an existing Contact.
Response description
Property | Type | Description |
---|---|---|
contact | RespDeleted | An object which contains the Contact's id, owning Company id, and deleted status. |
contact | uint64 | Identifier of the Company to which this object belongs. |
contact | boolean | Flag showing if the object is deleted. |
contact | uint64? | Identifier given as input for the command. |
contact | Array.<uint32> | |
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "contact": { "company": number, "deleted": boolean, "id": number, "v": [ number ] }, "errorCode": number, "errorDetails": { "kind": string }, "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
500 | 2 | A communication error occurred. If you receive this error, please contact technical support. |
400 | 3 | The request does not contain a contact object, or it is invalid. |
400 | 3 | The contact object does not contain an id, or it is invalid. |
401 | 5 | You do not have permission to delete this Contact. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 31 | The Contact was not found by its unique identifier. |
409 | 121 | This Contact is still being used by a Asset or User. Returns an ErrorDetailContactInUse as the errorDetails .. |
GET/contacts/{contactId}?includeDeleted=boolean
Gets details of the specified Contact.
URL Parameters
Parameter | Type | Required | Description |
---|---|---|---|
contactId | uint64 | required | Unique identifier of the Contact. |
includeDeleted | boolean | optional | When true, the command will also return deleted objects. |
Response description
Property | Type | Description |
---|---|---|
contact | Contact | The requested Contact. |
contact | Object.<string, string> | Mailing addresses. Use the object key like a name of the address. Example keys: Home, Work, Park, etc. |
contact | uint64 see: Company.id | The company to which this contact belongs |
contact | Object.<string, datetime> | Date information. Use the object key like a name of the date. Example keys: Birthday, Started Date, Retired On, etc. |
contact | Object.<string, email> maximum-length of values: 254 | Email addresses. Use the object key like a name of the address. Example keys: Home, Work, Support, Old, etc. |
contact | uint64 | Unique identifier of this contact. |
contact | string maximum-length: 100 | The person's name |
contact | string | Notes about this person. |
contact | Object.<string, string> | Uncategorized information. Use the object keys and values however you'd like. |
contact | Object.<string, string> maximum-length of values: 254 | A collection of other names this person might go by. Use the object key like a name identifier. Example keys: Initials, Nickname, Maiden Name, etc. |
contact | Object.<string, phone> | Phone numbers. Use the object key like a name of the phone number. Example keys: Mobile, Fax, Home, Office, etc. |
contact | Array.<uint64> for values see: Picture.id | Pictures of this Contact. |
contact | Array.<string> | A list of roles they play in the Company. |
contact | Object.<string, url> maximum-length of values: 254 | Websites and other online resources. Use the object key like a name of the address. Example keys: Downloads, Support, FTP, etc. |
contact | Array.<uint32> | Object version keys used to validate synchronization for all object properties. |
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "contact": { "addresses": { string: string }, "company": number, "dates": { string: string }, "emails": { string: string }, "id": number, "name": string, "notes": string, "options": { string: string }, "otherNames": { string: string }, "phones": { string: number }, "pictures": [ number ], "roles": [ string ], "urls": { string: string }, "v": [ number ] }, "errorCode": number, "errorDetails": { "kind": string }, "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
400 | 3 | The request does not contain a contact object, or it is invalid. |
400 | 3 | The contact object does not contain an id, or it is invalid. |
401 | 5 | You do not have permission to view this Contact. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 31 | The Contact was not found by its unique identifier. |
POST/contacts/{contactId}
Creates a new or updates an existing Contact.
URL Parameters
Parameter | Type | Required | Description |
---|---|---|---|
contactId | uint64? | optional | Unique identifier of the Contact. This value is optional, and ignored by the command. |
HTTP Request body description
Property | Type | Required | Description |
---|---|---|---|
contact | Object.<string, ?> | always | A simple object to contain the Contact parameters. |
contact | Object.<string, string> | optional | Mailing addresses Use the object key like a name of the address. Example keys: Home, Work, Park, etc. |
contact | uint64? | create | The Company to which this Contact belongs. After creation, this value is read-only. |
contact | Object.<string, datetime> | optional | Date information Use the object key like a name of the date. Example keys: Birthday, Started Date, Retired On, etc. |
contact | Object.<string, email> maximum-length of values: 254 | optional | Email addresses Use the object key like a name of the address. Example keys: Home, Work, Support, Old, etc. |
contact | uint64? | update | The unique identifier of the Contact you want to update. |
contact | string maximum-length: 100 | optional | Name for the Contact. |
contact | string | optional | Notes for the Contact. |
contact | Object.<string, string> | optional | Uncategorized information Use the object keys and values however you'd like. |
contact | Object.<string, string> maximum-length of values: 254 | optional | A collection of other names this person might go by. Use the object key like a name identifier. Example keys: Initials, Nickname, Maiden Name, etc. |
contact | Object.<string, phone?> | optional | Phone numbers. Use the object key like a name of the phone number. Example keys: Mobile, Fax, Home, Office, etc. |
contact | Array.<uint64> for values see: Picture.id | optional | Pictures of this Contact. |
contact | Array.<codified> | optional | A list of roles they play in the Company. |
contact | Object.<string, url> maximum-length of values: 254 | optional | Websites and other online resources Use the object key like a name of the address. Example keys: Downloads, Support, FTP, etc. |
contact | Array.<int32> | optional | |
reqId | int32? | optional | Identifier used by external system to correlate requests to responses. |
HTTP Request body structure
{ "contact": { "addresses": { string: string }, "company": number, "dates": { string: string }, "emails": { string: string }, "id": number, "name": string, "notes": string, "options": { string: string }, "otherNames": { string: string }, "phones": { string: number }, "pictures": [ number ], "roles": [ string ], "urls": { string: string }, "v": [ number ] }, "reqId": number }
Response description
Property | Type | Description |
---|---|---|
contact | RespIdCompany | An object which contains the "id" and "company" keys when there is no error. |
contact | uint64 | Identifier of the Company to which this object belongs. |
contact | uint64? | Identifier given as input for the command. |
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "contact": { "company": number, "id": number }, "errorCode": number, "errorDetails": { "kind": string }, "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
500 | 2 | A communication error occurred. If you receive this error, please contact technical support. |
400 | 3 | The request does not contain a contact object, or it is invalid. |
400 | 3 | Not enough keys exist in the contact object. |
400 | 3 | During create: When creating a new Contact, a company was not given. |
400 | 3 | During create: When creating a new Contact, a name was not given, or it is invalid. |
400 | 3 | During update: When updating a Contact, the id was invalid. |
400 | 3 | During update: When updating a Contact, the name was given as blank. |
400 | 3 | During update: When updating a Contact, the v was not an array, or contained too few numbers. |
400 | 3 | One of the contact.otherNames keys or values is invalid. Returns an ErrorDetailInput as the errorDetails .. |
400 | 3 | One of the contact.emails keys or values is invalid. Returns an ErrorDetailInput as the errorDetails .. |
400 | 3 | One of the contact.phones keys or values is invalid. Returns an ErrorDetailInput as the errorDetails .. |
400 | 3 | One of the contact.addresses keys or values is invalid. Returns an ErrorDetailInput as the errorDetails .. |
400 | 3 | One of the contact.urls keys or values is invalid. Returns an ErrorDetailInput as the errorDetails .. |
400 | 3 | One of the contact.dates keys or values is invalid. Returns an ErrorDetailInput as the errorDetails .. |
400 | 3 | One of the contact.options keys or values is invalid. Returns an ErrorDetailInput as the errorDetails .. |
400 | 3 | One of the contact.pictures values is invalid. Returns an ErrorDetailInput as the errorDetails .. |
401 | 5 | You do not have permission to create a new Contact. |
401 | 5 | You do not have permission to update this Contact. |
400 | 6 | During update: When updating a Contact, an incorrect v value was given as input. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 31 | During update: The Contact was not found by its unique identifier. |
404 | 69 | One of the contact.pictures given as input in the Pictures array was not found. Returns an ErrorDetailBadIds as the errorDetails .. |
409 | 130 | During update: When updating a Contact, the company was provided as a different value. |
DELETE/contacts/{contactId}
Deletes an existing Contact.
URL Parameters
Parameter | Type | Required | Description |
---|---|---|---|
contactId | uint64 | required | Unique identifier of the Contact. |
Response description
Property | Type | Description |
---|---|---|
contact | RespDeleted | An object which contains the Contact's id, owning Company id, and deleted status. |
contact | uint64 | Identifier of the Company to which this object belongs. |
contact | boolean | Flag showing if the object is deleted. |
contact | uint64? | Identifier given as input for the command. |
contact | Array.<uint32> | |
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "contact": { "company": number, "deleted": boolean, "id": number, "v": [ number ] }, "errorCode": number, "errorDetails": { "kind": string }, "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
500 | 2 | A communication error occurred. If you receive this error, please contact technical support. |
400 | 3 | The request does not contain a contact object, or it is invalid. |
400 | 3 | The contact object does not contain an id, or it is invalid. |
401 | 5 | You do not have permission to delete this Contact. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 31 | The Contact was not found by its unique identifier. |
409 | 121 | This Contact is still being used by a Asset or User. Returns an ErrorDetailContactInUse as the errorDetails .. |
PATCH/contacts/{contactId}/restore
Restores the specified Contact.
URL Parameters
Parameter | Type | Required | Description |
---|---|---|---|
contactId | uint64 | required | Unique identifier of the Contact. |
Response description
Property | Type | Description |
---|---|---|
contact | RespDeleted | An object which contains the Contact's id, owning Company id, and deleted status. |
contact | uint64 | Identifier of the Company to which this object belongs. |
contact | boolean | Flag showing if the object is deleted. |
contact | uint64? | Identifier given as input for the command. |
contact | Array.<uint32> | |
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "contact": { "company": number, "deleted": boolean, "id": number, "v": [ number ] }, "errorCode": number, "errorDetails": { "kind": string }, "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
500 | 2 | A communication error occurred. If you receive this error, please contact technical support. |
400 | 3 | The request does not contain a contact object, or it is invalid. |
400 | 3 | The contact object does not contain an id, or it is invalid. |
401 | 5 | You do not have permission to restore this Contact. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 31 | The Contact was not found by its unique identifier. |
400 | 32 | The Contact was found, but is not marked as deleted. |
Dispatch
POST/assets/{assetId}/dispatch
Updates an existing AssetDispatch.
URL Parameters
Parameter | Type | Required | Description |
---|---|---|---|
assetId | uint64? | optional | Unique identifier of the Asset. This value is optional, and ignored by the command. |
HTTP Request body description
Property | Type | Required | Description |
---|---|---|---|
assetDispatch | Object.<string, ?> | always | A simple object to contain the AssetDispatch parameters. |
assetDispatch | Array.<DispatchDirection> | optional | Driving directions and route path details. |
assetDispatch | uint64 | always | The unique identifier of the asset you want to update. |
assetDispatch | Array.<uint64> see: DispatchJob | optional | The list of DispatchJobs to be assigned to this asset. |
assetDispatch | boolean | optional | Indicates whether the jobs should be optimized based on distance and priority. |
assetDispatch | Array.<int32> | optional | |
reqId | int32? | optional | Identifier used by external system to correlate requests to responses. |
HTTP Request body structure
{ "assetDispatch": { "directions": [ { "directions": [ { /* recursive DispatchDirection objects */ } ], "distance": number, "duration": string, "instructions": string, "job": number, "path": string, "step": number } ], "id": number, "jobs": [ number ], "optimize": boolean, "v": [ number ] }, "reqId": number }
Response description
Property | Type | Description |
---|---|---|
assetDispatch | RespIdCompany | An object which contains the "id" and "company" keys. |
assetDispatch | uint64 | Identifier of the Company to which this object belongs. |
assetDispatch | uint64? | Identifier given as input for the command. |
errorCode | ErrorCode | The unique, numeric error code when processing this request. |
errorDetails | ErrorDetail | An object to provide developers with a hint about the nature of the error. The key is not always present, and only available for some errors. |
message | string | An English description of the error. |
reqId | int32? | Identifier used by external system to correlate requests to responses. |
Response structure
{ "assetDispatch": { "company": number, "id": number }, "errorCode": number, "errorDetails": { "kind": string }, "message": string, "reqId": number }
Possible exceptions
HTTP Status | Error Code | Description |
---|---|---|
500 | 2 | A communication error occurred. If you receive this error, please contact technical support. |
400 | 3 | The request does not contain an assetDispatch object, or it is invalid. |
400 | 3 | Not enough keys exist in the assetDispatch object. |
400 | 3 | The assetDispatch.id is invalid. |
400 | 3 | The v was not an array, or contained too few numbers. |
400 | 3 | One of the assetDispatch.jobs given in the array cannot be parsed, or is a value less than zero. Returns an ErrorDetailInput as the errorDetails .. |
400 | 3 | One of the assetDispatch.directions given in the array cannot be parsed. Returns an ErrorDetailInput as the errorDetails .. |
401 | 5 | You do not have permission to update the AssetDispatch. |
401 | 5 | You do not have permission to view this Asset. |
400 | 6 | During update: When updating an AssetDispatch, the wrong version key was given. |
401 | 7 | You cannot execute this command because your session has expired. |
502 | 8 | You cannot execute this command because you are not logged in. |
403 | 16 | You cannot execute this command because your password has expired. |
404 | 20 | This Asset was not found by its unique identifier. |
404 | 20 | The Asset for one of the assetDispatch.jobs was not found. |
502 | 82 | An error occured while optimizing the job steps. |
403 |