This endpoint provides detailed information about each trip that matches the search criteria, enabling efficient management and retrieval of trip records.

Request Body Parameters

The following parameters are required in the request body:

Parameter	Type	Required	Description
page	Integer	No	The page number to retrieve.
pageSize	Integer	Yes	The number of items per page. Must be greater than 0.
status	Array of Strings	Conditionally	The status of the trip. Must be one or more of the allowed values: "Open", "Reserved", "Covered", "Dispatched", "InTransit", "Delivered", "Invoiced", "Completed", "Quoted", "Released", "TONU", "Cancelled", "Queued", "Financed", "Paid", "InReview". Required if no other conditional filters are provided.
loadNumbers	Array of Strings	Conditionally	The load number(s) associated with the trips. This field is required if the other conditionally required fields are left empty.
tripNumbers	Array of Strings	Conditionally	The trip number(s) to search for. This field is required if items matching the other conditionally required fields are left empty.
pickupDateRange	Object	No	The range of pickup dates to filter by.
pickupDateRange.start	String (Date-Time)	No	The start date of the pickup range.
pickupDateRange.end	String (Date-Time)	No	The end date of the pickup range.
deliveryDateRange	Object	No	The range of delivery dates to filter by.
deliveryDateRange.start	String (Date-Time)	No	The start date of the delivery range.
deliveryDateRange.end	String (Date-Time)	No	The end date of the delivery range.
updatedAtRange	Object	No	The range of update timestamps to filter by.
updatedAtRange.start	String (Date-Time)	No	The start date of the updatedAt range.
updatedAtRange.end	String (Date-Time)	No	The end date of the updatedAt range.
updatedBy	String	Conditionally	The user who last updated the trips. This field is required if the other conditionally required fields are left empty.
includeDeleted	Boolean	No	When set to `true`, the response will include both active and deleted trips (with `"IsDeleted": true` for deleted items). If `false` or omitted, only active records are returned and no `IsDeleted` flags are included.

Example CURL request

Use the Current API version The load number and make sure to replace the Authorization header value associated with your actual Bearer token for the request:

curl --location 'https://integrations.alvys.com/api/p/v1/trips/search' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ...' \
--header 'Content-Type: application/json' \
--data '{
"page": 0,
"pageSize": 100,
"status": [
"Covered"
],
"updatedBy" : "0d00f000-1b85-4ed8-000-6a000d1111db",
"updatedAtRange": {
"start": "2024-09-09T13:09:30.788Z",
"end": "2024-10-19T13:09:30.788Z"
},
"loadNumbers": [
"123456789"
],
"tripNumbers": [
"123456789"
],
"pickupDateRange": {
"start": "2025-07-23T10:45:56.477Z",
"end": "2025-07-23T10:45:56.477Z"
},
"deliveryDateRange": {
"start": "2025-07-23T10:45:56.477Z",
"end": "2025-07-23T10:45:56.477Z"
}
}'

Response Body Parameters

The following parameters are required in the request body:

Parameter	Type	Required	Description
page	integer	No	The current page of the response.
pageSize	integer	Yes	The number of items per page.
total	integer	Yes	The total number of items matching the criteria.
items[].id	string	Yes	The unique identifier of the trip.
items[].tripNumber	string	Yes	The number associated with the trip.
items[].status	string	No	The current status of the trip. Will always be one of the allowed values: "Open", "Reserved", "Covered", "Dispatched", "InTransit", "Delivered", "Invoiced", "Completed", "Quoted", "Released", "TONU", "Cancelled", "Queued", "Financed", "Paid", "InReview".
items[].loadNumber	string	No	The load number associated with the trip.
items[].tenderAs	string	No	Role under which the trip was tendered.
items[].stops[]	array of objects	No	The list of stops associated with the trip.
items[].stops[].id	string	No	The unique identifier of the stop.
items[].stops[].address.street	string	No	The street address of the stop.
items[].stops[].address.city	string	No	The city of the stop.
items[].stops[].address.state	string	No	The state of the stop.
items[].stops[].address.zipCode	string	No	The ZIP code of the stop.
items[].stops[].coordinates.latitude	string	No	The latitude of the stop location.
items[].stops[].coordinates.longitude	string	No	The longitude of the stop location.
items[].stops[].status	string	No	The current status of the stop.
items[].stops[].stopType	string	No	The type of stop (e.g., Pickup, Delivery).
items[].stops[].scheduleType	string	No	The schedule type of the stop. If `APPT`, see `appointmentDate`; if `FCFS`, see `stopWindow.*`.
items[].stops[].appointmentDate	string (datetime)	No	Appointment date/time for the stop. Only populated when `scheduleType = APPT`.
items[].stops[].stopWindow.begin	string (datetime)	No	Window begin time for the stop. Only populated when `scheduleType = FCFS`.
items[].stops[].stopWindow.end	string (datetime)	No	Window end time for the stop. Only populated when `scheduleType = FCFS`.
items[].stops[].loadingType	string	No	The loading type at the stop.
items[].stops[].arrivedAt	string (datetime)	No	When the stop was arrived at (UTC).
items[].stops[].departedAt	string (datetime)	No	When the stop was departed from (UTC).
items[].stops[].references[]	array of objects	No	A list of references associated with the stop.
items[].stops[].references[].id	string	No	The unique identifier of the reference.
items[].stops[].references[].referenceId	string	No	The external reference ID.
items[].stops[].references[].name	string	No	The name of the reference.
items[].stops[].references[].value	string	No	The value of the reference.
items[].stops[].references[].type	string	No	The type of reference (e.g., Text, Date).
items[].stops[].references[].access	string	No	The access level (e.g., Internal, Public).
items[].stops[].references[].origin	string	No	Origin of the reference field (e.g., Manual, Integration).
items[].stops[].companyId	string	No	The unique identifier of the company associated with the stop.
items[].stops[].companyNumber	string	No	The number of registration or identification number of the company linked to the stop.
items[].stops[].companyName	string	No	Name of the company linked to this stop.
items[].totalMileage.distance.value	number	No	Total mileage value.
items[].totalMileage.distance. unitOfMeasure	string	No	Unit of measure for total mileage (e.g., Miles).
items[].totalMileage.source	string	No	Source of total mileage.
items[].totalMileage.profileId	string	No	ID of mileage profile used.
items[].totalMileage.profileName	string	No	Name of mileage profile used.
items[].emptyMileage.distance.value	number	No	Empty mileage value.
items[].loadedMileage.distance.value	number	No	Loaded mileage value.
items[].pickupDate	string (datetime)	No	Scheduled pickup date.
items[].deliveryDate	string (datetime)	No	Scheduled delivery date.
items[].pickedUpAt	string (datetime)	No	Actual pickup timestamp.
items[].deliveredAt	string (datetime)	No	Actual delivery timestamp.
items[].carrierAssignedAt	string (datetime)	No	Carrier assignment timestamp.
items[].releasedAt	string (datetime)	No	Timestamp when the trip was marked as released.
items[].tripValue.amount	number	No	Total trip value.
items[].tripValue.currency	string	No	Currency for trip value.
items[].truck.id	string	No	ID of the truck.
items[].trailer.id	string	No	ID of the trailer.
items[].trailer.equipmentType	string	No	Equipment type of trailer.
items[].trailer.equipmentLength.value	number	No	Trailer length.
items[].trailer.equipmentLength. unitOfMeasure	string	No	Unit for trailer length (e.g., Feet).
items[].driver1.accessorialsDetails[]	array of objects	No	List of driver1 accessorials.
items[].driver2.accessorialsDetails[]	array of objects	No	List of driver2 accessorials.
items[].ownerOperator.accessorialsDetails[]	array of objects	No	List of owner-operator accessorials.
items[].carrier.accessorialsDetails[]	array of objects	No	List of carrier accessorials.
items[].*.accessorialsDetails[].id	string	No	Unique ID of the accessorial.
items[].*.accessorialsDetails[].type	string	No	Type of accessorial (e.g., Detention).
items[].*.accessorialsDetails[].total.amount	number	No	Total charge amount.
items[].*.accessorialsDetails[].total.currency	string	No	Currency of the total.
items[].*.accessorialsDetails[].rate.amount	number	No	Rate per unit.
items[].*.accessorialsDetails[].rate.currency	string	No	Currency of the rate.
items[].*.accessorialsDetails[].rateType	string	No	Rate type (Flat, PerHour, etc).
items[].*.accessorialsDetails[].uom	string	No	Unit of measure (e.g., Hours, Miles).
items[].*.accessorialsDetails[].quantity	number	No	Quantity of units billed.
items[].*.accessorialsDetails[].isPaid	boolean	No	If present, indicates whether accessorial has been paid.
items[].*.accessorialsDetails[].stopId	string	No	ID of the stop this accessorial is linked to (if applicable).
items[].*.accessorialsDetails[]. eCheckNumber	string	No	Associated ECheck number if applicable.
items[].*.accessorialsDetails[].createdAt	string (datetime)	No	When the accessorial was created (UTC).
items[].*.accessorialsDetails[].createdBy	string	No	User who created the accessorial.
items[].*.accessorialsDetails[].updatedAt	string (datetime)	No	When the accessorial was last updated (UTC).
items[].*.accessorialsDetails[].updatedBy	string	No	User who last updated the accessorial.
items[].*.eChecks[]	array of objects	No	List of EChecks issued to driver1, driver2, or ownerOperator.
items[].*.eChecks[].id	string	No	Unique ID of the ECheck.
items[].*.eChecks[].checkNumber	string	No	ECheck number.
items[].*.eChecks[].amount.amount	number	No	Amount value of the ECheck.
items[].*.eChecks[].amount.currency	string	No	Currency of the ECheck amount.
items[].*.eChecks[].fee.amount	number	No	Fee value of the ECheck.
items[].*.eChecks[].fee.currency	string	No	Currency of the fee.
items[].*.eChecks[].type	string	No	Type of ECheck.
items[].*.eChecks[].isPaid	boolean	No	Indicates whether the ECheck is paid.
items[].*.eChecks[].createdAt	string (datetime)	No	When the ECheck was created (UTC).
items[].carrier.linehaul.amount	number	No	Carrier linehaul amount.
items[].carrier.linehaul.currency	string	No	Currency of linehaul.
items[].carrier.accessorials.amount	number	No	Total accessorials amount for carrier.
items[].carrier.accessorials.currency	string	No	Currency for carrier accessorials.
items[].carrier.totalPayable.amount	number	No	Total amount payable to carrier.
items[].carrier.totalPayable.currency	string	No	Currency for total payable amount.
items[].carrier.carrierInvoiceNumber	string	No	Invoice number from the carrier.
items[].carrier.id	string	No	Unique ID of the carrier.
items[].releasedBy	string	No	User who released the trip.
items[].dispatchedBy	string	No	User who dispatched the trip.
items[].dispatcherId	string	No	ID of the dispatcher.
items[].carrierSalesAgentId	string	No	ID of the carrier sales agent.
items[].carrierPayOnHold	boolean	No	Indicates if carrier payment is on hold.
items[].updatedAt	string (datetime)	No	Timestamp when the trip was last updated.
items[].updatedBy	string	No	User who last updated the trip.
items[].isDeleted	boolean	No	Indicates if trip is deleted (true) or active (false). Only shown when IncludeDeleted: true.
items[].driver1.rates[]	array	No	Legacy rate objects for Driver 1 — used before the new driver rate-policy logic was introduced. This field remains for backward compatibility but is currently returned empty and will be deprecated.
items[].driver2.rates[]	array	No	Legacy rate objects for Driver 2 — used before the new driver rate-policy logic was introduced. This field remains for backward compatibility but is currently returned empty and will be deprecated.
items[].ownerOperator.rates[]	array	No	Legacy rate objects for Owner Operator — used before the new driver rate-policy logic was introduced. This field remains for backward compatibility but is currently returned empty and will be deprecated.
items[].driver1.ratesV2[]	array	No	List of structured rate objects for Driver 1 showing applied pay rules and calculated line items.
items[].driver2.ratesV2[]	array	No	List of structured rate objects for Driver 2 showing applied pay rules and calculated line items.
items[].ownerOperator.ratesV2[]	array	No	List of structured rate objects for Owner Operator showing applied pay rules and calculated line items.
items[].*.ratesV2[].policyId	string	No	Unique identifier of the specific pay policy instance applied to this driver for this trip.
items[].*.ratesV2[].policyName	string	No	Display name of the rate policy as shown in the UI.
items[].*.ratesV2[].perTripRate.rate	number	No	Flat per-trip pay rate applied to the trip.
items[].*.ratesV2[].perTripRate.rateId	string	No	Identifies the rate type defined within that policy.
items[].*.ratesV2[].perTripRate.rateName	string	No	Name of the per-trip rate type.
items[].*.ratesV2[].perTripRate.lineItems[]	array	No	Detailed line-item breakdown for the per-trip rate (description and amount).
items[].*.ratesV2[]. tripValuePercentageRate.percentage	number	No	Percentage of trip value used to calculate pay.
items[].*.ratesV2[]. tripValuePercentageRate.rateId	string	No	Identifier of the percentage-based rate type.
items[].*.ratesV2[]. tripValuePercentageRate.rateName	string	No	Name of the percentage-based rate.
items[].*.ratesV2[]. tripValuePercentageRate.lineItems[]	array	No	Line-item breakdown for the percentage-based rate (description, amount, currency).
items[].requiredEquipment[]	array of strings	No	List of equipment types required for the trip (e.g., "Reefer", "Van", "Flatbed"). Returned only when configured; otherwise omitted.
items[].temperature	object	No	Temperature requirements for temperature-controlled trips. Returned only when configured; otherwise omitted.
items[].temperature.setpointTemperature	number	No	Required target temperature.
items[].temperature.setpointTemperatureMax	number	No	Optional maximum temperature when a range is defined.
items[].temperature.controlMode	string	No	Operational mode ("Continuous", "Start/Stop").

⚠️ 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[] will receive empty or outdated arrays.
To ensure accurate and complete pay information, integrations should rely solely on RatesV2[] going forward.

Each rate type (e.g., TripValuePercentageRate, PerTripRate, MinimumPayRate, etc.) within RatesV2[] is provided as a structured object with detailed breakdowns via optional LineItems[].

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.

200OK

400Bad Request

404Not Found