Licenses

The Licenses API allows Account administrators to query and create Licenses for their Accounts. Licenses will be used for allocation to the Drivers of that Account on a one-to-one basis. Unassigned Licenses can also be moved to a sub-account under the current Account.

Upon Driver activation, a Driver will be assigned a license based on the available set of Licenses for that Account. If there are no available Licenses, Driver creation will fail. A License that was assigned to a Driver that has been terminated will again be available for reassignment but not anymore for moving to a sub-account.

Fields

Tag Data Type Required Description
accountId Long Auto The id of the Account that owns this record.
duration Interval Yes Duration regarding validity of the License.
id Auto-incremented Long Auto Unique identifier
key Text (Unlimited) Yes A string of hexadecimal values that uniquely identifies the License 
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)
registrationDate Text Auto Date when the License was generated
Note: Format must be in (YYYY-MM-DD)
skuId Long Yes The SKU ID assigned to the License. This ID must be the same with the SKU ID allowed in the Account.
status Text Auto Indicates if the License is currently assigned to a Driver or not.
type Character (25) Yes Indicates the type of license.

Read

API PATH: /api/v2/licenses
METHOD: GET
PARAMETERS: key – Retrieves matching records for a specific User (e.g. key=6b3f3127-a7c9-7792-449b-a0576e9cf4fc, all keys by default)
sku-id – Retrieves matching records for a Licenses with specific SKU id (e.g. user-id=1252160, all SKUs by default)
from-registration-date – Retrieves records with a registration date on or after the date given (e.g. from-date=2016-07-01)
to-registration-date – Retrieves records with a registration date before the date given (e.g. to-date=2016-07-01)
offset – Retrieves matching records after an offset value (e.g. offset=2, zero offset by default)
limit – Retrieves a number of records per page specified by the value (e.g. limit=10, all records by default)
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=key – Sort records by their key field in ascending order
sort=-key – Sort records by their key field in descending order
sort=registration-date – Sort records by their registrationDate field in ascending order
sort=-registration-date – Sort records by their registrationDate field in descending order
QUERY STRING EXAMPLES: Get the License with the specified id: api/v2/licenses/4
Get multiple Licenses by concatenating their ids : /2+3
Get all Licenses of the current Account that were registered on or after 2016-09-05 and before 2016-09-06 : ?from-registration-date=2016-09-05&to-registration-date=2016-09-06
Get two Licenses of the current Account with an offset of 1 : ?offset=1&limit=2
Get all Licenses of the current Account sorted by names alphabetically: ?sort=key
EXAMPLE RESPONSE:
[
  {
    "key": "6b3f3127-a7c9-7792-449b-a0576e9cf4fc",
    "type": "HOS",
    "duration": "P1Y6M1D",
    "registrationDate": "2018-06-11",
    "status": "UNASSIGNED",
    "skuId": 1,
    "accountId": 1248457,
    "id": 4,
    "lastChangedDate": "2018-06-11T12:00:00.000Z"
  }
]

Create

API PATH: /api/v2/licenses
METHOD: POST
EXAMPLE REQUEST:
[
  {
    "key": "6b3f3127-a7c9-7792-449b-a0576e9cf4fc",
    "type": "HOS",
    "duration": "P1Y6M1D"
  }
]
EXAMPLE RESPONSE:
[
  {
    "key": "6b3f3127-a7c9-7792-449b-a0576e9cf4fc",
    "type": "HOS",
    "duration": "P1Y6M1D",
    "registrationDate": "2018-06-11",
    "status": "UNASSIGNED",
    "accountId": 1248457,
    "id": 4,
    "lastChangedDate": "2018-06-11T12:00:00.000Z"
  }
]

Move to a sub-account

API PATH: /api/v2/licenses/move
METHOD: PUT
DESCRIPTION: Moves a specific lLicense to a sub-account under the current Account.
EXAMPLE REQUEST:
[
  { 
    "key" : "6b3f3127-a7c9-7792-449b-a0576e9cf4fc", 
    "targetAccountId" : 1248458
  }
]
EXAMPLE RESPONSE:
[
  { 
    "key" : "6b3f3127-a7c9-7792-449b-a0576e9cf4fc", 
    "targetAccountId" : 1248458
  }
]

Bulk move to a sub-account

API PATH: /api/v2/licenses/move/bulk
METHOD: PUT
DESCRIPTION

Moves a number of Licenses to a sub-account under the current Account given the following criteria:
  A. Only Licenses that have not yet been used to License any drivers (active or terminated) can be moved.
  B. Licenses to be moved are selected by registration date (earliest first), then by ID (ascending order)
  C. The “count” field must be less than or equal the number of Licenses from criteria A.
If the criteria fails, an error is thrown and the operation will be cancelled.

EXAMPLE REQUEST:
[
  {
    "count" : 20, 
    "targetAccountId" : 1248249 
  }
]
EXAMPLE RESPONSE:
[
  {
    "count" : 20, 
    "targetAccountId" : 1248249 
  }
]

Stats

API PATH: /api/v2/licenses/meta/counts
METHOD: GET
DESCRIPTION Displays the number of Licenses per status and the number of Licenses per SKUs
EXAMPLE RESPONSE:
[
  {
    "totals": {
      "expiredLicenses": 0,
      "inUseLicenses": 4,
      "availablePartialLicenses": 0,
      "availableFullLicenses": 6,
      "licenses": 10,
      "availableLicenses": 6
    }
  },
  {
    "totalsBySku": [
      {
        "expiredLicenses": 0,
        "inUseLicenses": 3,
        "availablePartialLicenses": 0,
        "skuId": 1,
        "availableFullLicenses": 2,
        "licenses": 5,
        "availableLicenses": 2
      },
      {
        "expiredLicenses": 0,
        "inUseLicenses": 1,
        "availablePartialLicenses": 0,
        "skuId": 2,
        "availableFullLicenses": 4,
        "licenses": 5,
        "availableLicenses": 4
      }
    ]
  }
]

API error calls

ERROR MESSAGE POSSIBLE CAUSES
Access Denied. GET method requires User Role of USERADMIN or ACCOUNTADMIN
POST and PUT methods require User Role of ACCOUNTADMIN or higher
PUT method is only allowed for /move and move/bulk
JSON read failed: <error> JSON error with the error message