Programming Guide to the Hours of Service Platform

Visibility Sets

Visibility Sets control who can see which resources. Assets and Users have Visibility Sets. Users can only create or modify Assets with at least one matching Visibility Set. The default set of a fresh Account is “Visibility Set1” but this can be changed to another set. Inversely, a User can have multiple Visibility Sets, granting visibility to all Assets that include any of those sets.

Fields

Tag Data Type Required Description
accountId Long Auto The id of the Account that owns this record.
id Auto-incremented Long Auto Unique Identifier 
isDefault Boolean No Indicates if it is the designated Default Set
lastChangedDate Text Auto Auto-generated timestamp of the last change made to this record
Note: Format is in timestamp and timezone (YYYY-MM-DDTHH:MM:SS.sssZ, e.g: 1970-01-01T00:00:00.000Z)
name Character Yes Name of the Visibility Set 

Create

API PATH: /api/v2/visibilitySets
METHOD: POST
EXAMPLE REQUEST: 
[
  {
    "name": "Set1",
    "isDefault": false,
    "accountId": 1248100
  }
]
EXAMPLE RESPONSE: 
[
  {
    "name": "Set1",
    "isDefault": false,
    "accountId": 1248100,
    "id": 1544,
    "lastChangedDate": "2018-06-11T12:00:00.000Z"
  }
]

Read

API PATH: /api/v2/visibilitySets
METHOD: GET
PARAMETERS: name – Retrieves matching records with the specific name (e.g. name=Set1, all names by default)
offset – Retrieves matching records after an offset value (e.g. offset=2)
limit – Retrieves a number of records per page specified by the value (e.g. limit=10)
SORTING: sort=id – Sort records by their id field in ascending order (DEFAULT)
sort=-id – Sort records by their id field in descending order
sort=name – Sort records by their name field in ascending order
sort=-name – Sort records by their name field in descending order
QUERY STRING EXAMPLES: Get the Visibility Set with the specified id: api/v2/visibilitySets/1544
Get two Visibility Sets of the current Account with an offset of 1 : ?offset=1&limit=2
Get all Visibility Sets of the current Account sorted by name alphabetically: ?sort=name
EXAMPLE RESPONSE: 
[
  {
    "name": "Set1",
    "isDefault": false,
    "accountId": 1248100,
    "id": 1544,
    "lastChangedDate": "2018-06-11T12:00:00.000Z"
  }
]

Update

API PATH: /api/v2/visibilitySets
METHOD: PUT
EXAMPLE REQUEST: 
[
  {
    "name": "Set1",
    "isDefault": false,
    "accountId": 1248100,
    "id": 1544
  }
]
EXAMPLE RESPONSE: 
[
  {
    "name": "Set1",
    "isDefault": false,
    "accountId": 1248100,
    "id": 1544,
    "lastChangedDate": "2018-06-11T12:00:00.000Z"
  }
]

Delete

API PATH: /api/v2/visibilitySets/<id>
METHOD: DELETE

API error calls

ERROR MESSAGE POSSIBLE CAUSES
Access Denied. POST, PUT and DELETE methods require user role of ACCOUNTADMIN or higher
A visibility set with the given ID was not found. PUT error because Visibility Set id does not exist.
A visibility set cannot be deleted when it has assets assigned to it. DELETE error because Visibility Set to be deleted has Assets assigned to it.