The endpoint for searching loads requires specifying the API version in the URL path. 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.

Request Parameters

The following parameter is required in the URL path:

Parameter	Type	Required	Description
version	String	Yes	The API version to use.

Request Body Parameters

The version is required in the path parameters. The query request parameters for this endpoint are listed below.

Parameter	Type	Required	Description
page	Number	No	The page number for pagination.
pageSize	Number	Yes	The number of items per page for pagination. PageSize must be greater than 0.
dateRange	Object	No	The date range to filter the loads.
dateRange.start	String	No	The start date of the range to filter the `createdAt` loads.
dateRange.end	String	No	The end date of the range to filter the `createdAt` loads.
status	Array	Conditionally	The status of the loads to filter. This field is required if the other conditionally required fields are left empty. Statuses: [TONU, Dispatched, In Transit, Queued, Paid, Open, Completed, Financed, Cancelled, Covered, In Review, Quoted, Invoiced, Released, Delivered]
orderNumbers	Array	Conditionally	The order numbers to filter the loads. This field is required if the other conditionally required fields are left empty.
loadNumbers	Array	Conditionally	The load numbers to filter the loads. This field is required if the other conditionally required fields are left empty. The maximum number of load I allowed in the search body, loadNumber is 150.
poNumbers	Array	Conditionally	The purchase order numbers to filter the loads. This field is required if the other conditionally required fields are left empty.
customerId	String	Conditionally	The customer ID to filter the loads. This field is required if the other conditionally required fields are left empty.
updatedAtRange	Object	No	The date range to filter loads based on their last update.
updatedAtRange.start	String	No	The start date of the range to filter the `updatedAt` loads.
updatedAtRange.end	String	No	The end date of the range to filter the `updatedAt` loads.
updatedBy	String	Conditionally	The user ID of the person who last updated the loads.This field is required if the other conditionally required fields are left empty.
includeDeleted	Boolean	No	Optional flag. When set to true, the response will include both active and deleted loads (with "IsDeleted": true for deleted items). If omitted or set to false, only active records are returned and no IsDeleted flags are included.

Example CURL request

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

curl --location 'https://integrations.alvys.com/api/p/v1/loads/search' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ...' \
--header 'Content-Type: application/json' \
--data '{
  "page": 0,
  "pageSize": 200,
  "dateRange": {
      "start": "2023-09-09T13:09:30.788Z",
      "end": "2024-09-09T13:09:30.788Z"
               },
  "status": ["In Transit"],
  "updatedBy" : "0d00f000-1b85-4ed8-000-6a000d1111db",
  "updatedAtRange": {
      "start": "2024-09-09T13:09:30.788Z",
      "end": "2024-10-19T13:09:30.788Z"
  },           
  "orderNumbers": [
         "123456789"
               ],
  "loadNumbers": [
         "123456789"
                 ],
  "poNumbers": [
          "123456789"
               ],
  "customerId": "0e2bb9d5eae342c9bb89f7ac24f01a84"
}

Response Parameters

The following table lists the parameters included in the response for load-related requests.

Parameter	Type	Required	Description
id	String	Yes	The unique identifier of the load.
loadNumber	String	Yes	Human-readable load number, unique by subsidiary.
orderNumber	String	No	An optional external order number.
poNumber	String	No	An optional external Purchase Order number.
customerId	String	Yes	The internal Customer ID for the load.
customerName	String	No	Normalized customer name for reporting purposes; can be null for some historical data.
status	String	Yes	One of the following: In Review, Open, Quoted, Reserved, Covered, Dispatched, In Transit, Delivered, TONU, Released, Queued, Invoiced, Financed, Completed, Paid, Cancelled.
contractId	String	No	Optional Customer Contract ID.
customerType	List `<String>`	Yes	The type of customer this load is associated with.
fleet	Object	No	Information about the fleet associated with the load.
fleet.id	String	No	The unique identifier of the fleet.
fleet.name	String	No	The name of the fleet.
fleet.invoiceNumberPrefix	String	No	The invoice number prefix used by the fleet.
invoiceAs	String	Yes	The subsidiary or company information used when invoicing this load.
officeId	String	No	This value corresponds to the internal Office ID associated with the load.
linehaul	Object	No	The cost of transporting the load, excluding additional fees such as fuel surcharges or accessorials.
linehaul.amount	Number	No	The numeric value of the linehaul charge.
linehaul.currency	String	No	The currency of the linehaul charge.
fuelSurcharge	Object	No	The additional charge applied to cover fluctuating fuel costs.
fuelSurcharge.amount	Number	No	The numeric value of the fuel surcharge.
fuelSurcharge.currency	String	No	The currency of the fuel surcharge.
customerAccessorials	Object	No	Additional charges beyond the base rate and fuel surcharge, such as detention or lumper fees.
customerAccessorials.amount	Number	No	The numeric value of the accessorial charges.
customerAccessorials.currency	String	No	The currency of the accessorial charges.
customerRate	Object	No	Information about the rate charged to the customer for the load.
customerRate.amount	Number	No	The numeric amount of the customer rate, which includes all applicable customer accessorials like Linehaul (LH) + Fuel Surcharge (FSC) + Accessorials (ACC).
customerRate.currency	String	No	The currency of the customer rate.
customerMileage	Object	No	Information about the mileage associated with the load.
customerMileage.distance	Object	No	Information about the distance details.
customerMileage.distance.value	Number	No	The numeric value of the distance.
customerMileage.distance.unitOfMeasure	String	No	The unit of measure for the distance, e.g., Miles.
customerMileage.source	String	No	The source of the mileage data.
customerMileage.profileId	String	No	The profile ID used for the mileage data.
customerMileage.profileName	String	No	The profile name used for the mileage data.
invoicedAmount	Object	No	Information about the total amount invoiced for the load.
invoicedAmount.amount	Number	No	The numeric amount invoiced.
invoicedAmount.currency	String	No	The currency of the invoiced amount.
weight	Object	No	Information about the weight of the load.
weight.value	Number	No	The numeric value of the weight.
weight.unitOfMeasure	String	No	The unit of measure for the weight, e.g., Kilograms.
volume	Object	No	Information about the volume of the load.
volume.value	Number	No	The numeric value of the volume.
volume.unitOfMeasure	String	No	The unit of measure for the volume, e.g., Gallons.
scheduledPickupAt	String	No	Scheduled pick-up date and time.
scheduledDeliveryAt	String	No	Scheduled delivery date and time.
pickedUpAt	String	No	Actual pick-up time, always in UTC.
deliveredAt	String	No	Actual delivery time, always in UTC.
invoicedAt	String	No	Date and time when the first invoice was generated.
references	Object	No	Information about references associated with the load.
references.id	String	No	The unique identifier of the reference.
references.name	String	No	The name of the reference.
references.value	String	No	The value of the reference.
references.type	String	No	The data type of the reference, e.g., Text, Date, Bool, or List.
references.access	String	No	The access level of the reference, e.g., Internal or Public.
customerAccountManagerId	String	No	The unique identifier of the Customer Account Manager assigned to the load.
updatedAt	String	No	The date and time when the load was last updated.
updatedBy	String	No	The user who last updated the load.
IsDeleted	Boolean	No	Indicates deletion status of the `item: true` for deleted records, `false` for active records. Only present when `IncludeDeleted: true`.
loadType	String	No	The `LoadType` field indicates whether a load is `"Revenue"` or `"Non-Revenue"`.
customerAccessorialsDetails	Array of Objects	No	List of accessorial charges for the customer on the load.
customerAccessorialsDetails[].id	String	No	Unique ID of the accessorial.
customerAccessorialsDetails[].type	String	No	Type of accessorial (e.g., Detention, Layover, Fuel Surcharge).
customerAccessorialsDetails[].total.amount	Number	No	Total charge amount of the accessorial.
customerAccessorialsDetails[].total.currency	String	No	Currency of the total amount (e.g., USD).
customerAccessorialsDetails[].rate.amount	Number	No	Unit rate applied to the accessorial.
customerAccessorialsDetails[].rate.currency	String	No	Currency of the unit rate.
customerAccessorialsDetails[].rateType	String	No	How the rate is calculated (e.g., Flat, PerHour, PerMile).
customerAccessorialsDetails[].uom	String	No	Unit of measure (e.g., Hour, Mile, Stop).
customerAccessorialsDetails[].quantity	Number	No	Quantity multiplied by the rate to compute the total.
customerAccessorialsDetails[].isPaid	Boolean	No	If present, indicates whether the accessorial has been paid.
customerAccessorialsDetails[].stopId	String	No	ID of the related stop, if the accessorial is stop-specific (e.g., Detention).
customerAccessorialsDetails[].createdAt	String (DateTime)	No	Timestamp when the accessorial was created (UTC).
customerAccessorialsDetails[].updatedAt	String (DateTime)	No	Timestamp when the accessorial was last updated (UTC).
lastInvoiceSentAt	String (DateTime)	No	The timestamp of the most recent successful submission of an invoice from the Load Details 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 completing the fields for the parameters below. 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.