/api/p/v{version}/trips

The Retrieve All Trips API endpoint allows you to retrieve a list of all trips in the Alvys system. This endpoint provides comprehensive data about each trip, facilitating effective management and tracking of trips within the system.

Request Parameters

The following parameter is required in the URL path:

ParameterTypeRequiredDescription
versionStringYesThe API version to use.
tripNumberStringConditionallyThe trip number to filter results. This field is required if the other conditionally required fields are left empty.
idStringConditionallyThe 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 trip-related requests:

Parameter

Type

Required

Description

id

String

Yes

The unique identifier of the trip.

tripNumber

String

No

The number associated with the trip.

status

String

No

The current status of the trip. One of the following: In Review, Open, Quoted, Reserved, Covered, Dispatched, In Transit, Delivered, TONU, Released, Queued, Invoiced, Financed, Completed, Paid, Cancelled.

loadNumber

String

No

The load number associated with the trip.

stops

Array of Objects

No

The list of stops in the trip.

stops.id

String

No

The unique identifier of the stop.

stops.address

Object

No

Information about the stop's address.

stops.address.street

String

No

The street address of the stop.

stops.address.city

String

No

The city of the stop.

stops.address.state

String

No

The state of the stop.

stops.address.zipCode

String

No

The ZIP code of the stop.

stops.coordinates

Object

No

Information about the stop's geographical coordinates.

stops.coordinates.latitude

String

No

The latitude of the stop's location.

stops.coordinates.longitude

String

No

The longitude of the stop's location.

stop.status

String

No

The current status of the trip.

stops.stopType

String

No

The type of the stop (e.g., Pickup, Delivery).

stops.scheduleType

String

No

The schedule type for the stop.

stops.loadingType

String

No

The type of loading at the stop.

stops.arrivedAt

String (DateTime)

No

The timestamp for when the stop was arrived at.

stops.departedAt

String (DateTime)

No

The timestamp for when the stop was departed from.

stops.references

Array of Objects

No

A list of references related to the stop.

stops.references.id

String

No

The unique identifier of the reference.

stops.references.name

String

No

The name of the reference.

stops.references.value

String

No

The value of the reference.

stops.references.type

String

No

The type of reference (e.g., Text, Date).

stops.references.access

String

No

The access level of the reference (e.g., Internal, Public).

totalMileage

Object

No

Information about the total mileage of the trip.

totalMileage.distance

Object

No

The distance details for total mileage.

totalMileage.distance.value

Number

No

The value of the total distance.

totalMileage.distance.unitOfMeasure

String

No

The unit of measure for the distance (e.g., Miles).

emptyMileage

Object

No

Information about the empty mileage of the trip.

loadedMileage

Object

No

Information about the loaded mileage of the trip.

pickupDate

String (DateTime)

No

The scheduled pickup date of the trip.

deliveryDate

String (DateTime)

No

The scheduled delivery date of the trip.

pickedUpAt

String (DateTime)

No

The actual timestamp for when the load was picked up.

deliveredAt

String (DateTime)

No

The actual timestamp for when the load was delivered.

dateReleased

String (DateTime)

No

The actual timestamp for when the load was marked as Released.

carrierAssignedAt

String (DateTime)

No

The timestamp for when the carrier was assigned to the trip.

tripValue

Object

No

Information about the value of the trip.

tripValue.amount

Number

No

The numeric value of the trip.

tripValue.currency

String

No

The currency for the trip value.

truck

Object

No

Information about the truck assigned to the trip.

truck.id

String

No

The unique identifier of the truck.

truck.fleet

Object

No

Information about the fleet associated with the truck.

trailer

Object

No

Information about the trailer used in the trip.

trailer.id

String

No

The unique identifier of the trailer.

trailer.equipmentType

String

No

The type of equipment used for the trailer.

trailer.equipmentLength

Object

No

Information about the trailer's length.

trailer.equipmentLength.value

Number

No

The numeric value of the trailer's length.

trailer.equipmentLength.unitOfMeasure

String

No

The unit of measure for the trailer's length (e.g., Feet).

driver1

Object

No

Information about the first driver assigned to the trip.

driver1.id

String

No

The unique identifier of the first driver.

driver1.contractorType

String

No

The contractor type of the first driver.

driver1.rates

Array of Objects

No

Information about the rates applied to the first driver.

driver2

Object

No

Information about the second driver assigned to the trip.

releasedBy

String

No

The user who released the trip.

dispatchedBy

String

No

The user who executed the action to dispatch the trip.

dispatcherId

String

No

The user assigned as the dispatcher responsible for managing the load.

carrier

Object

No

Information about the carrier assigned to the trip.

carrier.id

String

No

The unique identifier of the carrier.

carrier.carrierInvoiceNumber

String

No

The invoice number for the carrier.

carrier.rate

Object

No

Information about the rate for the carrier.

carrier.rate.amount

Number

No

The numeric value of the carrier rate.

carrier.rate.currency

String

No

The currency of the carrier rate.

carrier.linehaul

Object

No

The base transportation cost for moving the load, excluding any additional charges.

carrier.linehaul.amount

Number

No

The numeric amount for the linehaul portion of the carrier's payment.

carrier.linehaul.currency

Number

No

The currency code for the linehaul amount.

carrier.accessorials

Object

No

The additional charges applied to the trip (e.g., detention, fuel surcharge).

carrier.accessorials.amount

Number

No

The numeric amount for the accessorial charges.

carrier.accessorials.currency

Number

No

The currency code for the accessorial charges.

carrier.totalPayable

Object

No

The total amount payable to the carrier (Linehaul + Accessorials).

carrier.totalPayable.amount

Number

No

The total numeric amount payable to the carrier.

arrier.totalPayable.currency

Number

No

The currency code for the total payable amount.

carrierPaymentOnHold

Boolean

No

Indicates whether payment to the carrier is currently on hold (true) or not (false).

updatedAt

String (DateTime)

No

The timestamp for when the trip was last updated.

updatedBy

String

No

The user who last updated the trip.

releasedAt

String (DateTime)

No

This field indicates the timestamp when the load was marked as "Released".


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. Alternatively, you can fork our Public API Postman Collection directly. Make sure to authorize yourself before trying a request.

Language
Credentials
Header
URL
Click Try It! to start a request and see the response here!