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) | No | 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:
|
| 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. |
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
],
"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
],
"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
],
"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
],
"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
],
"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 |