DSDC LTL eBOL API
The Digital LTL Council's electronic bill of lading standard, version 2.1.0 — the council's first and most adopted contract. This is the standard's own specification, not any carrier's implementation.
OpenAPI Specification
openapi: 3.0.0
info:
description: 'This document provides an electronic Bill of Lading (eBOL). The eBOL is a legal document that provides a contract between the shipper, carrier and consignee stating what goods are being shipped, where the shipment is coming from and where it’s headed to. “Pro” number is the unique identifier for the document for update and delete functions.'
version: "2.1.0"
title: Electronic Bill Of Lading Service
paths:
/bol/v1/app/:
post:
summary: Create an Electronic Bill of Lading
tags:
- Carrier API Standards
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BOL_Request'
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/BOL_Response'
'400':
description: Error response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Result_Status_Codes'
/bol/v1/app/{pro}:
put:
summary: Update an Electronic Bill of Lading
tags:
- Carrier API Standards
description: This operation updates an existing Electronic Bill of Lading.
parameters:
- in: path
name: pro
schema:
type: string
required: true
description: PRO Number of eBOL to update.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BOL_Request'
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/BOL_Response'
'400':
description: Error response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Result_Status_Codes'
'404':
description: eBOL not found.
delete:
summary: Delete an Electronic Bill of Lading
description: This operation deletes an existing Electronic Bill of Lading.
parameters:
- in: path
name: pro
schema:
type: string
required: true
description: PRO Number of eBOL to delete.
operationId: ''
tags:
- Carrier API Standards
responses:
'200':
description: Successful response.
'404':
description: eBOL not found.
'400':
description: Error response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Result_Status_Codes'
components:
schemas:
BOL_Request:
title: LTL BOL Request
description: >-
Objects and/or attributes that are required are indicated by a _**red
asterisk**_*. For those that are conditionally required, it will be
indicated within their description, including the condition in which
they are required.
type: object
required:
- bol
- version
- commodities
- payment
- origin
- destination
- billTo
properties:
bol:
type: object
required:
- function
- requestedPickupDate
- isTest
- requestorRole
properties:
requestedPickupDate:
type: string
example: '2022-11-20T00:00:00.000'
description: |
The intended Ship Date. NOTE this does not serve as a Pickup Request
Valid Formats:
* YYYY-MM-DDTHH:mm:ss.sss (ISO 8601)
function:
type: string
example: Create
description: |
The intent for the submitted request.
Valid Values:
* Create - Used for initial creation
isTest:
type: boolean
example: true
description: >-
Indicates whether or not the submitted request is intended to be
a test or not.
requestorRole:
type: string
example: Third Party
description: |
Identifies the party making the request.
Valid Values: See Requestor_Roles schema at the bottom of this page.
specialInstructions:
type: string
example: Gate code 123 to enter complex
description: >-
Special delivery instructions that need to be followed for the
shipment's delivery.
version:
type: string
example: "2.1.0"
description: |
Indicates which minor version of the Digital LTL Council Bill of Lading spec you are consuming
Valid values: 2.0.0, 2.0.1, 2.1.0
images:
type: object
properties:
includeBol:
type: boolean
description: >
Indicates whether or not you want an image of the populated BOL
returned in the response.
Default is false.
example: true
includeShippingLabels:
type: boolean
description: >
Indicates whether or not you want image(s) of the shipping
labels returned in the response.
Default is false.
example: true
shippingLabels:
type: object
properties:
format:
type: string
description: >
Specifies the printer format type for the labels.
Required when images.includeShippingLabels is true.
Valid Values: See the Shipping_Label_Formats schema at the
bottom of this page.
example: Avery
quantity:
type: integer
description: |
Specifies the quantity of pages desired.
Required when images.includeShippingLabels is true.
example: 5
position:
type: integer
description: |
Specifies the starting position for the shipping labels.
Required when images.shippingLabel is Avery.
Valid Values:
* 1 - 6
example: 2
email:
type: object
properties:
includeBol:
type: boolean
description: >
Used to request the bill of lading PDF to be sent to one or
more email addresses
example: true
includeLabels:
type: boolean
description: >
Used to request the shipping labels PDF to be sent to one or
more email addresses
example: true
addresses:
type: array
description: >
Provide one or more email addresses to receive the bol
and/or shipping labels PDF
items:
type: string
example:
- dispatch@shipper.com
notifications:
type: array
description: >-
include if you want notifications of shipment movements by text
message or email
items:
type: object
properties:
phoneNumber:
type: string
description: Phone number of contact for updates about shipment movements
example: '8881234567'
email:
type: string
description: Email address of contact for updates about shipment movements
example: dispatch@consignee.com
referenceNumbers:
type: object
properties:
pro:
type: string
description: >-
Shipper's pre-assigned PRO number for the requested carrier. If one was not provided in the request, one will be auto assigned by the carrier. The PRO number value should include the check digit when applicable.
example: 123456-7
quoteId:
type: string
description: >-
Quote (estimate) number provided by the carrier after submitting
a rate quote request.
example: E556724
shipmentId:
type: string
description: Shipment Id (SID) number for the shipment.
example: SID9743985
masterBol:
type: string
description: Master Bill of Lading number for the shipment.
example: MBL98472587
trailerId:
type: string
description: >-
When passed, indicates that the shipment is associated to a specific, spotted trailer.
manifestId:
type: string
description: >-
When passed, indicates that the shipment is associated to a manifest that includes multiple shipments, possibly across multiple spotted trailers.
bol:
type: array
items:
type: string
example:
- BL19498432
- BL99744565
po:
type: array
items:
type: object
properties:
number:
type: string
example: '554238'
description: The Purchase Order number.
pieces:
type: integer
example: 5
description: Total pieces associated with the Purchase Order
weight:
type: integer
example: 150
description: Total weight associated with the Purchase Order
weightUnit:
type: string
example: Pounds
description: |
The unit of measurement for weight. Defaults to Pounds (Imperial) if not passed.
Valid Values: Pounds or Kilograms
palletized:
type: boolean
example: true
description: >-
Indicates whether or not the pieces associated with the
purchase order are on a pallet/slip/skid or not.
additionalShipperInfo:
type: string
example: Freight must always stay upright
description: Additional information from shipper per line item
additionalReferences:
type: array
items:
type: object
properties:
name:
type: string
example: Customer Reference Id
description: |
Indicates the name of the reference number being provided.
value:
type: string
example: CRID3452-01
description: >-
Additional reference number that correlates to the
additional reference name.
payment:
type: object
required:
- terms
properties:
terms:
type: string
example: Prepaid
description: |
Freight Billing Terms for the shipment
Valid Values: See the Payment_Terms schema at the bottom of this
page.
commodities:
type: object
required:
- lineItemLayout
- handlingUnits
- lineItems
properties:
lineItemLayout:
type: string
example: Nested
description: |
Valid values: Nested or Stacked
Nested: Indicates if the Handling Unit/Line Item relationship is
known. If this value is used, each Line Item associated to a
Handling Unit is conditionally required to be passed within that
Handling Unit's object.
Stacked: Indicates if the Handling Unit/Line Item relationship
is not known. If this value is used, Line Items may passed
within any Handling Unit object.
handlingUnits:
type: array
items:
type: object
required:
- count
- type
- weight
properties:
count:
type: integer
example: 2
description: Number of handling units being described
type:
type: string
example: SKD
description: |
Type of the handling units being described
Valid Values: See the Handling_Unit_Types schema at the
bottom of this page
tareWeight:
type: integer
example: 5
description: Weight of the skids/pallets/slips used in the shipment.
weight:
type: integer
description: Total weight for the specified handling units.
example: 1500
weightUnit:
type: string
example: Pounds
description: |
The unit of measurement for weight. Defaults to Pounds (Imperial) if not passed.
Valid Values: Pounds or Kilograms
length:
type: integer
example: 48
description: The length of the handling units being described.
width:
type: integer
example: 48
description: The width of the handling units being described.
height:
type: integer
example: 48
description: The height of the handling units being described.
dimensionsUnit:
type: string
example: Inches
description: |
The unit of measurement for dimensions. Defaults to Inches (Imperial) if not passed.
Valid Values: Inches or Centimeters
stackable:
type: boolean
example: false
description: |
Identifies whether or not the freight being described can be stacked on one another.
Default is false.
lineItems:
type: array
items:
type: object
required:
- weight
- classification
- description
- hazardous
- stackable
- pieces
- packagingType
properties:
description:
type: string
example: Small frameless mirrors
description: Description of the freight being described.
weight:
type: integer
example: 1500
description: Total weight for the specified lineItem.
weightUnit:
type: string
example: Pounds
description: |
The unit of measurement for weight. Defaults to Pounds (Imperial) if not passed.
Valid Values: Pounds or Kilograms
pieces:
type: integer
example: 3
description: >-
Number of individual pieces for the line item being
described.
packagingType:
type: string
example: BOX
description: |
Packaging type for the individual pieces of the line item being described.
Valid Values: See the Packaging_Types schema at the
bottom of this page
classification:
type: string
example: '55'
description: |
Classification of the line item being described.
Valid Values: See the Classification_Codes schema at
the bottom of this page.
nmfc:
type: string
description: NMFC code of the freight being described.
example: '86900'
nmfcSub:
type: string
description: >-
The Sub value for the NMFC of the freight being
described.
example: '3'
hazardous:
type: boolean
example: true
description: >-
Identifies whether or not the freight being
described contains hazardous materials.
hazardousDescription:
type: string
example: UN 1090, Acetone, 3, PG II
description: >-
Conditionally required when 'hazardous' is 'true'.
Provides a detailed description of the hazardous
item.
hazardousDetails:
type: object
properties:
weight:
type: integer
example: 45
description: >-
Total weight of hazardous material coveraged by
one description.
weightUnit:
type: string
example: Pounds
description: |
The unit of measurement for weight. Defaults to Pounds (Imperial) if not passed.
Valid Values: Pounds or Kilograms
class:
type: string
example: '3'
description: >-
Class that the hazardous material is catogorized
by.
unnaNumber:
type: string
example: UN1234
description: >-
Proper Identification Number (UN or NA)
corresponding to the Proper Shipping Name
propername:
type: string
example: Anhydrous ammonia
description: |
Proper shipping name for the hazardous material.
From DOT regulations 172.101
technicalName:
type: string
example: NH3
description: >
Technical name for the hazardous material. Not
all hazardous items will have a technical name.
From DOT regulations 172.101
packingGroup:
type: string
example: '2'
description: >-
Hazmat Packing Group number. Not all hazmat
items have a packing group
contractNumber:
type: string
example: '54321'
description: >-
The contract number with the hazardous materials
contact
shipmentTotals:
type: object
properties:
grossWeight:
type: integer
example: 2000
description: >-
Total weight of the entire shipment, including handling units
(tare weight).
netWeight:
type: integer
example: 1993
description: >-
Total weight of the entire shipment, not including handling
units (tare weight).
weightUnit:
type: string
example: Pounds
description: |
The unit of measurement for weight. Defaults to Pounds (Imperial) if not passed.
Valid Values: Pounds or Kilograms
handlingUnits:
type: integer
example: 2
description: Handling unit count for the entire shipment
linearLength:
type: integer
description: Linear length for the entire shipment
example: 96
dimensionsUnit:
type: string
example: Inches
description: |
The unit of measurement for dimensions. Defaults to Inches (Imperial) if not passed.
Valid Values: Inches or Centimeters
cube:
type: integer
example: 128
description: >-
Cubic volume of the entire shipment (total length X total width
X total height).
cubeDimensionsUnit:
type: string
example: Feet
description: |
The unit of measurement for cubic dimensions. Defaults to Feet (Imperial) if not passed.
Valid Values: Feet or Meters
declaredValue:
type: integer
example: 7
description: >-
Total monetary value of the shipment in USD (sometimes needed
for cross-border moves).
currency:
type: string
example: USD
description: |
Optional attribute to indicate currency of declaredValue.
Defaults to USD.
Valid values: See the Currencies schema at the bottom of this
page.
accessorials:
type: object
properties:
codes:
type: array
description: |
An array to hold the list of services requested for the shipment
Valid Values: See the Accessorial_Codes schema at the bottom of
this page.
items:
type: string
example:
- IDL
- LFTP
hazardousDetails:
type: object
description: >
Required if accessorial codes list contains HAZ and/or if any
commodity line item's hazardous flag is set to true.
properties:
emergencyContact:
type: object
properties:
name:
type: string
example: Manny Delgato
description: >-
Full name of who should be contacted in the case of a
hazardous materials-related issue.
phone:
type: string
example: '7775558899'
description: |
Phone number of who should be contacted in the case of a hazardous materials-related issue.
Valid Formats:
* ########## (10 digits - Area code + phone)
cod:
type: object
description: >
Required when accessorial code COD is present in the
accessorial.codes list.
properties:
amount:
type: string
example: '56.71'
description: |
Amount to be received for the COD.
Valid Formats:
* ##.## (2 decimal places only)
currency:
type: string
example: USD
description: |
Optional attribute to indicate currency of COD. Defaults to USD.
Valid values: See the Currencies schema at the bottom of this page.
terms:
type: string
example: Collect
description: |
Payment terms associated with the COD.
Valid Values:
* Prepaid
* Collect
customerCheckAcceptable:
type: boolean
example: true
description: >-
Indicates whether or not a customer check or cash is
acceptable.
remitTo:
type: object
description: >
Required when accessorial code COD is present in the
accessorial.codes list.
properties:
name:
type: string
description: Name of the remit to company.
example: Dog Beds by Stella
address1:
type: string
description: Primary Address line of the remit to company.
example: 121 S. Cliffwood Ave.
address2:
type: string
description: Secondary Address of the remit to company.
example: Suite 55
city:
type: string
example: Los Angeles
description: City Name of the remit to company.
stateProvince:
type: string
description: |
Two letter state/province code of the remit to company.
Valid Values: See the State_Province_Codes schema at the bottom of this page.
example: CA
postalCode:
type: string
example: '90001'
description: >
The 5-digit + 4 or 5-digit for the United States, 5-digit for Mexico, or 6-character for Canada, postal code for the remit to company location.
Valid formats:
* 12345-1234 (5 digits + 4 - USA)
* 12345 (5 digits - USA/MEX)
* A1A1A1 (6 characters - CAN)
* A1A1A (5 characters - CAN)
country:
type: string
example: USA
description: |
Three letter country code of the remit to company.
Valid Values: See the Country_Codes schema at the bottom of this page.
sortAndSegregateDetails:
type: object
description: >
Required when accessorial code SRT is present in the
accessorial.codes list.
properties:
pieces:
type: integer
description: Number of pieces in a shipment to be sorted/segregated
example: 25
fullValueCoverageDetails:
type: object
description: >
Required when accessorial code FVC is present in the
accessorial.codes list.
properties:
monetaryValue:
type: string
description: |
Value of the cargo.
Valid Formats:
* ##.## (2 decimal places only)
example: '100.00'
currency:
type: string
example: USD
description: |
Optional attribute to indicate currency of monetaryValue.
Defaults to USD.
Valid values: See the Currencies schema at the bottom of this page.
markDetails:
type: object
description: >
Required when accessorial code MARK is present in the
accessorial.codes list.
properties:
pieces:
type: integer
description: Number of pieces in a shipment requiring marking or tagging
example: 25
limitedAccessType:
type: object
description: >
Optional attribute to indicate the limited access type when
accessorial code LTDAP or LTDAD is present in the
accessorial.codes list.
properties:
origin:
type: string
description: >
Optional attribute to indicate the limited access type when
accessorial code LTDAP is present in the accessorial.codes
list.
Valid Values: See the Limited_Access_Types schema at the
bottom of this page.
example: Church
destination:
type: string
description: >
Optional attribute to indicate the limited access type when
accessorial code LTDAD is present in the accessorial.codes
list.
Valid Values: See the Limited_Access_Types schema at the
bottom of this page.
example: Secure
timeCriticalDetails:
type: object
properties:
type:
type: string
example: Delivery Window
description: >
Type of delivery required for the requested Time Critical
Service.
Required when accessorials.code list include TCS.
Valid Values: See the Time_Critical_Types schema at the
bottom of this page.
date:
type: object
properties:
start:
type: string
example: '2021-05-20T00:00:00.000'
description: >
The date (with or without time) the shipment is
re
# --- truncated at 32 KB (64 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/nmfta/refs/heads/main/openapi/nmfta-dsdc-ltl-ebol-2.1.0-openapi.yml