Offers Webhook Flow

Instructions on how to integrate and perceive offer requests from the Smart Load Board

Purpose: To forward the POST/Offer request from a carrier through the Smart Load Board to the external webhook URL of a Freight Partner. Smart Load Board will surface up the status of offers placed through this experience back to the carrier determined from the webhook response (e.g., Success, Server Error, etc.)

The URL can be customized to include the Load ID and Load Reference embedded in the URL path.
Examples :
a) http://example.com/offer/endpoint
b) http://example.com/offer/endpoint?load_id={load_id}&load_reference={load_reference}
Smart Load Board team will update Freight Partner preferences manually to add the webhook URL
Basic Authentication is supported.
When a carrier submits a Book Now or Bid offer from the Smart Load Board, it will trigger a post offer message.
SLB will send all Booking/Bidding offers for loads with STATUS = OPEN
The carrier who made the request is attached to the offer object. Note, you may receive multiple DOTs/MCs or no DOT/MC with a Bid offer, but you will always receive exactly one DOT and/or MC with a Book Now offer.
SLB will then POST to the provided Webhook with the offer object in the request body.
Configure the Webhook to respond with an HTTP status code, status ENUM and optionally a message body
Reach out to us when the Webhook configuration is complete

Example webhook response body

{
    "status": <status ENUM>,
    "message": <optional message>
}

The message on the webhook response is a useful place to send back a detailed error response if there are any issues about the webhook or offer from the broker's end.

The Offers Status messaging will be shared to carriers when your webhook contains the response defined above and for offer requests placed through the latest client app experience.¹

Offers Status Messaging:
These dialogs on the client side (web app and mobile) will show up if your Webhook body contains the corresponding Status ENUM . If status is not present then the message is determined by the HTTP Status Code.

HTTP Status	Status ENUM	Description	UI Message Header	UI Message Body
200	OFFERS_STATUS_MESSAGE_BOOKED	Load has been successfully booked in broker’s TMS	Booking/Bidding Confirmed	[load.broker_name] will contact you directly to follow up.
500	OFFERS_STATUS_MESSAGE_FP_INTERNAL_ERROR	All server errors caused by a technical failure on the FREIGHT PARTNER side	Booking/Bidding Error	We’re sorry, <load.broker_name> seems to be having a technical issue. Please try again later. You can also call <load.contact.phone> or email <load.contact.email> to book this load.
552	OFFERS_STATUS_MESSAGE_NOT_AVAILABLE	The load is no longer available (status <> OPEN)	Load No Longer Available	We’re sorry, this load has been removed.
553	OFFERS_STATUS_MESSAGE_INSURANCE_ERROR	There is some issue with the carrier’s insurance	Insurance Issue	You cannot book this load at this time because there is an issue with the insurance you have on file with <load.broker_name>. Please call <load.contact.phone> or email <load.contact.email> to resolve.

Expected webhook Offer object JSON format:

Value	Type	Desscription
Load_id	String	Load SLB ID
Load_reference	String	Load Broker's Reference
Type	String/ENUM	TYPE_BOOK_NOW , TYPE_BID
Booking_requirements	Array of booking requirement objects	The carrier’s selections of booking requirements that they’ve consented to
Carriers	Array of carrier objects [Deprecated]	Carrier object - all information is provided based on Motive account data
Carrier.name	String	Carrier name
Carrier.usdot	String	Company’s Carrier DOT
Carrier.mc_mx_ff	String	Carrier's MC ID
Carrier.is_on_allowlist	Bool	Whether carrier is on broker's allwolist
Carrier.provided_visibility_consent	Bool	Whether carrier has provided consent to share visibility data with broker (note: this field will not be provided at launch - to be added in future)
Submitter	Object
Submitter.role	String/ENUM	Indicates the role of the individual who submitted the offer. Values: ROLE_DRIVER , ROLE_FLEET_MANAGER
Contact	Object	Indicates the information for the individual that the broker should contact about the offer.
Contact.name	String	Individual's name
Contact.email	String	Contact email (optional if phone is provided)
Contact.phone	String	Contact phone (optional if email is provided)
Contact.role	String/ENUM	Indicates the role of the individual who should be contacted about the offer. (When a driver submits a bid, they can identify their dispatcher as the contact, in which case SUBMITTER.ROLE = ROLE_DRIVER and CONTACT.ROLE = ROLE_DISPATCHER) Values: ROLE_DRIVER, ROLE_DISPATCHER
Rate	uint32	Rate that the carrier is offering (for Book Now, will equal the posted rate)
Platform	String/ENUM	The platform that the carrier used to submit the offer. Values: PLATFORM_DRIVER_MOBILE_ANDROID_APP, PLATFORM_DRIVER_MOBILE_IOS_APP, PLATFORM_DESKTOP_WEB_DASHBOARD
Carrier	Object	Carrier object - all information is provided based on Motive account data
Carrier.name	String	Carrier name
Carrier.usdot	String	Company’s Carrier DOT
Carrier.mc_mx_ff	String	Carrier’s MC ID
Carrier.is_on_allowlist	Bool	Whether carrier is on broker’s allowlist
Carrier.provided_visibility_consent	Bool	Whether carrier has provided consent to share visibility data with broker (note: this field will not be provided at launch - to be added in future)
Version	String²	A string specifying the offers version (v1, v2)

¹ Client app version: Web clients should always place offers through this flow, mobile apps on version 47.0 will utilize this flow
² Version: This field indicates which SLB internal API the client application used to submit the offer

Offer V2 Webhook object with only USDOT carrier example:

{
   "load_id": "486863267242625a4d2a585555384035a51d8b15f140d7d98f443598b34d950e",
   "load_reference": "7ffc1cb7c47f49f59b9233fe6ddeeb52",
   "type": "TYPE_BOOK_NOW",
   "booking_requirements": [
       {
           "key": "REQUIREMENT_HAZMAT",
           "status": "STATUS_REQUIRED"
       },
       ...
   ],
   "carriers": [
       {
           "name": "FRIEND BOX COMPANY",
           "usdot": "42654",
           "is_on_allowlist": true,
           "provided_visibility_consent": false
       }
   ],
   "submitter": {
       "role": "ROLE_DRIVER"
   },
   "contact": {
       "name": "John Doe",
       "email": "jdoe@test.com",
       "phone": "+1344242342",
       "role": "ROLE_DISPATCHER"
   },
   "rate": 123,
   "carrier" : {
           "name": "FRIEND BOX COMPANY",
           "usdot": "42654",
           "is_on_allowlist": true,
           "provided_visibility_consent": false
   },
   "platform": "PLATFORM_DESKTOP_WEB_DASHBOARD",
   "version": "v2",  
}

Offer V2 Webhook object with only MCMXFF carrier example:

{
   "load_id": "486863267242625a4d2a585555384035a51d8b15f140d7d98f443598b34d950e",
   "load_reference": "7ffc1cb7c47f49f59b9233fe6ddeeb52",
   "type": "TYPE_BOOK_NOW",
   "booking_requirements": [
       {
           "key": "REQUIREMENT_HAZMAT",
           "status": "STATUS_REQUIRED"
       },
       ...
   ],
   "carriers": [
       {
           "name": "EISELES HONEY AND POLLINATION",
           "mc_mx_ff": "64858",
           "is_on_allowlist": true,
           "provided_visibility_consent": false
       }
   ],
   "submitter": {
       "role": "ROLE_DRIVER"
   },
   "contact": {
       "name": "John Doe",
       "email": "jdoe@test.com",
       "phone": "+1344242342",
       "role": "ROLE_DISPATCHER"
   },
   "rate": 123,
   "carrier": {
       "name": "EISELES HONEY AND POLLINATION",
       "mc_mx_ff": "64858",
       "is_on_allowlist": true,
       "provided_visibility_consent": false
   },
   "platform": "PLATFORM_DESKTOP_WEB_DASHBOARD",
   "version": "v2",
}