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.)

  1. 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.
  2. When a carrier submits a Book Now or Bid offer from the Smart Load Board, it will trigger a post offer message.
  3. SLB will send all Booking/Bidding offers for loads with STATUS = OPEN
  4. 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.
  5. SLB will then POST to the provided Webhook with the offer object in the request body.
  6. Configure the Webhook to respond with an HTTP status code, status ENUM and optionally a message body
  7. 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.1

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

String2

A string specifying the offers version (v1, v2)

1 Client app version: Web clients should always place offers through this flow, mobile apps on version 47.0 will utilize this flow
2 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",
}