Use Cases

Below are some common integration use cases that can be implemented via the API. Each use case below gives an overview of the API calls that can be used to support that use case.

Retrieve tolls transactions for a given date range for reporting purposes

Clients often have a need to load toll transaction data into their own internal reporting systems to feed that data into custom reports based on specific business needs. This could mean loading the data into a data warehouse or data lake, a database server, Power BI, etc.

This typically starts from a requirement of something along the lines of "I need all toll data between dates X and Y".

There are a few things to be aware of as you start to pull transaction data:

There are two dates that go along with any toll transaction, the post date and the transaction date, these are included in the GET /transactions response as the following:
- tollPostDate - when Bestpass received the toll from the toll provider. The post date will correlate with the monthly statement this toll is applied to for billing purposes.
- exitDate - when the toll actually happened, sometimes also referred to as the transaction date.
When do tolls get posted to Bestpass?
- A toll's post date is typically 24-48 hours after it happens as there is a delay from when the toll occurs to when the provider processes it and sends the information to Bestpass.
- In some cases (e.g. video toll, violations) this can take a longer period. In the worst case it could be weeks before Bestpass receives the toll and it is posted to the account. However, in most cases you should see charges within 24-48 hours.
For historical data, you can pull transactions by either the transaction date or the post date depending on your needs.
Example: Let's say we want to retrieve all toll posted between the two-month period from 2024-09-01 and 2024-10-31.
- We'll be exclusively using the GET /transactions API for this scenario
- A few caveats to be aware of with the GET /transactions API:
  - The date range has a maximum of 31 days in a single request, so we need to pull one month at a time.
  - Within a single date range request data will be paginated based on pageNumber / pageSize. You may need multiple requests to pull the full dataset.
  - The date ranges accept an ISO 8601 formatted date time.
    - If no timestamp is provided, the API will default to midnight for the given date.
    - If no time zone is provided, the API will default to UTC.
      - If you are comparing results against the Bestpass User Portal (https://go.bestpass.com), be aware that the User Portal defaults to EST.
- API Requests for this example, pulling in pages of size 10,000 (the max allowed by the transactions API):
  - GET https://api.bestpass.com/fleet-api/v1/transactions?startDate=2024-09-01&endDate=2024-10-01&pageSize=10000&pageNumber=1
    - This gets the first page of data for September 2024
    - If response pagingInfo.nextPage is not null that indicates additional pages of data are available. These should be retrieved via subsequent requests until all data in that date range has been retrieved at which point pagingInfo.nextPage will be null. Additionally, you can inspect the pagingInfo.totalRecords element to determine how many total pages are available.
  - GET https://api.bestpass.com/fleet-api/v1/transactions?startDate=2024-09-01&endDate=2024-10-01&pageSize=10000&pageNumber=2
    - Get gets the second page of data for September 2024. For this example, assume this is the last page.
  - GET https://api.bestpass.com/fleet-api/v1/transactions?startDate=2024-10-01&endDate=2024-11-01&pageSize=10000&pageNumber=1
    - This gets the first page of data for October 2024. For this example, assume we only have one page.
  - We're done -- all data for the desired date range has been retrieved.

Synchronize toll transactions into your accounting system as they become available

Clients may want to pull all toll transactions into their own accounting system as they become available in Bestpass. This typically will start with an up-front sync of data following the same process described above in the "Retrieve tolls transactions for a given date range" section. Once the historical data has been loaded into the system, the client can then poll for new data as it becomes available.

Oftentimes, a nightly sync of transaction data is sufficient, but this can be done on a more frequent interval if desired (e.g. hourly). In most cases, transactions are sent to Bestpass by the toll providers in batches on some schedule, so more frequent polling typically won't get you the data any faster.

Example, we want to pull all transactions into the system as they become available via a nightly process.
- We'll be exclusively using the GET /transactions API for this scenario
- API Requests for this example, pulling in pages of size 10,000 (the max allowed by the transactions API). Assume starting from today being 2025-01-10:
  - GET https://api.bestpass.com/fleet-api/v1/transactions?startDate=2025-01-09&endDate=2024-01-10&pageSize=10000&pageNumber=1
    - Since we are synching nightly, when the job runs on 2025-01-10 we want to pull all transactions for the prior day, 2025-01-09.
    - We are searching by toll post date. If on 2025-01-10 we pull all toll posted on 2025-01-09 there is no chance we miss data or data is added to that data set in the future. Note that tolls posted on 2025-01-09 may have been incurred (have an exitDate) any time prior to that date.
    - Repeat to pull all available pages for that date range as necessary via the context provided in the pagingInfo response element.
  - GET https://api.bestpass.com/fleet-api/v1/transactions?startDate=2025-01-10&endDate=2024-01-11&pageSize=10000&pageNumber=1
    - Repeat the process the following night: 2025-01-11 we pull transactions for 2025-01-10.
  - Continue indefinitely as long as you need to keep transactions in sync. Note that if the nightly process fails for some reason (e.g. a network timeout), you will want to retry. If the failure continues you may need the next iteration on the job to pick up multiple days of transactions via adjusting the date range in the requests.

Rebill toll transactions to your customers based on what driver/vehicle incurred the toll charge

In this case, you want to find out which vehicle incurred the toll so you can bill that back to your own clients or otherwise distribute the billing to the appropriate department.

Typically, you would start with an implementation of the "Retrieve tolls transactions for a given date range" or "Synchronize toll transactions" to get the toll data you need to rebill. This scenario utilizes the GET /transactions API. Once you've retrieved the data, for each toll transaction you can inspect the following fields depending on your specific requirements.

costCenter - which cost center this toll was applied to within Bestpass. Cost centers are customer defined logical groupings of devices and vehicles.
unit - the vehicle unit number
licensePlate - the vehicle license plate
licenseState - the vehicle license plate state or province
deviceNumber - the transponder device number if this was a transponder toll
chargeAmount - the toll charge amount
discountedAmount - the discounted toll charge amount, if the toll was discounted. Note that the discounted amount may change at any point up until the toll has been applied to a monthly billing statement (since discount rates may vary based on overall volume that month for a specific toll provider.
statementNumber - the statement number this toll was applied to. If this is non-null the toll has been applied to a statement and the discountedAmount is final.

You may also be interested in some of the other fields on the response that give additional information on the toll provider and the location that the toll was incurred. See the full GET /transactions API documentation for details.

Identify toll transactions that are being charged to transponders that are not properly linked to a vehicle

When retrieving toll via the GET /transactions API, you may in some cases see a toll with a deviceNumber but no corresponding vehicle information on the record (e.g unit, licensePlate, licenseState are null).

This means there was a transponder read but that transponder was not assigned to any vehicle in Bestpass at the time of the toll. Should you run into this, you should review your transponder to vehicle assignments to establish a link to ensure these fields are populated going forward. Once you have identified which vehicle that transponder is actually assigned to, you can use the equipment assignment API to link the transponder to the vehicle within Bestpass.

You can do this via the POST /equipment/{equipmentNumber}/assign API.

Synchronize changes to your vehicle fleet

Keeping your Bestpass account in sync with your actual vehicle fleet is critical for accurate toll billing, proper transponder assignments, and violation management. This section covers how to add new vehicles, update existing ones, deactivate vehicles, and manage transponder assignments.

Recommended Synchronization Workflow

[Optional] Synchronize costs centers on your account (Refer to "Manage the cost centers on your account" section for this flow)
Retrieve your current fleet from Bestpass
Deactivate vehicles from Bestpass that are no longer in your fleet / no longer require toll coverage.
Update existing Bestpass vehicles (e.g. a vehicle's cost center changed, a transponder was added/removed)
Add new vehicles to Bestpass, assign transponders (as necessary)

Common Errors and How to Handle Them

400 Bad Request

This error generally indicates a problem with the data that was provided in the request.

Resolution: Depends on the context. Refer to the error message in the response for more information.

404 Not Found

Indicates the resource that was requested (e.g. vehicle) could not be found in the system.

Resolution: If occurred during vehicle update, perform vehicle lookup including inactive vehicles to determine if vehicle needs to be reactivated or added to Bestpass. If you receive this error on vehicle deletion, no further action is necessary, the vehicle is not active with Bestpass.

409 Conflict

The vehicle couldn't be added because at least one of these errors occurred:

The unit already exists on your account
The license plate already exists on your account
Another Bestpass customer has the license plate active on their account.

Resolution: Double check the unit number and license plate against what should be active on your account. If you are swapping a unit or plate between vehicles, make sure to deactivate the plate/unit first before assigning it to the new vehicle. If you receive the error `License Plate already exists on another account` you must contact Bestpass Customer Support to resolve the conflict if you're certain you should have the plate active on your account.

Manage the cost centers on your account

Cost centers in Bestpass allow you to organize vehicles (and their associated toll transactions) into logical groupings defined by your organization — such as by region, division, terminal, or business unit. Every account comes with a default cost center. Vehicles not explicitly assigned to a cost center will fall under this default. Each vehicle can only belong to one cost center at a time.

When toll transactions are retrieved via the /transactions endpoint, the cost center name associated with the vehicle at the time of the toll is included in the response.

Before You Begin Using the API

Most companies already have cost center structures in place. Review the following before you start making requests to the API:

Cost center naming conventions:
- Must be unique within your account
- No longer than 50 characters. Ensure your existing naming convention fits within this constraint.
A vehicle can only belong to a single cost center. If your internal structure requires a vehicle to be tagged to multiple departments, you'll need to choose a primary assignment.
Default cost center: Every account has one. You don't need to create it, it already exists. Any vehicle without an explicit cost center assignment will land here.

Recommended Cost Center Workflow

It is important to keep your cost center data in-sync with Bestpass. If you rarely update cost centers, consider a monthly or quarterly audit of active cost centers with Bestpass. If you update frequently, you may need to update your cost centers more frequently with Bestpass in order to assign vehicles to newly created cost centers. We suggest choosing one of two different approaches:

Manage your cost centers before attempting vehicle create / update requests. This will help avoid error responses.
React to cost center related error responses during vehicle creation/update. Inspect errors during vehicle creation, looking for error message "Cost center does not exist"; create the cost center and then attempt to re-add or update the vehicle again.

Keeping Cost Centers Updated - Example Workflow

Follow this workflow to ensure we have the most accurate cost center information before adding or updating your vehicles:

Audit your existing cost centers by pulling the current cost center list. Review the list, looking for stale or unused cost centers that should be deactivated, any missing cost centers that need to be created.
Create new cost centers as needed.
Deactivate cost centers that are no longer needed.
NOTE: You cannot deactivate a cost center that still has vehicles assigned to it. Move those vehicles to another cost center first, then deactivate the cost center.
Reactivate previously deactivated cost centers if needed. If a cost center is not active but is needed again, send an update request and set `inactivateDate` to `null`.

Common Exceptions and How to Handle Them

409 Conflict on Create

This is caused by attempting to create a cost center with a name that is already in use, it may be inactive.

Resolution: Look up the cost center via `GET /cost-centers?activeOnly=false`. If it is inactive, reactivate by setting `inactiveDate` to false via the PUT request.

400 Bad Request on Deactivation

This is most likely caused by vehicles still being assigned to the cost center.

Resolution: Reassign vehicles to a different cost center first, then retry cost center deactivation update.

404 Not Found on Lookup / Update

The cost center name does not match any existing record.

Resolution: Review all cost centers on your account via `GET /cost-centers`. If not found in this list, it does not currently exist on your account.

Retrieve detailed statement transactions (from toll customer billing statements) for a specific Statement and Charge Item

Clients may need to collect and separate detailed, charged transactions within their customer statement [from Fleetworthy Tolling / Bestpass] obtaining a detailed itemization of transactions under Statement Charges, e.g. “Violation Avoidance Program”.

The basic process is

Identify the target statement’s number (known or using API)
Pass in the statement number and charge ID to the API
Receive back a full list of transactions under that line charge

Step 1 — Get the list of Statements to find the desired Statement Number

Note: If you already know the Statement Number, you may skip this step.

GET https://api.bestpass.com/fleet-api/v1/statements

Fleet API / Get Statements Endpoint Documentation

Step 2 — Get the list of Charges for the Statement

(“23051004565” is the Statement Number in this example.)

GET https://api.bestpass.com/fleet-api/v1/statements/23051004565/charges

Fleet API / Get Charges Endpoint Documentation

A return dataset would look something like this:

{
    "statementSummary": {
        "statementNumber": "23051004565",
        "dateCreated": "2023-06-07T18:41:19.353",
        "usageCutoffDate": "2023-05-31T00:00:00",
        "statementAmount": 0.0000,
        "amountPaid": 0.0000
    },
    "charges": [{
        "statementLineItemId": 9488410,
        "itemDescription": "BESTPASS",
        "serviceOfferingId": 0,
        "suretyId": 12071,
        "total": 38137.5400,
        "lines": [{
            "chargeId": 24247398,
            "chargeDescription": "NYSTA Credit Request Adjustment",
            "quantity": 1.00,
            "rate": 2.1700,
            "total": 2.170000
        }, {
            "chargeId": 24248103,
            "chargeDescription": "AMIS Fee Adjustment",
            "quantity": 1.00,
            "rate": -0.4300,
            "total": -0.430000
        }, {
            "chargeId": 24249687,
            "chargeDescription": "Violation Avoidance Program",
            "quantity": 1.00,
            "rate": 35991.0000,
            "total": 35991.000000
        }, {
// ... TRIMMED

From this data, you may wish to find specific charge types. As mentioned above, using a chargeDescription value of “Violation Avoidance Program" we can obtain the corresponding chargeId which is 24249687 in this case.

Step 3 — Get the Itemized Transaction Details for that specific Charge on the Statement

(“23051004565” is the Statement Number and “24249687” the Charge ID in this example.)

GET https://api.bestpass.com/fleet-api/v1/statements/23051004565/charges/24249687

Fleet API / Get Charge Details Endpoint Documentation

This returns the full set of transaction included in the identified Charge. The transaction dataset mirrors format of the Transactions API.

{
    "chargeItemizationType": "Transaction",
    "transactions": {
        "transactionCount": 35991,
        "transactions": [{
            "transactionId": 813213902,
            "tollPostDate": "2023-05-01T05:43:17.437+00:00",
            "chargeAmount": 2.00,
            "feeAmount": 0.00,
            "deviceNumber": "GPJR04-FL",
            "unit": "4555584",
            "transactionType": "Toll",
            "entryDate": null,
            "entryPlazaCode": "-",
            "entryPlazaName": "None",
            "entryLane": null,
            "exitDate": "2023-04-25T14:43:40+00:00",
            "exitPlazaCode": "000002",
            "exitPlazaName": "CAPE CORAL",
            "exitLane": "001",
            "licensePlate": "GPJR04",
            "licenseState": "FL",
            "transactionClass": "3",
            "miles": 0,
            "agency": "LCF",
            "prePaid": true,
            "serviceName": "E-ZPass Prepaid",
            "discounted": false,
            "discountedAmount": 2.00,
            "costCenter": "014",
            "transactionDescription": "Plate Toll",
            "statementNumber": "23051004565",
            "location": {
                "latitude": 26.558353,
                "longitude": -81.921193
            }
        },
    // ... TRIMMED