TBN API — Developer Documentation

Overview

• Base URL: Your TBN-provided API host (e.g., https://api.thebusnetwork.com)
• API Style: REST over HTTPS, JSON request/response bodies
• OpenAPI Spec: Available at GET /docs/spec.json
• Interactive Docs: Swagger UI available at GET /docs (no authentication required)

Quick Start

1. Get Your API Key

Contact TBN to request an API key. Keys are scoped to one of three access levels:

2. Make Your First Request

curl -H "Authorization: Bearer tbn_c_your_api_key_here" \
  https://api.thebusnetwork.com/api/usage/current

The /api/usage/current endpoint is free (0 units) and is a good way to verify your key is working.

3. Explore the Data

Authentication

All /api/* endpoints require a valid API key in the Authorization header using the Bearer scheme:

Authorization: Bearer <your-api-key>

Key behavior:

• Keys are validated against bcrypt hashes on the server
• Validated keys are cached for 5 minutes to reduce latency on subsequent requests
• The lastUsedAt timestamp on your key is updated with each request

Authentication errors:

Missing or malformed header:

HTTP 401
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid Authorization header"
  }
}

Invalid key:

HTTP 401
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}

Scope & Data Access

Your API key determines what data you can access. The TBN data hierarchy is:

Enterprise
  └── Parent Company
        └── Company

Scope Narrowing

Higher-level keys can optionally narrow their scope using query parameters:

Example — Enterprise key narrowing to a specific company:

curl -H "Authorization: Bearer tbn_e_your_key" \
  "https://api.thebusnetwork.com/api/bookings?companyID=456"

Scope errors:

Invalid scope parameter (not an integer):

HTTP 400
{
  "error": {
    "code": "INVALID_PARAM",
    "message": "Invalid companyID parameter"
  }
}

Company not in your hierarchy:

HTTP 403
{
  "error": {
    "code": "FORBIDDEN",
    "message": "Company does not belong to this hierarchy"
  }
}

Request Format

Query Parameters

All list endpoints accept optional scope filters:

Some endpoints support additional filters:

Date Format

All date parameters must be in ISO 8601 format:

startDate=2026-02-01T00:00:00Z
endDate=2026-02-28T23:59:59Z

Date range rules:

• Maximum window: 31 days between startDate and endDate
• endDate must be on or after startDate
• If startDate is omitted, it defaults to the current time
• If endDate is omitted, it defaults to startDate + 24 hours

Path Parameters

Detail endpoints use a numeric id path parameter:

GET /api/bookings/{id}
GET /api/drivers/{id}

The id must be a positive integer.

Request Body

Only one endpoint accepts a request body:

POST /api/drivers/verify

{
  "email": "driver@example.com",
  "password": "their_password"
}

Both fields are required.

Response Format

Successful Responses

List endpoints return an array wrapped in a data envelope:

HTTP 200
{
  "data": [
    { "id": 1, "companyName": "Acme Transport", ... },
    { "id": 2, "companyName": "Beta Bus Co", ... }
  ]
}

If no records match, data is an empty array: { "data": [] }

Detail endpoints return a single object in a data envelope:

HTTP 200
{
  "data": {
    "id": 1,
    "companyName": "Acme Transport",
    ...
  }
}

Driver verify returns a non-enveloped response:

HTTP 200
{
  "verified": true
}

Usage Response Headers

Every successful response includes these headers:

Date Fields in Responses

Response fields use two date formats:

Some datetime fields include a separate timezone field:

{
  "firstDeparture": "2026-02-15T08:00:00Z",
  "firstDepartureTZ": "America/New_York"
}

Field Naming Conventions

Error Responses

All errors follow a consistent format:

{
  "error": {
    "code": "<ERROR_CODE>",
    "message": "<Human-readable description>"
  }
}

Error Code Reference

Handling 429 Responses

All 429 responses include a Retry-After header (in seconds) indicating when you can retry:

Rate-limited responses also include usage headers with X-TBN-Units-Consumed: 0 (the rejected request does not consume units).

Recommended retry strategy:

1. Read the Retry-After header
2. Wait at least that many seconds before retrying
3. For RATE_LIMIT_MINUTE, implement exponential backoff starting at 60 seconds
4. For HARD_LIMIT_EXCEEDED or ALLOCATION_EXCEEDED, stop making requests and contact TBN if you need a plan upgrade

Usage & Metering

How Units Work

Every API call consumes units from your plan's allocation. The cost of each call depends on:

• Endpoint weight — Each endpoint has a configured base unit cost
• Scope level — List endpoints called with parent company or enterprise keys cost base weight × number of active companies in scope. Detail endpoints (by ID) always cost the base weight regardless of scope.
• Zero-cost endpoints — The /api/usage/current endpoint costs 0 units

Rate Limits

Your plan defines limits across multiple time windows:

Monitoring Your Usage

Check your current consumption at any time (free, 0 units):

curl -H "Authorization: Bearer tbn_c_your_key" \
  https://api.thebusnetwork.com/api/usage/current

You can also read the X-TBN-* response headers on any API call to monitor usage inline.

Endpoint Reference

All data endpoints are mounted under /api and require authentication.

System

Reference Data

Global lookup tables. Not scoped — the same data is returned regardless of your key level.

Bookings

Key fields: id, bookingFormattedID, bookedQuoteID, primaryContactID, primaryContactName, organizationID, organizationName, bookingCategory, documentType, salesPerson, tripDescription, numPassengers, firstDeparture, firstDepartureTZ, totalBeforeTax, totalTax, totalAfterTax, amountPaid, amountOutstanding, depositAmount, depositDue, isCancelled, cancelledAt, companyID, companyName, parentCompanyID, parentCompanyName, enterpriseID, enterpriseName, createdAt, updatedAt

Quotes

Key fields: id, formattedQuoteID, contactID, contactName, operationsContactID, operationsContactName, billingContactID, billingContactName, quoteStatus, documentType, source, quoteChannel, customerStatus, bookingCategory, salesPerson, startYardID, startYardName, returnYardID, returnYardName, firstDeparture, firstDepartureTZ, firstPickUpLocation, destination, numTripDays, passengers, charterDescription, tripReference, groupName, routeDescription, priceOverride, expirationDate, dateSubmitted, createdAt, updatedAt

Quote Segments

Vehicle Requests

Addon Requests

Discount Code Quotes

Routes (Vehicle Assignments)

Route Segments

Addon Assignments

Discount Code Routes

Dispatch

Key fields: id, driverStartTime, routeID, driverID, driverName, vehicleTypeName, vehicleInventoryName, driverStatusName, affiliateID, useAffiliate, affiliateRate, customerNotes, driverInstructions, invoiceNotes, price, suggestedPrice, priceAtBooking, salesTax, driverCheckIn, driverCheckOut, driverAcceptedAt, publishedAt, cancelledAt, hideFromCustomer, hideFromInvoice, isReliefAssignment, createdAt, updatedAt

Drivers

Key fields: id, fullName, firstName, lastName, email, mobilePhone, homePhone, employmentStatusID, employmentStatus, driverReferenceID, dob, dateEmploymentStart, dateEmploymentEnd, licenseNumber, dateLicenseExpired, available, suspended, primaryLocation, companyID, companyName, createdAt, updatedAt

Driver Absence Events

Driver Availability Events

Driver Actuals

Incidents

Other Assignments

Invoices

Key fields: id, invoiceNumber, contactID, contactName, organizationID, organizationName, bookingID, bookingFormattedID, scheduledServiceID, scheduledServiceDescription, paymentTerm, invoiceDeliveryMethod, invoiceFormatType, invoiceDueDate, date, description, totalBeforeTax, totalTax, totalAfterTax, totalDiscount, amountPaid, amountOutstanding, paidInFull, voidedAt, createdAt, updatedAt

Companies

Key fields: id, companyName, displayName, companyShorthandCode, companyPhone, website, addressStreet1, addressStreet2, addressCity, addressState, addressZip, parentCompanyID, parentCompanyName, enterpriseID, enterpriseName

Organizations

Contacts

Yards

Schools

School Contracts

School Routes

Key fields: id, routeName, busNumber, schoolContractID, schoolContractName, driverID, driverName, startYardID, startYardName, returnYardID, returnYardName, schoolRouteTypeID, schoolRouteType, vehicleTypeName, vehicleDisplayID, driverStartTime, departYardTime, returnYardTime, driverEndTime, sunday through saturday (booleans), additionalRouteDetails, createdAt, updatedAt

School Segments

Tour Contracts

Tour Routes

Tour Segments

Tour Vehicle Requests

Scheduled Services

Scheduled Service Routes

Scheduled Service Segments

Scheduled Service Vehicle Requests

Scheduled Service Addon Requests

Best Practices

Use Scope Narrowing for Performance

If you have an enterprise or parent company key but only need data for one company, always pass ?companyID=. List endpoints at higher scopes cost more units (base weight multiplied by your active company count).

Respect Date Range Defaults

Endpoints with date filtering default to a 24-hour window from the current time. If you need historical data, always specify both startDate and endDate. Keep ranges to 31 days or less per request.

Monitor Usage Proactively

Read the X-TBN-Period-Remaining header on responses to detect when you're approaching limits. Use /api/usage/current for a detailed breakdown without consuming units.

Handle 429s Gracefully

Always check the Retry-After header on 429 responses. Implement exponential backoff for rate limits. For allocation or hard limit errors, pause all requests until the next billing period or contact TBN for a plan upgrade.

Cache Reference Data

Reference data endpoints (/api/regions, /api/customer-types, /api/employment-statuses, etc.) return global lookup tables that change infrequently. Cache these responses on your side to reduce unnecessary API calls.

Use Detail Endpoints When You Know the ID

Detail endpoints (/api/bookings/{id}) always cost the base unit weight, regardless of your key's scope level. If you already have the record ID, prefer the detail endpoint over filtering a list.

Troubleshooting

Support

For API key requests, plan changes, or technical support, email TBN- support@tbndrives.com

For endpoint-level field documentation, use the interactive Swagger UI at /docs on your API host.