Accounts

Accounts are likened to environments, in that each one has its own Assets, Users, Drivers, Terminals, etc. Accounts are not the same as Users. A single Account can have multiple Users, and depending on its roles and permissions, a User can access these environmental components. Administrative Accounts can have sub-accounts, which may themselves have Users and sub-accounts.

Fields

Tag Data Type Required Description
accountToken Character (40) Yes Unique string identifier used to login from a specific Account
activeDrivers Integer Auto Indicates the number of active Drivers (excluding system drivers) in an Account. This field only appears on the accounts/meta/tree endpoint.
administrativeUser Object No Contains information for an administrative User to be created along with the new Account. This can only be used in the POST JSON request.
allowSubAccountBranding Boolean No Indicates if the Account allows sub account branding or not.
Note: Can only be viewed and changed by Users with the PERM_IS_ACCOUNT_ADMIN permission
canCreateReseller Boolean No Indicates if the Account can create other reseller Accounts or not.
Note: Can only be viewed and changed by Hours of Service administrators
carrierInformation Object Yes Contains information for a default Carrier to be created with the new Account. This can only be used in the POST JSON request.
deactivated Boolean No Indicates if the Account has been deactivated or not. Deactivating an account will automatically deactivate its sub accounts
domainName Text No Contains an Account’s custom domain name. This is not returned on GET for Accounts that don’t have one.
features Object No Contains Features and indicates if they are available for the Account:

  • ifta –when set to true, this enables the Portal’s State Mileage Menu
  • map – when set to true, this enables the Portal’s Locations Page
  • eld – when set to true, this enables the Portal’s Hours of Service Menu
  • dvir – when set to true, this enables the Portal’s DVIR Menu
  • workOrder – when set to true, this enables the Portal’s Mobile Worker Menu in the Portal
  • complianceSupportCenter – when set to true, this means that drivers under the account can contact the compliance support agents
id Auto-incremented Long Auto Unique Identifier
isBillable Boolean No Indicates if the Account is billable or not
Note: Can only be viewed and changed by Hours of Service administrators
isGoodStanding Boolean No Indicates if the Account is in good standing or not
isReseller Boolean  No Indicates if the Account is a reseller or not
Note: Can only be viewed and changed by Hours of Service administrators or if the current User belongs to an Account that has “canCreateReseller” field set to true
name Character (225)  Yes The name of the Account.
productIds Array  Yes The ids of the Product(s) enabled in the Account.
resellableProducts Array  No The ids of the Product(s) that an Account can resell to its own sub-accounts.
skuIds Text (unlimited)  No SKU IDs for Accounts that require an SKU ID on creation.

Create (requires Account Admin role)

API PATH: /api/v2/accounts
METHOD: POST
Note: Must not contain an ID. When creating an account, a terminal with the “mainOffice” field set to true must also be created via the Terminals API
EXAMPLE REQUEST:
[
  {
    "name": "Account 1",
    "isBillable": false,
    "isReseller": true,
    "canCreateReseller": false,
    "domainName": "www.account.com",
    "allowSubAccountBranding":false,
    "productIds": [
      1247623,
      1248099,
      1247189
    ],
    "skuIds": [
      1
    ],
    "resellableProducts": [
      {
        "id": 1247623
      },
      {
        "id": 1248099
      },
      {
        "id": 1247189
      }
    ],
    "administrativeUser": {
      "email": "sub1@mtest.com",
      "firstName": "SubOne",
      "lastName": "MTEST",
      "password": "123",
      "suffix": "Jr",
      "isVerified": true
    },
    "carrierInformation":{
      "carrierName":"CARRIER",
      "carrierDotNumber":337788,
      "street":"505 Michigan Avenue",
      "city":"Chicago",
      "state":"IL",
      "country":"USA",
      "zip":"60611",
      "phoneNumber":"19954066243",
      "timezone":"CST6CDT",
      "startTimeOfDay":"00:00:00.000"
    }, 
    "features": {
      "ifta": true,
      "map": true,
      "eld": true,
      "dvir": true,
      "workOrder": true,
      "complianceSupportCenter": false
    }
  }
]
EXAMPLE RESPONSE:
[
  {
    "id": 1249104,
    "name": "Account 1",
    "accountToken":"227F2A0A12294A8DA7F847DA598E373F",
    "isGoodStanding": true,
    "deactivated": false,
    "isBillable": false,
    "isReseller": true,
    "canCreateReseller": false,
    "domainName": "www.account.com",
    "allowSubAccountBranding":false,
    "productIds": [
      1247623,
      1248099,
      1247189
    ],
    "skuIds": [
      1
    ],
    "resellableProducts": [
      {
        "id": 1247623
      },
      {
        "id": 1248099
      },
      {
        "id": 1247189
      }
    ],
    "features": {
      "ifta": true,
      "map": true,
      "eld": true,
      "dvir": true,
      "workOrder": true,
      "complianceSupportCenter": false
    }
  }
]

Read

API PATH: /api/v2/accounts
METHOD: GET
PARAMETERS name – Retrieves the matching record with the specified name (e.g. name=Account 1, all names by default)
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=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 account with the specified id: api/v2/accounts/1248430
Get all immediate sub-accounts of the current account with the name of Account 1 : ?name=Account 1
Get two immediate sub-accounts of the current account with an offset of 1 : ?offset=1&limit=2
Get all immediate sub-accounts of the current account sorted by names alphabetically: ?sort=name
EXAMPLE RESPONSE:
[
  {
    "id": 1249104,
    "name": "Account 1",
    "accountToken":"227F2A0A12294A8DA7F847DA598E373F",
    "isGoodStanding": true,
    "deactivated": false,
    "isBillable": false,
    "isReseller": true,
    "canCreateReseller": false,
    "domainName": "www.account.com",
    "allowSubAccountBranding":false,
    "productIds": [
      1247623,
      1248099,
      1247189
    ],
    "skuIds": [
      1
    ],
    "resellableProducts": [
      {
        "id": 1247623
      },
      {
        "id": 1248099
      },
      {
        "id": 1247189
      }
    ],
    "features": {
      "ifta": true,
      "map": true,
      "eld": true,
      "dvir": true,
      "workOrder": true,
      "complianceSupportCenter": false
    }
  }
]

Read Accounts Tree

API PATH: /api/v2/accounts/meta/tree
METHOD: GET
EXAMPLE RESPONSE:
[
  {
    "id": 1247744,
    "name": "Sub Account A",
    "activeDriversCount": 2,
    "activeVehiclesCount": 4,
    "deactivated": false,
    "isReseller": true,
    "subAccounts": [
      {
        "id": 1247745,
        "name": "Sub Account A-1",
        "activeDriversCount": 2,
        "activeVehiclesCount": 3,
        "deactivated": false,
        "isReseller": true,
        "subAccounts": [
          {
            "id": 1247745,
            "name": "Sub Account A-1.1",
            "activeDriversCount": 12,
            "activeVehiclesCount": 14,
            "deactivated": false,
            "isReseller": false
          }
        ]
      },
      {
        "id": 1247745,
        "name": "Sub Account A-2",
        "activeDriversCount": 8,
        "activeVehiclesCount": 10,
        "deactivated": false,
        "isReseller": true
      }
    ]
  }
]

Update (requires Account Admin role)

API PATH: /api/v2/accounts
METHOD: PUT
EXAMPLE REQUEST:
[
  {
    "id": 1249104,
    "name": "Account 1 - EDIT",
    "isGoodStanding": true,
    "deactivated": false,
    "isBillable": false,
    "isReseller": true,
    "canCreateReseller": false,
    "domainName": "www.account.com",
    "allowSubAccountBranding":false,
    "productIds": [
      1247623,
      1248099,
      1247189
    ],
    "skuIds": [
      1
    ],
    "resellableProducts": [
      {
        "id": 1247623
      },
      {
        "id": 1248099
      },
      {
        "id": 1247189
      }
    ],
    "features": {
      "ifta": true,
      "map": true,
      "eld": true,
      "dvir": true,
      "workOrder": true,
      "complianceSupportCenter": false
    }
  }
]
EXAMPLE RESPONSE:
[
  {
    "id": 1249104,
    "name": "Account 1 - EDIT",
    "accountToken":"227F2A0A12294A8DA7F847DA598E373F",
    "isGoodStanding": true,
    "deactivated": false,
    "isBillable": false,
    "isReseller": true,
    "canCreateReseller": false,
    "domainName": "www.account.com",
    "allowSubAccountBranding":false,
    "productIds": [
      1247623,
      1248099,
      1247189
    ],
    "skuIds": [
      1
    ],
    "resellableProducts": [
      {
        "id": 1247623
      },
      {
        "id": 1248099
      },
      {
        "id": 1247189
      }
    ],
    "features": {
      "ifta": true,
      "map": true,
      "eld": true,
      "dvir": true,
      "workOrder": true,
      "complianceSupportCenter": false
    }
  }
]

Delete (requires Account Admin role)

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

API error calls

ERROR MESSAGE HTTP STATUS ERROR CODE POSSIBLE CAUSES
Current account is not a reseller. 500 8000 POST error because the current account is not a reseller account.
A user with the given email address already exists 500 3100 POST error because the administrative user’s email address is already used by another user
The new account to insert should not have an id. 500 1000 POST error because the account must have a name
The new account to insert should not have an account token. 500 1000 POST error because the account must not have an account token
The new account name must not be blank. 500 7000 POST error because the account name must not be blank
The new account must have a carrier information 500 7000 POST error because the new account must have a carrier information
Access Denied. User is not authorized for this request. 403 8000 POST and PUT methods require permission of PERM_IS_ACCOUNT_ADMIN or higher
Account already exists with this name. 500 1001 POST or PUT error because account name is already used by another account.
A <domain.name> domain name already exists 500 1004 POST or PUT error because domain name is already used by another account.
<domain.name> is not a valid domain. 500 1000 POST or PUT error because domain name is not a valid domain name.
One resellable product is required. 500 1005 POST or PUT error because account must have one resellable product
Only one resellable product is required. 500 6000 POST or PUT error because account is limited to only one resellable product
Only one product module allowed per account 500 6000 POST or PUT error because account is limited to one product module
<module> is NOT resellable by the parent account 500 1300 POST or PUT error because module cannot be resold by the parent account
User does not have permission to edit or delete this account 403 8000 PUT or DELETE error because user cannot delete the specified account
User does not have DELETE role 403 8000 DELETE error because user role does not allow it to delete an account
DELETE on own account is not allowed 403 8000 DELETE error because own account cannot be deleted
<METHOD> is not supported. 500 12000 POST, PUT and DELETE methods are not allowed for /meta/tree