get
https://integrations.alvys.com/api/p/v/loads
Recent Requests
Log in to see full request history
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Loading…
The endpoint for retrieving 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 version is required in the PATH parameters. The following parameters can be added as QUERY parameters to filter the results:
| Parameter | Type | Required | Description |
|---|---|---|---|
| version | String | String | The API version to interact with. |
| id | String | Conditionally | The unique Alvys identifier of the load. This field is required if the other conditionally required fields are left empty. |
| loadNumber | String | Conditionally | Human-readable load number. This field is required if the other conditionally required fields are left empty. |
| orderNumber | String | Conditionally | An optional external order number. This field is required if the other conditionally required fields are left empty. |
Example CURL request
Example using Load ID:
curl --location 'https://integrations.alvys.com/api/p/v{version}/loads?id={loadId}' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'Example using Load Number:
curl --location 'https://integrations.alvys.com/api/p/v{version}/loads?loadNumber={loadNumber}' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'Example using Order Number:
curl --location 'https://integrations.alvys.com/api/p/v{version}/loads?orderNumber={orderNumber}' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'Replace {version} with the API version number, {loadId}, {loadNumber}, and {orderNumber} with the actual values, and YOUR_ACCESS_TOKEN with your actual Bearer token:
Using Load ID:
curl --location 'https://integrations.alvys.com/api/p/v1/loads?id=12345678964a744d5bd543647e6106f52' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ...'Using Load Number:
curl --location 'https://integrations.alvys.com/api/p/v1/loads?loadNumber=123456789' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ...'Using Order Number:
curl --location 'https://integrations.alvys.com/api/p/v1/loads?orderNumber=GENEIC123456789' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ...'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. |
| customerNumber | String | No | The customer number associated with the load. |
| 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. |
| tenderId | String | No | The identifier of the inbound EDI tender that created this load. null if the load was created manually or through a non-tender channel. |
| contractId | String | No | Optional Customer Contract ID. |
| customerType | List <String> | Yes | The type of customer this load is associated with. |
| stops | Array of Objects | Yes | List of stops associated with the load. |
| 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. |
| lastInvoiceSentAt | String (DateTime) | No | The timestamp of the most recent successful submission of an invoice from the Load Details page. |
| notes | Array of Objects | Yes | List of notes associated with the load. |
| createdAt | String (DateTime) | Yes | The date and time when the load was created. |
| createdBy | String | Yes | The user who created the load. |
| cancelledAt | String (DateTime) | No | The date and time when the load was cancelled. |
| cancelledBy | String | No | The user who cancelled the load. |
| 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. |
| customerServiceRepId | String | No | The unique identifier of the Customer Service Representative assigned to the load. |
| customerSalesAgentId | String | No | The unique identifier of the Customer Sales Agent assigned to the load. |
| customerSalesManagerId | String | No | The unique identifier of the Customer Sales Manager assigned to the load. |
| customerLoadPlannerId | String | No | The unique identifier of the Customer Load Planner assigned to the load. |
| 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. |
| paidAt | String (DateTime) | No | Timestamp when a customer payment was recorded against this load. |
| totalPaid | Object | No | Total amount paid by the customer to date. |
| totalPaid.amount | Number | No | The numeric total amount paid by the customer to date. |
| totalPaid.currency | String | No | The currency of the total paid amount. |
| payments | Array of Objects | No | Array of individual customer payment records. |
| payments[].id | String | No | The unique identifier of the payment record. |
| payments[].amount.amount | Number | No | The numeric amount of the payment. |
| payments[].amount.currency | String | No | The currency of the payment amount. |
| payments[].paidAt | String (DateTime) | No | The date and time when the payment was recorded. |
| tenderId | String | No | The identifier of the inbound EDI tender that created this load. null if the load was created manually or through a non-tender channel. |
| isDeleted | Boolean | No | Indicates whether the load is deleted. |
| requiredEquipment | List <String> | No | The required equipment for this load. |
| 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). |
404 Not Found
404 Not Found is returned in two cases:
- No load with the given ID exists for your tenant.
- A load record exists but has no associated trips (abandoned creation). These loads are treated as non-existent by the API.
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.