Load Offers API
This document outlines all the features that we have to support the Load Offers API interface.
This set of features allows you, as a integrator, to query our available loads and accept these directly from your platform.
Main features:
List Available Loads
Accept Load
List Accepted Loads
Drop Carrier from Load
Manage webhooks
How each feature works?
This API works as a marketplace where many loads are offered every day. The Search Offers endpoint provides many query parameters in order to filter the results based on origin, destination, equipment type, pickup date or delivery date.
Request:
curl --request GET \
--url https://api.sandbox.loadsmart.com/api/v2/load-offers/offers \
--header 'Authorization: JWT <Application-JWT token>'
Response:
Response::
{
"count": 1,
"next": null,
"previous": null,
"results": [
{
"id": "1f3b2981-dae1-4e48-bc6a-01ea55efd8fd", <-- offer reference
"price": 2246.0,
"load": {
"equipment_type": "DRV",
"commodity": "",
"weight": 20000.0,
"dimensions": {
"length": null,
"height": null,
"width": null
},
"distance": 1300.5,
"stops": [
{
"type": "PU",
"address": "101 Collins Avenue",
"city": "Miami Beach",
"state": "FL",
"country": "USA",
"window_start": "2023-09-13T13:00:00Z",
"window_end": "2023-09-13T15:00:00Z",
"window_timezone": "America/New_York",
"requirements": {
"blind_bol": false,
"drop_trailer": false,
"heavy_scale_ticket": false,
"light_scale_ticket": false
},
"latitude": 25.770007,
"longitude": -80.133743,
"zipcode": "33139",
"facility_info": {
"score": null,
"avg_time_spent": {
"pickup": 7,
"delivery": null
},
"detention_rate": 0
}
},
{
"type": "DEL",
"address": "459 Broadway",
"city": "New York",
"state": "NY",
"country": "USA",
"window_start": "2023-09-14T18:00:00Z",
"window_end": "2023-09-14T20:00:00Z",
"window_timezone": "America/New_York",
"requirements": {
"blind_bol": false,
"drop_trailer": false,
"heavy_scale_ticket": false,
"light_scale_ticket": false
},
"latitude": 40.720859,
"longitude": -74.000961,
"zipcode": "10013",
"facility_info": {
"score": null,
"avg_time_spent": {
"pickup": 1,
"delivery": null
},
"detention_rate": 0
}
}
],
"requirements": {
"beer": null,
"chemicals": null,
"ctpat": null,
"food_grade": null,
"frozen": null,
"hazmat": null,
"hvhr": null,
"pharmaceuticals": null,
"produce": null,
"teams": false,
"tsa": null,
"twic": null,
"vented_vans": null
},
"ref_number": "413036"
},
"actions": {
"redirect_url": "https://carrier.sandbox.loadsmart.com/#/loads/7e97683d-ea5a-4754-bf0c-e88644f3b997?utm_source=mayara",
"accept_url": "https://api.sandbox.loadsmart.com/api/v2/load-offers/offers/1f3b2981-dae1-4e48-bc6a-01ea55efd8fd/accept" <-- book it now URL
}
}
]
}
Besides other information, you’ll find the offer unique identifier in this endpoint’s response. You can use it to further requests such as to get a specific offer information:
Request:
curl --request GET \
--url https://api.sandbox.loadsmart.com/api/v2/load-offers/offers/1f3b2981-dae1-4e48-bc6a-01ea55efd8fd \
--header 'Authorization: JWT <Application-JWT token>'
After the search, an offer can be accepted for a carrier. It is necessary to use User-JWT to call the Accept an Offer endpoint in order accept the offer for a specific carrier signed on token.
Request:
curl --request POST \
--url https://api.sandbox.loadsmart.com/api/v2/load-offers/offers/1f3b2981-dae1-4e48-bc6a-01ea55efd8fd/accept \
--header 'Authorization: JWT <User-JWT token>'
Response:
{
"id": "f4212bbb-3a52-47bb-bc88-de0bbe335eaa" <<- load reference
}
Besides other features, you can use the load reference to download the Rate Confirmation by calling the Rate Confirmation endpoint:
Request:
curl --request GET \
--url https://api.sandbox.loadsmart.com/api/v2/load-offers/loads/f4212bbb-3a52-47bb-bc88-de0bbe335eaa/rate_confirmation \
--header 'Authorization: JWT <User-JWT token>'
Every accepted offer can be listed and detailed for further verification by using the List Accepted Loads endpoint:
Request:
curl --request GET \
--url https://api.sandbox.loadsmart.com/api/v2/load-offers/loads \
--header 'Authorization: JWT <Application-JWT token>'
An accepted load can be dropped in case the carrier is no longer able to move the load. To perform this action, the Drop a load endpoint must be called.
Request:
curl --request DELETE \
--url https://api.sandbox.loadsmart.com/api/v2/load-offers/loads/f4212bbb-3a52-47bb-bc88-de0bbe335eaa \
--header 'Authorization: JWT User-JWT' \
--header 'Content-Type: application/json' \
--data '{
"reason": "drop reason"
}'
A couple of events can be sent via webhook calls and it informs when an event is originated inside Loadsmart’s platform. The events can be:
load_cancelled: the load was canceled by the shipper.
load_carrier_bounced: the carrier was dropped from the load by Loadsmart.
This API provide endpoints to manage the webhooks configurations.
For the features listed above, they are all accessible over a REST API.
Validating on Sandbox
In order to make sure that all steps are been correctly followed, there are a few test-cases to execute in sandbox environment. Before executing these steps it is important to complete the validation of Partner Integration case the partner integration is been created.
Accept an Offer:
With a Application-JWT token, Search Offers;
With a User-JWT token, Accept an Offer;
List Loads and check if the load from the accepted offer is there.
Drop a Load:
With an a load that was accepted (previous test case);
List Loads and check if the load was removed.
Load dropped event (this test requires interaction with Loadsmart team):
With the webhooks configured;
And with an a load a accepted (first test case);
Loadsmart will drop the carrier an accepted load (event load_carrier_bounced);
Check if the webhook event is received.