Getting Started
Authorization header of every request.
Welcome to the RoadBays API. To get started, sign into your account, navigate to Company Settings → API, and generate your API key.
Include your key as a Bearer token on every request:
curl --location --request GET 'https://www.roadbays.com/api/v1_Cases' \
--header 'Authorization: Bearer YOUR_API_KEY_HERE'
List Cases
Retrieve a list of cases filtered by date range using the case open date.
curl --location --request GET \
'https://www.roadbays.com/api/v1_Cases?startdate=10-1-2021&enddate=10-4-2021' \
--header 'Authorization: Bearer YOUR_API_KEY'
[
{
"id": 408500,
"dateCreated": "2021-10-03T09:07:13.84",
"inactive": 0,
"accountGUID": "b5b1032a-6336-4d51-c1z3-bad295795192",
"dateOpened": "2021-10-03T09:07:13.84",
"dateCompleted": "2021-10-03T09:09:56.12",
"dateClosed": "2021-10-03T09:09:56.12",
"assignedUser": 81,
"vendors": {
"id": 10464,
"name": "Shop Location 1",
"address": "1234 Main Ave",
"city": "Green Bay",
"zip": "54304",
"email": "test@email.com",
"phone": "92012345687",
"latitude": 47.254547,
"longitude": -67.9403301,
"vendorType": "CustomerShop",
"ranking": 6
},
"vendorsId": 10464,
"caseNumber": 8,
"caseStatus": { "id": 3, "name": "Closed" },
"caseStatusId": 3,
"description": "Test Header",
"units": {
"id": 1030,
"unitNumber": "3345",
"description": "Mack Truck",
"unitTypesId": 1014,
"serialNo": "1XPBDP956AD486131",
"engine": "MP8",
"engineManufacturer": "MACK",
"unitMake": "MACK",
"unitModel": "Anthem",
"modelYear": "2020",
"unitSearchLabel": "3345 Tractor"
},
"unitsId": 1030,
"repairReasonsId": 12,
"priority": { "id": 5, "value": "5" },
"priorityId": 5,
"maintenanceBoard": 1
}
]
| Parameter | Type | Description |
|---|---|---|
| Authorization | string | Bearer token API key required |
| startdate | DateTime | Start date filter by case open date required |
| enddate | DateTime | End date filter by case open date required |
Get Case
Retrieve full details for a single case by its RoadBays system-generated ID.
curl --location --request GET \
'https://www.roadbays.com/api/v1_Cases/408500' \
--header 'Authorization: Bearer YOUR_API_KEY'
{
"id": 408500,
"dateCreated": "2021-10-03T09:07:13.84",
"inactive": 0,
"accountGUID": "b5b1032a-6336-4d51-c1z3-bad295795192",
"dateOpened": "2021-10-03T09:07:13.84",
"dateCompleted": "2021-10-03T09:09:56.12",
"dateClosed": "2021-10-03T09:09:56.12",
"assignedUser": 81,
"vendors": null,
"vendorsId": 10464,
"caseNumber": 8,
"driverId": null,
"caseStatus": null,
"caseStatusId": 3,
"description": "This is a case description",
"locationDescription": null,
"units": null,
"unitsId": 100030,
"repairReasonsId": 12,
"offSet": "-05:00",
"latitude": null,
"longitude": null,
"priority": null,
"priorityId": 5,
"maintenanceBoard": 1
}
| Parameter | Type | Description |
|---|---|---|
| Authorization | string | Bearer token API key required |
| caseId | integer | RoadBays system-generated case ID required |
Create Case by VIN
Create a new maintenance case linked to an asset by VIN. The asset must already exist in your RoadBays account.
curl --location --request POST \
'https://www.roadbays.com/api/v1_Cases' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'vin=1XPCEP6Y0JD486131' \
--data-urlencode 'description=Case Description' \
--data-urlencode 'assignedUser=81' \
--data-urlencode 'locDescription=located in NE corner of lot' \
--data-urlencode 'latitude=44.503807048107156' \
--data-urlencode 'longitude=-88.0080488474994' \
--data-urlencode 'userField1=custom field data 1' \
--data-urlencode 'userField2=custom field data 2'
{
"id": 4102,
"dateCreated": "2021-10-24T20:40:44.428835-05:00",
"inactive": 0,
"accountGUID": "b5b1032a-6336-4d51-c1z3-bad295795192",
"dateOpened": "2021-10-24T20:40:44.428835-05:00",
"dateCompleted": null,
"dateClosed": null,
"assignedUser": 81,
"vendors": null,
"vendorsId": null,
"caseNumber": 39,
"driverId": null,
"caseStatus": null,
"caseStatusId": 1,
"description": "Case Description",
"units": null,
"unitsId": 1030,
"repairReasonsId": null,
"offSet": "-05:00",
"latitude": null,
"longitude": null,
"priority": null,
"priorityId": 5,
"maintenanceBoard": 1
}
Create Case Note
Append a text note to an existing case. Notes appear in the case communication feed visible to all assigned parties.
curl --location --request POST \
'https://www.roadbays.com/api/v1_CaseNotes' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'caseId=4102' \
--data-urlencode 'noteText=Hello World'
| Parameter | Type | Description |
|---|---|---|
| Authorization | string | Bearer token API key required |
| caseId | integer | RoadBays system-generated case ID required |
| noteText | string | Text to append to the case note feed required |
Case Notification
Send a notification for a case via Email or SMS. Set NotificationTypesId to 2 for Email or 3 for SMS.
curl --location --request POST \
'https://www.roadbays.com/api/v1CaseNotifications' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'CaseId=4102' \
--data-urlencode 'NotificationTypesId=3' \
--data-urlencode 'NotificationContact=9207640865' \
--data-urlencode 'CaseHeader=True' \
--data-urlencode 'CaseNotes=True'
| Parameter | Type | Description |
|---|---|---|
| Authorization | string | Bearer token API key required |
| CaseId | integer | RoadBays system-generated case ID required |
| NotificationTypesId | integer | Email = 2 · SMS = 3 required |
| NotificationContact | string | Email address or phone number required |
| CaseHeader | bool | Notify on case header changes required |
| CaseNotes | bool | Notify on new case notes required |
List Invoices
Retrieve a list of invoices filtered by date range using the invoice open date.
curl --location --request GET \
'https://www.roadbays.com/api/v1_Invoices?startdate=10-1-2021&enddate=10-4-2021' \
--header 'Authorization: Bearer YOUR_API_KEY'
| Parameter | Type | Description |
|---|---|---|
| Authorization | string | Bearer token API key required |
| startdate | DateTime | Start date filter by invoice open date required |
| enddate | DateTime | End date filter by invoice open date required |
Get Invoice
Retrieve full details for a single invoice by its RoadBays system-generated ID.
curl --location --request GET \
'https://www.roadbays.com/api/v1_Invoices/408500' \
--header 'Authorization: Bearer YOUR_API_KEY'
| Parameter | Type | Description |
|---|---|---|
| Authorization | string | Bearer token API key required |
| invoiceId | integer | RoadBays system-generated invoice ID required |
Create Invoice by VIN
Create a new invoice linked to an asset by VIN and an existing case number.
curl --location --request POST \
'https://www.roadbays.com/api/v1_Invoices' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'vin=1XPCEP6Y0JD486131' \
--data-urlencode 'description=Invoice Description' \
--data-urlencode 'caseNumber=44' \
--data-urlencode 'locDescription=located in NE corner of lot'
| Parameter | Type | Description |
|---|---|---|
| Authorization | string | Bearer token API key required |
| vin | string | VIN of an existing unit in RoadBays required |
| caseNumber | integer | RoadBays system-generated case number required |
| description | string | Invoice description required |
| locDescription | string | Location description optional |
Get Invoice Payments
Retrieve payment records associated with a specific invoice.
curl --location --request GET \
'https://www.roadbays.com/api/v1_InvoicePayments/3157' \
--header 'Authorization: Bearer YOUR_API_KEY'
| Parameter | Type | Description |
|---|---|---|
| Authorization | string | Bearer token API key required |
| invoiceId | integer | RoadBays system-generated invoice ID required |
List Repair Reasons
Returns all repair reasons configured for your account. Use the returned id values when creating cases.
curl --location --request GET \
'https://www.roadbays.com/api/v1_RepairReasons' \
--header 'Authorization: Bearer YOUR_API_KEY'
| Parameter | Type | Description |
|---|---|---|
| Authorization | string | Bearer token API key required |
List Users
Returns all users registered to your account. Use the returned id as the assignedUser value when creating cases.
curl --location --request GET \
'https://www.roadbays.com/api/v1_CustomerUsers' \
--header 'Authorization: Bearer YOUR_API_KEY'
| Parameter | Type | Description |
|---|---|---|
| Authorization | string | Bearer token API key required |
List Drivers
Returns all drivers registered to your account.
curl --location --request GET \
'https://www.roadbays.com/api/v1_Drivers' \
--header 'Authorization: Bearer YOUR_API_KEY'
| Parameter | Type | Description |
|---|---|---|
| Authorization | string | Bearer token API key required |
Create Driver
Register a new driver to your RoadBays account. First name, last name, and email are required.
curl --location --request POST \
'https://www.roadbays.com/api/v1_Drivers' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'firstName=Demo' \
--data-urlencode 'lastName=User' \
--data-urlencode 'email=demo@roadbays.com' \
--data-urlencode 'phone=9203141144' \
--data-urlencode 'employeeId=1111111' \
--data-urlencode 'balance=1000'
| Parameter | Type | Description |
|---|---|---|
| Authorization | string | Bearer token API key required |
| firstName | string | Driver first name required |
| lastName | string | Driver last name required |
| string | Driver email address required | |
| phone | string | Phone number optional |
| employeeId | string | Internal employee identifier optional |
| balance | string | Account balance optional |
List Units
Returns all fleet assets (units) registered to your account.
curl --location --request GET \
'https://www.roadbays.com/api/v1_Units' \
--header 'Authorization: Bearer YOUR_API_KEY'
| Parameter | Type | Description |
|---|---|---|
| Authorization | string | Bearer token API key required |
Get Unit
Retrieve full details for a single unit by its RoadBays system-generated ID.
curl --location --request GET \
'https://www.roadbays.com/api/v1_Units/1030' \
--header 'Authorization: Bearer YOUR_API_KEY'
| Parameter | Type | Description |
|---|---|---|
| Authorization | string | Bearer token API key required |
| unitId | integer | RoadBays system-generated unit ID required |
Create Unit
Add a new fleet asset to your account. Vehicle specs are automatically decoded from the VIN via NHTSA.
curl --location --request POST \
'https://www.roadbays.com/api/v1_Units' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'vin=1XPCEP6Y0JD486131' \
--data-urlencode 'unitNumber=12345' \
--data-urlencode 'unitTypeId=1001' \
--data-urlencode 'license=1XY23Z45'
| Parameter | Type | Description |
|---|---|---|
| Authorization | string | Bearer token API key required |
| vin | string | 17-character vehicle VIN required |
| unitTypeId | integer | RoadBays unit type ID required |
| unitNumber | string | Your internal unit/fleet number required |
| license | string | License plate number optional |
Create Fault Code
Push DTC fault codes into RoadBays from your telematics provider. Codes are matched to the asset by VIN and linked to open cases automatically.
curl --location --request POST \
'https://www.roadbays.com/api/v1_FaultCodes' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'vin=1XPCEP6Y0JD486131' \
--data-urlencode 'code=P1401' \
--data-urlencode 'codeDescription=Crankcase Air Pressure' \
--data-urlencode 'status=open' \
--data-urlencode 'source=Crankcase' \
--data-urlencode 'platform=api' \
--data-urlencode 'externalId=367423'
| Parameter | Type | Description |
|---|---|---|
| Authorization | string | Bearer token API key required |
| vin | string | VIN of the unit in RoadBays required |
| code | string | DTC fault code (e.g. P1401) required |
| codeDescription | string | Human-readable description of the code optional |
| platform | string | Label of originating platform (e.g. Samsara) optional |
| status | string | open or closed optional |
| source | string | Source bus or system of the code optional |
| externalId | string | Your external ID — use to update status later optional |
Update Fault Code
Update the status of an existing fault code. Identify the record using either the RoadBays internal id or the externalId assigned at creation. One of the two is required.
curl --location --request PUT \
'https://www.roadbays.com/api/v1_FaultCodes' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'id=145585' \
--data-urlencode 'externalId=1455a58s45' \
--data-urlencode 'status=closed'
| Parameter | Type | Description |
|---|---|---|
| Authorization | string | Bearer token API key required |
| id | integer | RoadBays internal fault code ID — required if no externalId |
| externalId | string | Your external ID — required if no id |
| status | string | Open or Closed required |
Update Mileage
Push updated mileage for a unit by VIN. The mileage value must be greater than the current recorded value to update correctly.
curl --location --request POST \
'https://www.roadbays.com/api/v1_Mileage' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'vin=1XPCEP6Y0JD486131' \
--data-urlencode 'mileage=145585'
| Parameter | Type | Description |
|---|---|---|
| Authorization | string | Bearer token API key required |
| vin | string | VIN of the unit to update required |
| mileage | string | Must be greater than current recorded mileage required |
Error Codes
The RoadBays API uses standard HTTP status codes. Errors return a JSON body with a message field describing the issue.
| Code | Meaning |
|---|---|
| 401 | Unauthorized — Verify your Bearer token is correct and included in the Authorization header. |
| 403 | Forbidden — Your API key does not have permission to access this endpoint. |
| 404 | Not Found — The requested resource ID does not exist. Verify the ID and try again. |
| 500 | Internal Server Error — An unexpected server error occurred. Please try again later. |
| 503 | Service Unavailable — The API is temporarily offline for maintenance. Please try again later. |