Request Parameters

The following parameters are available in the URL path and query string:

Parameter	Type	Required	Description
version	String	Yes	The API version to use.
tripNumber	String	Conditionally	The trip number to filter results. This field is required if the other conditionally required fields are left empty.
id	String	Conditionally	The trip id to filter results. This field is required if the other conditionally required fields are left empty.

Example CURL request

Example using Trip ID:

curl --location 'https://integrations.alvys.com/api/p/v{version}/trips?id={tripId}' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Example using Trip Number:

curl --location 'https://integrations.alvys.com/api/p/v{version}/trips?tripNumber={tripNumber}' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Replace {version} with the API version number, {tripId} with the actual trip ID, {tripNumber} with the actual trip number, and YOUR_ACCESS_TOKEN with your actual Bearer token:

Using Trip ID:

curl --location 'https://integrations.alvys.com/api/p/v1/trips?id=000c3a9bf0000000bf000d000e000a0b' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ...'

Using Trip Number:

curl --location 'https://integrations.alvys.com/api/p/v1/trips?tripNumber=123456789' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ....'

Response Parameters

The following table lists the parameters included in the response for a single trip request:

Parameter	Type	Required	Description
id	string	Yes	Unique identifier of the trip.
tripNumber	string	Yes	Number associated with the trip.
status	string	No	Current status of the trip.
loadNumber	string	No	Load number associated with the trip.
tenderAs	string	No	Role under which the trip was tendered.
tenderAsSubsidiaryType	string	No	Subsidiary type under which the trip was tendered (e.g., `"Carrier"`).
stops[]	array	No	List of stops for the trip.
stops[].id	string	No	Unique identifier of the stop.
stops[].address.street	string	No	Street address of the stop.
stops[].address.city	string	No	City of the stop.
stops[].address.state	string	No	State of the stop.
stops[].address.zipCode	string	No	ZIP code of the stop.
stops[].coordinates.latitude	string	No	Latitude of the stop.
stops[].coordinates.longitude	string	No	Longitude of the stop.
stops[].status	string	No	Status of the stop.
stops[].stopType	string	No	Type of stop (e.g., Pickup, Delivery).
stops[].appointmentDate	string (datetime)	No	Appointment date/time for the stop.
totalMileage.distance.value	number	No	Total mileage value.
totalMileage.distance.unitOfMeasure	string	No	Unit of measure for total mileage.
totalMileage.source	string	No	Source of mileage data.
totalMileage.profileName	string	No	Name of the mileage profile used.
emptyMileage.distance.value	number	No	Empty mileage value.
loadedMileage.distance.value	number	No	Loaded mileage value.
pickupDate	string (datetime)	No	Scheduled pickup date.
deliveryDate	string (datetime)	No	Scheduled delivery date.
pickedUpAt	string (datetime)	No	Actual pickup timestamp.
deliveredAt	string (datetime)	No	Actual delivery timestamp.
carrierAssignedAt	string (datetime)	No	Carrier assignment timestamp.
tripValue.amount	number	No	Total trip value.
tripValue.currency	string	No	Currency for trip value.
truck.id	string	No	Truck ID.
truck.fleet.id	string	No	Fleet ID of the truck.
truck.fleet.name	string	No	Fleet name of the truck.
trailer.id	string	No	Trailer ID.
trailer.equipmentType	string	No	Equipment type of trailer.
temperature	object	No	Temperature requirements for temperature-controlled trips. Returned only when configured; otherwise omitted from the response.
temperature.setpointTemperature	number	No	Required target temperature.
temperature.setpointTemperatureMax	number	No	Optional maximum temperature when a temperature range is defined.
temperature.controlMode	string	No	Operational mode of the trailer (`Continuous`, `Start/Stop`).
requiredEquipment[]	array of strings	No	List of equipment types required for the trip (e.g., `Reefer`, `Van`, `Flatbed`). Returned only when configured; omitted when no requirement exists.
driver1.id	string	No	Unique ID of Driver 1.
driver1.contractorType	string	No	Contractor type of Driver 1.
driver1.rates[]	array	No	Legacy field. Old driver rate objects. Returned for backward compatibility and may be empty or outdated.
driver1.ratesV2[]	array	No	New structured rate objects for Driver 1 showing applied pay rules and calculated line items.
driver1.ratesV2[].policyId	string	No	Unique identifier of the applied rate policy.
driver1.ratesV2[].policyName	string	No	Display name of the rate policy.
driver1.ratesV2[].perTripRate.rate	number	No	Flat per-trip pay rate applied to the trip.
driver1.ratesV2[].perTripRate.rateId	string	No	Identifier of the per-trip rate type.
driver1.ratesV2[].perTripRate.rateName	string	No	Name of the per-trip rate type.
driver1.ratesV2[].perTripRate.lineItems[]	array	No	Detailed line-item breakdown for per-trip rate.
driver1.ratesV2[].tripValuePercentageRate.percentage	number	No	Percentage of trip value used to calculate pay.
driver1.ratesV2[].tripValuePercentageRate.rateId	string	No	Identifier of the percentage-based rate type.
driver1.ratesV2[].tripValuePercentageRate.rateName	string	No	Name of the percentage-based rate.
driver1.ratesV2[].tripValuePercentageRate.lineItems[]	array	No	Line-item breakdown for percentage-based rate (description, amount, currency).
driver2.id	string	No	Unique ID of Driver 2.
driver2.contractorType	string	No	Contractor type of Driver 2.
driver2.rates[]	array	No	Legacy rate list for Driver 2 — may be empty or outdated.
driver2.ratesV2[]	array	No	Structured rate objects for Driver 2.
ownerOperator.id	string	No	Unique ID of the owner-operator.
ownerOperator.rates[]	array	No	Legacy rate list for Owner Operator — may be empty or outdated.
ownerOperator.ratesV2[]	array	No	Structured rate objects for Owner Operator.
carrier.id	string	No	Carrier ID.
carrier.rate.amount	number	No	Carrier rate amount.
carrier.rate.currency	string	No	Carrier rate currency.
carrier.linehaul.amount	number	No	Carrier linehaul amount.
carrier.linehaul.currency	string	No	Currency of linehaul.
carrier.totalPayable.amount	number	No	Total payable amount to the carrier.
carrier.totalPayable.currency	string	No	Currency for total payable amount.
dispatchedBy	string	No	User who dispatched the trip.
dispatcherId	string	No	ID of the dispatcher.
updatedAt	string (datetime)	No	Timestamp when the trip was last updated.
updatedBy	string	No	User who last updated the trip.

⚠️ Important Note on `Rates` and `RatesV2` Fields

Both the legacy Rates[] and the new RatesV2[] fields are currently returned in the Trips API response under driver1, driver2, and ownerOperator.

The legacy Rates[] field remains available for backward compatibility but is no longer populated for new trips created after migration to Driver Settlement.
For trips that existed prior to migration, Rates[] may still contain historical data; however, it can be out of sync with RatesV2[] if additional rate changes were made after migration.
Integrations that continue to read data from Rates[] may receive empty or outdated arrays.
To ensure accurate and complete pay information, integrations should rely on RatesV2[] going forward.

Each rate type (e.g., tripValuePercentageRate, perTripRate, minimumPayRate) within RatesV2[] is returned as a structured object with optional lineItems[] breakdowns.

Versioning

The version parameter in the URL path specifies which version of the API you are using. Including the version number ensures that your application interacts with the correct version of the API, providing stability and compatibility as the API evolves. For more information on how versioning works and how to include it in your requests, please refer to the Versioning page.

Example Response

On the right side, you can see examples of different error codes by clicking Example and selecting the response code.

Rate Limits

All endpoints are subject to rate limits to protect the API from traffic spikes. For detailed information on rate limits, please refer to the Rate Limits section.

This page is interactive, allowing you to try a request by specifying the API version in the URL path and providing the necessary request body. As you fill out the parameters, the Curl command on the right side of the page will be automatically updated.

200OK

400Bad Request

401Unauthorized

403Forbidden

404Not Found

429Too Many Requests