openapi: 3.1.0
info:
title: Electronic Bill Of Lading API
version: 1.0.0-public-preview
contact:
name: DSDC APIs Full Truckload
url: https://github.com/dsdcapis/full-truckload
license:
name: DSDC Repository License
url: https://github.com/dsdcapis/full-truckload/blob/main/LICENSE.md
description: |
# Overview
The NMFTA has partnered with leaders across the transportation industry to deliver a digitized
method of transferring data between parties. By developing open-source API standards, the
NMFTA and its partners will open the door to a more efficient method of data transfer, which
today is still accomplished through a variety of more rudimentary processes. Digital API
standards will reduce costs to onboard new business partners, improve visibility to shipment
information, allow for real time notification on shipment changes, and drive out waste across
the industry by eliminating manual processes. API standards will empower technological
development, particularly when it comes to process automation.
The Bill of Lading (BOL) is a crucial document that communicates the details and expectations
for a specific freight shipment. It is a legally binding document issued by the Carrier to the
Shipper that defines the shipment (type, quantity, origin, etc.), and is the basis of the business
transaction between a Shipper and a Carrier. The current BOL process consists of a physical
document transported between parties that is frequently lost, stolen, or delayed in being
documented for all parties to review. This council will create an electronic Bill of Lading API
standard that will allow for a more efficient and streamlined BOL process that will reduce or
eliminate some of the risks associated with the current BOL process.
Because the BOL sets the expectations for a shipment, it serves as the foundation for
processes later in the shipment lifecycle. Similarly, the eBOL defined by the Digital Council will
provide the foundation for the other APIs that will be defined to handle other business
processes. An eBOL will act as a digital twin of a physical BOL document, containing the same
crucial shipment information and carrying the same importance.
# Value Proposition
## Shipper
The eBOL API will allow a Shipper to more easily share the official details of a
shipment, reducing opportunities for misunderstanding, human error, and theft. With
existing BOL processes, particularly for a LTL shipment, a Shipper does not have
visibility to the PRO number or shipment status until Pickup occurs. With the eBOL API,
the Shipper will receive the PRO number pre-pickup, and in conjunction with other
standard APIs, will be able to receive pre-pickup visibility on their loads.
Additionally, current processes leave open the possibility for theft when bad actors
manipulate physical BOLs to hide evidence of theft, and makes it difficult for Shippers
to prove otherwise. An electronic BOL process will reduce these opportunities and give
Shippers peace of mind.
A Shipper will initiate the eBOL process by sending the details of their shipment to a
Carrier using the standard API format. They will receive back from the Carrier a
completed BOL and shipping label. The response will also include a unique shipment
identifier (PRO in the case of an LTL shipment) that can be used to reference the
shipment in future interactions with the Carrier, including tracking update requests.
## Carrier
The eBOL API will be especially beneficial to the Carrier community by
outlining the standard communication protocol for sharing BOL information, greatly
simplifying the connectivity required to do business with a large number of Shippers,
customers, and third parties. Among other things this will improve billing accuracy,
reduce opportunity for manual errors, and allow Carriers to provide better service to
customers.
A Carrier will receive details of a shipment via the eBOL API from the Shipper, store the
information in their system, and return the official BOL back to the Shipper. They will
also return a shipping label that the Shipper can print and attach to their shipment. As
part of this, they will also return a unique load identifier (in the case of an LTL shipment,
it will be the PRO number) back to the Shipper that can be used to reference their load
going forward.
## 3rd Party
The eBOL API will allow third parties of all kinds to receive and send the
necessary shipment information to ensure a seamless flow through the life cycle of a
shipment. Due to the nature of 3rd parties' business and having to interact with multiple
parties in the transportation industry, 3rd parties stand much to gain by simplification of
their business processes, which the eBOL will enable.
# LTL
In the LTL industry, the BOL is a particularly valuable document due to the inherent
complexities of an LTL shipment. Not only does an LTL BOL contain general shipment
information (such as origin, destination, billing info), but it also contains very detailed
information on the freight being shipped, down to the commodity information of each
individual line item. Because of this, any eBOL solution for an LTL shipment must be very
detailed, while still allowing for significant variations from shipment to shipment.
The NMFTA LTL Digital Council has already defined and released standards for eBOL in the LTL
industry. Its usage is being adopted by Shippers, Carriers, and 3PLs, and is being put to use to
drive efficiency and automation for LTL shipments.
# FTL
The BOL for a Full Truckload shipment serves the same purpose and contains similar
information to that of an LTL shipment. The main difference between a FTL and LTL is the level
of detail is usually less for a FTL shipment. A FTL BOL may not include a PRO number, NMFC
Codes, Classification, and often will not include pallet counts and reliable dimensions.
The NMFTA FTL Digital Council will be coordinating with their LTL Council counterparts to look
to find an opportunity for a single, combined eBOL standard that meets the needs of both the
LTL and FTL use cases. The synergy between the two will help drive adoption throughout the
transportation industry, where many organizations are involved in both FTL and LTL
transportation.
# Product Requirements Document (PRD)
The Product Requirements Document (PRD) for this API can be found [here](https://dsdcapis.github.io/full-truckload/api-prds/API%20Product%20Requirements%20-%20eBOL.pdf).
tags:
- name: Carrier API Standards
description: Standards for Carrier APIs
paths:
/bol/v1/app:
post:
summary: Create/Update/Delete an Electronic Bill of Lading
operationId: bol
description: |
## Request
As a Shipper/3rd Party, I want to Create/Update/Delete an Electronic Bill of Lading and send shipment
information for a particular shipment to a Carrier.
- In a request, the Shipper/3rd Party MUST identify themselves so the Carrier is aware of
who is sending the BOL information
- Types of Roles: Shipper, Third Party, Consignee
- In a request, the Shipper/3rd Party MUST provide a requested pickup date. The
requested pickup date MUST be in date/time format. The API will allow for a Pickup
Begin and Pickup End date/time.
- LTL Consideration: The requested pickup date is NOT a formal LTL Pickup
Request
- In a request, the Shipper/3rd Party MUST designate the origin and destination for the
shipment. This can be via a location id understood by both parties, or via the address of
the location.
- In a request, the Shipper/3rd Party MAY designate whether or not they want an image of
the BOL and/or Shipping Labels returned in the response.
- In a request, the Shipper/3rd Party MAY designate a reference number associated with
their shipment.
- In a request, the Shipper/3rd Party MUST specify freight Billing terms for the shipment.
- In a request, the Shipper/3rd Party MUST specify the Billing information for the shipment,
including name, address, and contact information.
- In a request, a Shipper/3rd Party MAY provide special shipment requirements that would
indicate if accessorials are needed.
- Examples Include, but not limited to:
- Limited Access
- Time Critical
- Lift Gate Required
- Expedite
- In a request, the Shipper/3rd Party MUST specify the commodity of the freight being
shipped.
- LTL Consideration: The classification of LTL commodities MUST be included for
an LTL shipment
- In a request, additional details on the shipment MAY be included. The API will allow for
information to be provided at both the commodity level, as well as at the total shipment
level.
- LTL Consideration: The weight, handling units, and dimensions of an LTL
shipment MUST be included
- Examples include:
- Weight
- Handling Units
- Linear Length
- Overall Dimensions
- Shipper/3rd Party SHOULD provide details for a HAZMAT shipment. This information
with be conditionally required based on U.S. Department of Transportation's (DOT)
Hazardous Materials Regulations (49 CFR Parts 171-180). This includes:
- Hazardous Description
- Total Quantity
- Weight or Volume (i.e. lbs, kilograms, liters, etc.)
- Hazard class or Division
- Identification Number (UN/NA)
- Proper Name
- Technical Name
- Packaging Group
- Emergency Response
- 24-Hour Emergency Response
- Emergency Response Guidebook (ERG) Guide Number
- Marine Pollutant Marking
- Contact Number
- Shipper/3rd Party SHOULD provide Total Shipment Value in a designated currency (USD
as an option) for high value shipments that may require additional considerations by the
Carrier.
## Response
As a Carrier, I want to respond to the Shipper/3rd Party who created the electronic Bill of Lading
and either accept or reject, as well as provide a unique shipment identifier associated with the
shipment.
- In a response, the Carrier must indicate if the eBOL was successfully accepted
- Reasons an eBOL request would be rejected:
- Not enough information provided in eBOL request
- Internal error in Carrier system (example: PRO number Shipper sent
already associated with a different shipment)
- In a response, the Carrier MUST provide the timestamp of the transaction date for the
electronic bill of lading.
- In a response, the Carrier MUST designate a reference number to uniquely identify the
shipment, if one was not provided in the request.
- If a reference number was provided in the request, then it MUST be provided in
the response.
- Reference Best Practices for list of available reference number types.
- The Carrier MUST provide BOL details in the response, and MUST provide a PDF image
of the BOL and Shipping labels if requested in the Request body.
tags:
- Carrier API Standards
requestBody:
required: true
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BOL_Request'
- $ref: '#/components/schemas/FTL_BOL_Request'
responses:
'200':
description: Successful response
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BOL_Response'
- $ref: '#/components/schemas/FTL_BOL_Response'
'400':
description: Error response
content:
application/json:
schema:
type: array
items:
oneOf:
- $ref: '#/components/schemas/Result_Status_Codes'
- $ref: '#/components/schemas/Result_Status_Codes-2'
components:
schemas:
FTL_BOL_Request:
allOf:
- type: object
required:
- bol
- version
properties:
bol:
allOf:
- type: object
required:
- function
properties:
function:
type: string
description: |
The intent for the submitted request.
enum:
- Create
- Update
- Delete
- $ref: '#/components/schemas/BOL_Header'
version:
$ref: '#/components/schemas/FTL_Version'
- $ref: '#/components/schemas/BOL_Request-2'
FTL_BOL_Response:
allOf:
- type: object
properties:
version:
$ref: '#/components/schemas/FTL_Version'
- $ref: '#/components/schemas/BOL_Response-2'
FTL_Version:
title: Version
type: string
description: |
Indicates which version of the Digital FTL Council Bill of Lading spec you are consuming
enum:
- 1.0.0-TL
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 requested to be delivered.
Required when timeCriticalDetails.type is populated with any valid value.
Valid Formats: * YYYY-MM-DDTHH:mm:ss.sss (ISO 8601)
end:
type: string
example: '2021-05-22T00:00:00.000'
description: |
The end date (with or without time) of the requested delivery window.
Required when the timeCriticalDetails.type is Delivery Window.
Valid Formats: * YYYY-MM-DDTHH:mm:ss.sss (ISO 8601)
appointmentDetails:
type: object
properties:
pickup:
type: object
properties:
start:
type: string
example: '2021-05-20T00:00:00.000'
description: |
Starting appointment date (with or without time) the shipment is requested to be picked up.
Required when accessorials.code list include APTP.
Valid Formats: * YYYY-MM-DDTHH:mm:ss.sss (ISO 8601)
end:
type: string
example: '2021-05-22T00:00:00.000'
description: |
Ending appointment date (with or without time) the shipment is requested to be picked up.
Valid Formats: * YYYY-MM-DDTHH:mm:ss.sss (ISO 8601)
delivery:
type: object
properties:
start:
type: string
example: '2021-05-20T00:00:00.000'
description: |
Starting appointment date (with or without time) the shipment is requested to be delivered.
Required when accessorials.code list include APTD.
Valid Formats: * YYYY-MM-DDTHH:mm:ss.sss (ISO 8601)
end:
type: string
example: '2021-05-22T00:00:00.000'
description: |
Ending appointment date (with or without time) the shipment is requested to be delivered.
Valid Formats: * YYYY-MM-DDTHH:mm:ss.sss (ISO 8601)
origin:
type: object
required:
- name
- address1
- city
- stateProvince
- postalCode
- country
- contact
properties:
account:
type: string
description: Company's account number/id for the origin.
example: '12345'
locationId:
type: string
description: Company's location id for the origin
example: '808'
name:
type: string
description: Company name associated with the origin location.
example: Closets Closets Closets
address1:
type: string
description: Primary Address line for the origin location
example: 12 S. Closets Place
address2:
type: string
description: Secondary Address line for the origin location
example: ste 3
city:
type: string
description: City Name for the origin location
example: Los Angeles
stateProvince:
type: string
description: |
Two letter state/province code for the origin location.
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 origin 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 for the origin location.
Valid Values: See the Country_Codes schema at the bottom of this page.
contact:
type: object
description: |
Object containing contact details for the shipper.
required:
- phone
properties:
phone:
type: string
example: '5552226666'
description: |
Ten digit phone number, without country code and/or dashes, for the origin location's contact person.
Valid Formats: * ########## (10 digits - Area code + phone)
phoneExt:
type: string
example: '99'
description: Phone extensionfor the origin location's contact person.
name:
type: string
example: Jay Pritchett
description: Name of the origin location's contact person.
email:
type: string
example: jpritchett@closets.com
description: Email address of the origin location's contact person.
destination:
type: object
required:
- name
- address1
- city
- stateProvince
- postalCode
- country
- contact
properties:
account:
type: string
description: Company's account number/id for the destination.
example: '12345'
locationId:
type: string
description: Company's location id for the destination
example: '808'
name:
type: string
description: Company name associated with the destination location.
example: Closets Closets Closets
address1:
type: string
description: Primary Address line for the destination location
example: 12 S. Closets Place
address2:
type: string
description: Secondary Address line for the destination location
example: ste 3
city:
type: string
description: City Name for the destination location
example: Los Angeles
stateProvince:
type: string
description: |
Two letter state/province code for the destination location.
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 destination 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 for the destination location.
Valid Values: See the Country_Codes schema at the bottom of this page.
contact:
type: object
description: |
Object containing contact details for the destination.
required:
- phone
properties:
phone:
type: string
example: '5552226666'
description: |
Ten digit phone number, without country code and/or dashes, for the destination location's contact person.
Valid Formats: * ########## (10 digits - Area code + phone)
phoneExt:
type: string
example: '99'
description: Phone extensionfor the destination location's contact person.
name:
type: string
example: Jay Pritchett
description: Name of the destination location's contact person.
email:
type: string
example: jpritchett@closets.com
description: Email address of the destination location's contact person.
billTo:
type: object
required:
- name
- address1
- city
- stateProvince
- postalCode
- country
- contact
properties:
account:
type: string
description: Company's account number/id for the billTo.
example: '12345'
locationId:
type: string
description: Company's location id for the billTo.
example: '808'
name:
type: string
description: Company name associated with the billTo location.
example: Closets Closets Closets
address1:
type: string
description: Primary Address line for the billTo location
example: 12 S. Closets Place
address2:
type: string
description: Secondary Address line for the billTo location
example: ste 3
city:
type: string
description: City Name for the billTo location
example: Los Angeles
stateProvince:
type: string
description: |
Two letter state/province code for the billTo location.
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 billTo 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 for the billTo location.
Valid Values: See the Country_Codes schema at the bottom of this page.
contact:
type: object
description: |
Object containing contact details for the billTo.
required:
- phone
properties:
phone:
type: string
example: '5552226666'
description: |
Ten digit phone number, without country code and/or dashes, for the billTo location's contact person.
Valid Formats: * ########## (10 digits - Area code + phone)
phoneExt:
type: string
example: '99'
description: Phone extensionfor the billTo location's contact person.
name:
type: string
example: Jay Pritchett
description: Name of the billTo location's contact person.
email:
type: string
example: jpritchett@closets.com
description: Email address of the billTo location's contact person.
customsBroker:
type: object
properties:
type:
type: string
example: Import
description: |
Used to identify a customs broker that is involved in a cross-border freight move.
Valid Values: Import or Export
* Import: customs broker handling the destination-side of the cross-border freight move
* Export: customs broker handling the origin-side of the cross-border freight move
name:
type: string
description: Company name associated with the customsBroker location.
example: Closets Closets Closets
address1:
type: string
description: Primary Address line for the customsBroker location
example: 12 S. Closets Place
address2:
type: string
description: Secondary Address line for the customsBroker location
example: ste 3
city:
type: string
description: City Name for the customsBroker location
example: Los Angeles
stateProvince:
type: string
description: |
Two letter state/province code for the customsBroker location.
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 customsBroker 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 for the customsBroker location.
Valid Values: See the Country_Codes schema at the bottom of this page.
contact:
type: object
description: |
Object containing contact details for the customsBroker.
required:
- phone
properties:
phone:
type: string
example: '5552226666'
description: |
Ten digit phone number, without country code and/or dashes, for the customsBroker location's contact person.
Valid Formats: * ########## (10 digits - Area code + phone)
phoneExt:
type: string
example: '99'
description: Phone extensionfor the customsBroker location's contact person.
name:
type: string
example: Jay Pritchett
description: Name of the customsBroker location's contact person.
email:
type: string
example: jpritchett@closets.com
description: Email address of the customsBroker location's contact person.
Requestor_Roles:
title: Requestor Roles
type: string
description: |
Valid values:
* Shipper
* Consignee
* Third Party
enum:
- Shipper
- Consignee
- Third Party
BOL_Header:
title: BOL Header
type: object
required:
- requestedPickupDate
- isTest
- requestorRole
properties:
requestedPickupDate:
type: string
format: date
description: |
The intended Ship Date. NOTE this does not serve as a Pickup Request
isTest:
type: boolean
description: Indicates whether or not the submitted request is intended to be a test or not.
requestorRole:
description: |
Identifies the party making the request.
See the Requestor Roles schema for valid value descriptions.
$ref: '#/components/schemas/Requestor_Roles'
Shipping_Label_Formats:
title: Shipping Label Formats
type: string
description: |
Valid Values:
* Avery - 3-1/3" x 4" (6 labels per sheet)
* Letter - Standard letter sheet
* Zebra - 4" x 6" (1 label per sheet)
enum:
- Avery
- Letter
- Zebra
Images:
title: 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: false
includeShippingLabels:
type: boolean
description: |
Indicates whether or not you want image(s) of the shipping labels returned in the response.
default: false
shippingLabels:
type: object
properties:
format:
description: |
Specifies the printer format type for the labels.
Required when images.includeShippingLabels is true.
See the Shipping Label Formats schema for valid value descriptions.
$ref: '#/components/schemas/Shipping_Label_Formats'
quantity:
type: integer
description: |
Specifies the quantity of pages desired.
Required when images.includeShippingLabels is true.
examples:
- 5
position:
type: integer
description: |
Specifies the starting position for the shipping labels.
Required when images.shippingLabel is Avery.
minimum: 1
maximum: 6
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
includeLabels:
type: boolean
description: |
Used to request the shipping labels PDF to be sent to one or more email addresses
addresses:
type: array
description: |
Provide one or more email addresses to receive the bol and/or shipping labels PDF
items:
type: string
format: email
Notifications:
title: 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
Valid Formats:
* ########## (10 digits - Area code + phone)
examples:
- '8881234567'
pattern: ^\d{10}$
email:
type: string
format: email
description: Email address of contact for updates about shipment movements
Weight_Unit:
title: Weight Unit
type: string
enum:
- Pounds
- Kilograms
default: Pounds
description: |
The unit of measurement for weight.
ReferenceNumbers:
title: Reference Numbers
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.
examples:
- 123456-7
quoteId:
type: string
description: Quote (estimate) number provided by the carrier after submitting a rate quote request.
examples:
- E556724
shipmentId:
type: string
description: Shipment Id (SID) number for the shipment.
examples:
- SID9743985
masterBol:
type: string
description: Master Bill of Lading number for the shipment.
examples:
- 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
examples:
- BL19498432
- BL99744565
po:
type: array
items:
type: object
properties:
number:
type: string
examples:
- '554238'
description: The Purchase Order number.
pieces:
type: integer
examples:
- 5
description: Total pieces associated with the Purchase Order
weight:
type: integer
examples:
- 150
description: Total weight associated with the Purchase Order
weightUnit:
$ref: '#/components/schemas/Weight_Unit'
palletized:
type: boolean
description: Indicates whether or not the pieces associated with the purchase order are on a pallet/slip/skid or not.
additionalShipperInfo:
type: string
examples:
- Freight must always stay upright
description: Additional information from shipper per line item
additionalReferences:
type: array
items:
type: object
properties:
name:
type: string
examples:
- Customer Reference Id
description: |
Indicates the name of the reference number being provided.
value:
type: string
examples:
- CRID3452-01
description: Additional reference number that correlates to the additional reference name.
Payment_Terms:
title: Payment Terms
type: string
description: |
Valid values:
* Prepaid
* Collect
* Third Party
enum:
- Prepaid
- Collect
- Third Party
Payment:
title: Payment
type: object
required:
- terms
properties:
terms:
description: |
Freight Billing Terms for the Shipment
See the Payment Terms schema for valid value descriptions.
$ref: '#/components/schemas/Payment_Terms'
Handling_Unit_Types:
title: Handling Unit Types
type: string
description: |
Valid values:
* BAG - Bag
* BAL - Bale
* BBL - Barrel
* BSK - Basket
* BIN - Bin
* BOX - Box
* BXT - Bucket
* BCH - Bunch
* BDL - Bundle
* CAB - Cabinet
* CAG - Cage
* CAN - Can
* CBY - Carboy
* CAR - Carrier
* CTN - Carton
* CAS - Case
* CSK - Cask
* CHS - Chest
* COL - Coil
* CNT - Container
* COR - Cores
* CRT - Crate
* CYL - Cylinder
* DRM - Drum
* DBK - Dry Bulk
* ENV - Envelope
* FIR - Firkin
* GLD - Gaylord
* HPR - Hamper
* HGH - Hogshead
* HRB - On Hanger or Rack in Boxes
* INT - Intermediate Bulk Container
* JAR - Jar
* JCN - Jerrycan
* KEG - Keg
* KIT - Kit
* LIF - Lifts
* LBK - Liquid Bulk
* LSE - Loose
* MXD - Mixed
* OTH - Other
* PKG - Package
* PCK - Packed
* PAL - Pail
* PAT - Pallet
* PCS - Piece
* PLN - Pipe Line
* RCK - Rack
* REL - Reel
* ROL - Roll
* SKD - Skid
* SLP - Slip Sheet
* SPL - Spool
* TNK - Tank
* TBN - Tote
* TRY - Tray
* TRU - Truckload
* TRK - Trunk
* TUB - Tub
* TBE - Tube
* UNT - Unit
* VPK - Van Pack
* WRP - Wrapped
enum:
- BAG
- BAL
- BBL
- BSK
- BIN
- BOX
- BXT
- BCH
- BDL
- CAB
- CAG
- CAN
- CBY
- CAR
- CTN
- CAS
- CSK
- CHS
- COL
- CNT
- COR
- CRT
- CYL
- DRM
- DBK
- ENV
- FIR
- GLD
- HPR
- HGH
- HRB
- INT
- JAR
- JCN
- KEG
- KIT
- LIF
- LBK
- LSE
- MXD
- OTH
- PKG
- PCK
- PAL
- PAT
- PCS
- PLN
- RCK
- REL
- ROL
- SKD
- SLP
- SPL
- TNK
- TBN
- TRY
- TRU
- TRK
- TUB
- TBE
- UNT
- VPK
- WRP
Dimensions_Unit:
title: Dimensions Unit
type: string
enum:
- Inches
- Centimeters
default: Inches
description: |
The unit of measurement for dimensions.
Packaging_Types:
title: Packaging Types
type: string
description: |
Valid values:
* BAG - Bag
* BAL - Bale
* BBL - Barrel
* BSK - Basket
* BIN - Bin
* BOX - Box
* BXT - Bucket
* BCH - Bunch
* BDL - Bundle
* CAB - Cabinet
* CAG - Cage
* CAN - Can
* CBY - Carboy
* CAR - Carrier
* CTN - Carton
* CAS - Case
* CSK - Cask
* CHS - Chest
* COL - Coil
* CNT - Container
* COR - Cores
* CRT - Crate
* CYL - Cylinder
* DRM - Drum
* DBK - Dry Bulk
* ENV - Envelope
* FIR - Firkin
* GLD - Gaylord
* HPR - Hamper
* HGH - Hogshead
* HRB - On Hanger or Rack in Boxes
* INT - Intermediate Bulk Container
* JAR - Jar
* JCN - Jerrycan
* KEG - Keg
* KIT - Kit
* LIF - Lifts
* LBK - Liquid Bulk
* LSE - Loose
* MXD - Mixed
* OTH - Other
* PKG - Package
* PCK - Packed
* PAL - Pail
* PAT - Pallet
* PCS - Piece
* PLN - Pipe Line
* RCK - Rack
* REL - Reel
* ROL - Roll
* SKD - Skid
* SLP - Slip Sheet
* SPL - Spool
* TNK - Tank
* TBN - Tote
* TRY - Tray
* TRU - Truckload
* TRK - Trunk
* TUB - Tub
* TBE - Tube
* UNT - Unit
* VPK - Van Pack
* WRP - Wrapped
enum:
- BAG
- BAL
- BBL
- BSK
- BIN
- BOX
- BXT
- BCH
- BDL
- CAB
- CAG
- CAN
- CBY
- CAR
- CTN
- CAS
- CSK
- CHS
- COL
- CNT
- COR
- CRT
- CYL
- DRM
- DBK
- ENV
- FIR
- GLD
- HPR
- HGH
- HRB
- INT
- JAR
- JCN
- KEG
- KIT
- LIF
- LBK
- LSE
- MXD
- OTH
- PKG
- PCK
- PAL
- PAT
- PCS
- PLN
- RCK
- REL
- ROL
- SKD
- SLP
- SPL
- TNK
- TBN
- TRY
- TRU
- TRK
- TUB
- TBE
- UNT
- VPK
- WRP
Classification_Codes:
title: Classification Codes
type: string
description: |
Valid values:
* 50
* 55
* 60
* 65
* 70
* 77.5
* 85
* 92.5
* 100
* 110
* 125
* 150
* 175
* 200
* 250
* 300
* 400
* 500
* Not required
enum:
- '50'
- '55'
- '60'
- '65'
- '70'
- '77.5'
- '85'
- '92.5'
- '100'
- '110'
- '125'
- '150'
- '175'
- '200'
- '250'
- '300'
- '400'
- '500'
- Not required
Commodities:
title: Commodities
type: object
required:
- lineItemLayout
- handlingUnits
- lineItems
properties:
lineItemLayout:
type: string
enum:
- Nested
- Stacked
description: |
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
examples:
- 2
description: Number of handling units being described
type:
description: |
Type of the handling units being described
See the Handling Unit Types schema for valid value descriptions.
$ref: '#/components/schemas/Handling_Unit_Types'
tareWeight:
type: integer
examples:
- 5
description: Weight of the skids/pallets/slips used in the shipment.
weight:
type: integer
description: Total weight for the specified handling units.
examples:
- 1500
weightUnit:
$ref: '#/components/schemas/Weight_Unit'
length:
type: integer
examples:
- 48
description: The length of the handling units being described.
width:
type: integer
examples:
- 48
description: The width of the handling units being described.
height:
type: integer
examples:
- 48
description: The height of the handling units being described.
dimensionsUnit:
$ref: '#/components/schemas/Dimensions_Unit'
stackable:
type: boolean
description: |
Identifies whether or not the freight being described can be stacked on one another.
default: false
lineItems:
type: array
items:
type: object
required:
- weight
- description
- hazardous
- stackable
- pieces
- packagingType
properties:
description:
type: string
examples:
- Small frameless mirrors
description: Description of the freight being described.
weight:
type: integer
examples:
- 1500
description: Total weight for the specified lineItem.
weightUnit:
$ref: '#/components/schemas/Weight_Unit'
pieces:
type: integer
examples:
- 3
description: Number of individual pieces for the line item being described.
packagingType:
description: |
Packaging type for the individual pieces of the line item being described.
See the Packaging Types schema for valid value descriptions.
$ref: '#/components/schemas/Packaging_Types'
classification:
description: |
Classification of the line item being described.
See the Classification Codes schema for valid value descriptions.
$ref: '#/components/schemas/Classification_Codes'
nmfc:
type: string
description: NMFC code of the freight being described.
examples:
- '86900'
nmfcSub:
type: string
description: The Sub value for the NMFC of the freight being described.
examples:
- '3'
hazardous:
type: boolean
description: Identifies whether or not the freight being described contains hazardous materials.
hazardousDescription:
type: string
examples:
- 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
examples:
- 45
description: Total weight of hazardous material coveraged by one description.
weightUnit:
$ref: '#/components/schemas/Weight_Unit'
class:
type: string
examples:
- 3
description: Class that the hazardous material is catogorized by.
unnaNumber:
type: string
examples:
- UN1234
description: Proper Identification Number (UN or NA) corresponding to the Proper Shipping Name
propername:
type: string
examples:
- Anhydrous ammonia
description: |
Proper shipping name for the hazardous material.
From DOT regulations 172.101
technicalName:
type: string
examples:
- 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
examples:
- '2'
description: Hazmat Packing Group number. Not all hazmat items have a packing group
contractNumber:
type: string
examples:
- '54321'
description: The contract number with the hazardous materials contact
Currencies:
title: Currencies
type: string
description: |
Valid values:
* CAD
* MXN
* USD
enum:
- CAD
- MXN
- USD
default: USD
Shipment_Totals:
title: Shipment Totals
type: object
properties:
grossWeight:
type: integer
examples:
- 2000
description: Total weight of the entire shipment, including handling units (tare weight).
netWeight:
type: integer
examples:
- 1993
description: Total weight of the entire shipment, not including handling units (tare weight).
weightUnit:
$ref: '#/components/schemas/Weight_Unit'
handlingUnits:
type: integer
examples:
- 2
description: Handling unit count for the entire shipment
linearLength:
type: integer
description: Linear length for the entire shipment
examples:
- 576
linearWidth:
type: integer
description: Linear width for the entire shipment
examples:
- 102
linearHeight:
type: integer
description: Linear height for the entire shipment
examples:
- 60
dimensionsUnit:
$ref: '#/components/schemas/Dimensions_Unit'
cube:
type: integer
examples:
- 128
description: Cubic volume of the entire shipment (total length X total width X total height).
cubeDimensionsUnit:
type: string
enum:
- Feet
- Meters
default: Feet
description: |
The unit of measurement for cubic dimensions.
declaredValue:
type: integer
examples:
- 7
description: Total monetary value of the shipment in USD (sometimes needed for cross-border moves).
currency:
description: |
Optional attribute to indicate currency of declaredValue.
$ref: '#/components/schemas/Currencies'
Accessorial_Codes:
title: Accessorial Codes
type: string
description: |
Valid values:
* APTD - Appointment required at delivery
* APTP - Appointment required at pickup
* COD - Collect on delivery
* EXPD - Expedited Service
* FVC - Full value coverage
* GTD_AM- Guaranteed service - by Morning
* GTD_NOON- Guaranteed service - by Noon
* GTD_PM- Guaranteed service - by End of Day
* HAZ - Hazardous material
* IDL - Inside delivery
* INBD - In bond shipment
* IPU - Inside pickup
* LFTD - Lift gate required at delivery
* LFTP - Lift gate required at pickup
* LTDAD - Limited access delivery
* LTDAP - Limited access pickup
* MARK - Marked or tagged
* MNC - Must notify consignee
* OVR - Over dimension/excessive length
* PPD - Perishables (food)
* PSC - Protective from cold
* PSH - Protective from heat
* PSN - Poisonous material
* REP - Residential pickup
* RES - Residential delivery
* SRT - Sort and segregate
* SS - Single Shipment
* TCS - Time Crititcal Service
enum:
- APTD
- APTP
- COD
- EXPD
- FVC
- GTD_AM
- GTD_NOON
- GTD_PM
- HAZ
- IDL
- INBD
- IPU
- LFTD
- LFTP
- LTDAD
- LTDAP
- MARK
- MNC
- OVR
- PPD
- PSC
- PSH
- PSN
- REP
- RES
- SRT
- SS
- TCS
State_Province_Codes:
title: State/Province Codes
type: string
description: |
Valid values:
* AL - Alabama
* AK - Alaska
* AZ - Arizona
* AR - Arkansas
* CA - California
* CO - Colorado
* CT - Connecticut
* DC - District of Columbia
* DE - Delaware
* FL - Florida
* GA - Georgia
* HI - Hawaii
* ID - Idaho
* IL - Illinois
* IN - Indiana
* IA - Iowa
* KS - Kansas
* KY - Kentucky
* LA - Louisiana
* ME - Maine
* MD - Maryland
* MA - Massachusetts
* MI - Michigan
* MN - Minnesota
* MS - Mississippi
* MO - Missouri
* MT - Montana
* NE - Nebraska
* NV - Nevada
* NH - New Hampshire
* NJ - New Jersey
* NM - New Mexico
* NY - New York
* NC - North Carolina
* ND - North Dakota
* OH - Ohio
* OK - Oklahoma
* OR - Oregon
* PA - Pennsylvania
* PR - Puerto Rico
* RI - Rhode Island
* SC - South Carolina
* SD - South Dakota
* TN - Tennessee
* TX - Texas
* UT - Utah
* VT - Vermont
* VA - Virginia
* WA - Washington
* WV - West Virginia
* WI - Wisconsin
* WY - Wyoming
* AB - Alberta
* BC - British Columbia
* MB - Manitoba
* NB - New Brunswick
* NL - Newfoundland and Labrador
* NS - Nova Scotia
* NT - Northwest Territories
* NU - Nunavut
* ON - Ontario
* PE - Prince Edward Island
* QC - Quebec
* SK - Saskatchewan
* YT - Yukon
* CMX - Mexican Federal District
* AGU - Aguascalientes
* BCN - Baja California
* BCS - Baja California Sur
* CAM - Campeche
* COA - Coahuila
* COL - Colima
* CHP - Chiapas
* CHH - Chihuahua
* DUR - Durango
* GUA - Guanajuato
* GRO - Guerrero
* HID - Hidalgo
* JAL - Jalisco
* MEX - Mexico
* MIC - Michoacan
* MOR - Morelos
* NAY - Nayarit
* NLE - Nuevo Leon
* OAX - Oaxaca
* PUE - Puebla
* QUE - Queretaro
* ROO - Quintana Roo
* SLP - San Luis Potosi
* SIN - Sinaloa
* SON - Sonora
* TAB - Tabasco
* TAM - Tamaulipas
* TLA - Tlaxcala
* VER - Veracruz
* YUC - Yucatan
* ZAC - Zacatecas
enum:
- AL
- AK
- AZ
- AR
- CA
- CO
- CT
- DC
- DE
- FL
- GA
- HI
- ID
- IL
- IN
- IA
- KS
- KY
- LA
- ME
- MD
- MA
- MI
- MN
- MS
- MO
- MT
- NE
- NV
- NH
- NJ
- NM
- NY
- NC
- ND
- OH
- OK
- OR
- PA
- PR
- RI
- SC
- SD
- TN
- TX
- UT
- VT
- VA
- WA
- WV
- WI
- WY
- AB
- BC
- MB
- NB
- NL
- NS
- NT
- NU
- 'ON'
- PE
- QC
- SK
- YT
- CMX
- AGU
- BCN
- BCS
- CAM
- COA
- COL
- CHP
- CHH
- DUR
- GUA
- GRO
- HID
- JAL
- MEX
- MIC
- MOR
- NAY
- NLE
- OAX
- PUE
- QUE
- ROO
- SLP
- SIN
- SON
- TAB
- TAM
- TLA
- VER
- YUC
- ZAC
Country_Codes:
title: Country Codes
type: string
description: |
Three letter country code
Valid values:
* CAN - Canada
* USA - United States
* MEX - Mexico
enum:
- CAN
- USA
- MEX
AddressInformation:
title: Address Information
type: object
properties:
name:
type: string
description: Company name.
examples:
- Closets Closets Closets
address1:
type: string
description: Primary Address line
examples:
- 12 S. Closets Place
address2:
type: string
description: Secondary Address line
examples:
- ste 3
city:
type: string
description: City Name
examples:
- Los Angeles
stateProvince:
$ref: '#/components/schemas/State_Province_Codes'
postalCode:
type: string
examples:
- '90001'
description: |
The 5-digit + 4 or 5-digit for the United States, 5-digit for Mexico, or 6-character for Canada, postal code
Valid formats:
* 12345-1234 (5 digits + 4 - USA)
* 12345 (5 digits - USA/MEX)
* A1A1A1 (6 characters - CAN)
* A1A1A (5 characters - CAN)
country:
$ref: '#/components/schemas/Country_Codes'
Limited_Access_Types:
title: Limited Access Types
type: string
description: |
Valid Values:
* Airport
* Airport-3 - Airport Cargo
* Church
* Church-55 - Place of Worship
* Club
* Club-21 - Country Club / Golf Course
* Club-60 - Private Club
* Construction
* Construction-17 - Construction Site
* Fair
* Fair-27 - Fairgrounds
* Farm
* Farm-30 - Fruit Orchard
* Farm-62 - Pumpkin Patch / Vegetable Patch
* Farm-87 - Winery
* Hotel
* Hotel-14 - Casino
* Hotel-35 - Hotel
* Hotel-41 - Lodging
* Hotel-47 - Motel / Inn
* Hotel-54 - Parking Lot / Garage
* Hotel-65 - Resort
* Hotel-66 - Restaurant / Bar
* Mine
* Mine-46 - Mine / Quarry
* Other
* Other-6 - Book Store
* Other-7 - Bowling Alley
* Other-8 - Brewery
* Other-9 - Business Park
* Other-12 - Car Rental
* Other-13 - Car Wash
* Other-19 - Convenience Store
* Other-23 - Daycare
* Other-24 - Dealership
* Other-25 - Distillery
* Other-26 - Factory Outlet
* Other-28 - Fast Food
* Other-31 - Funeral Home
* Other-33 - Gym / Fitness Center
* Other-38 - Laundry / Dry Cleaner
* Other-40 - Liquor Store
* Other-42 - Mall
* Other-48 - Native American Reservation
* Other-52 - Other
* Other-67 - Retail Store
* Other-68 - Salon / Barber
* Other-72 - Shopping Center
* Other-75 - Specialty Food Store
* Other-78 - Theater
* Other-80 - Truck Stop
* Other-83 - Vet / Kennel
* Park
* Park-4 - Amusement Park
* Park-5 - Aquarium
* Park-10 - Camp
* Park-11 - Campground / RV Park
* Park-15 - Cemetery
* Park-53 - Park
* Park-64 - Recreational
* Park-73 - Ski Resort
* Park-76 - Sports Venue
* Park-77 - State / National Park
* Park-88 - Zoo
* Port
* Port-22 - Cruise Line Terminal
* Port-29 - Ferry
* Port-43 - Marina
* Port-57 - Port
* School
* School-34 - Hospital
* School-36 - Junior College
* School-39 - Library / Museum
* School-44 - Medical Facility
* School-50 - Nursing Home / Assisted Living
* School-56 - Police / Fire / Rescue
* School-61 - Public Transit Station
* School-69 - School
* School-70 - School District Office
* School-79 - Trade School
* School-81 - University / College
* Secure
* Secure-32 - Government Site
* Secure-37 - Junkyard / Landfill
* Secure-45 - Military Base
* Secure-49 - Nuclear Power Plant
* Secure-51 - Oil / Gas
* Secure-58 - Power Plant
* Secure-59 - Prison / Detention Center
* Secure-63 - Rail Yard
* Secure-74 - Solar Power Farm
* Secure-82 - Utility Site
* Secure-84 - Waste Transfer Station
* Secure-85 - Water Treatment Plant
* Secure-86 - Wind Power Farm
* Storage
* Storage-18 - Container Freight Station
* Storage-71 - Self Storage Warehouse
* Tradeshow
* Tradeshow-16 - Conference Center
* Tradeshow-20 - Convention Center
enum:
- Airport
- Airport-3
- Church
- Church-55
- Club
- Club-21
- Club-60
- Construction
- Construction-17
- Fair
- Fair-27
- Farm
- Farm-30
- Farm-62
- Farm-87
- Hotel
- Hotel-14
- Hotel-35
- Hotel-41
- Hotel-47
- Hotel-54
- Hotel-65
- Hotel-66
- Mine
- Mine-46
- Other
- Other-6
- Other-7
- Other-8
- Other-9
- Other-12
- Other-13
- Other-19
- Other-23
- Other-24
- Other-25
- Other-26
- Other-28
- Other-31
- Other-33
- Other-38
- Other-40
- Other-42
- Other-48
- Other-52
- Other-67
- Other-68
- Other-72
- Other-75
- Other-78
- Other-80
- Other-83
- Park
- Park-4
- Park-5
- Park-10
- Park-11
- Park-15
- Park-53
- Park-64
- Park-73
- Park-76
- Park-77
- Park-88
- Port
- Port-22
- Port-29
- Port-43
- Port-57
- School
- School-34
- School-36
- School-39
- School-44
- School-50
- School-56
- School-61
- School-69
- School-70
- School-79
- School-81
- Secure
- Secure-32
- Secure-37
- Secure-45
- Secure-49
- Secure-51
- Secure-58
- Secure-59
- Secure-63
- Secure-74
- Secure-82
- Secure-84
- Secure-85
- Secure-86
- Storage
- Storage-18
- Storage-71
- Tradeshow
- Tradeshow-16
- Tradeshow-20
Time_Critical_Types:
title: Time Critical Types
type: string
description: |
Valid Values:
* Deliver On Date - Freight can only be delivered on the specified start date.
* Deliver On or After Date - Freight can only be delivered on or after the specified start date.
* Deliver By Date - Freight can only be delivered up to, and including, the specified start date.
* Delivery Window - Freight can only be delivered between the specified start and end dates.
enum:
- Deliver On Date
- Deliver On or After Date
- Deliver By Date
- Delivery Window
Accessorials:
title: Accessorials
type: object
properties:
codes:
type: array
description: |
An array to hold the list of services requested for the shipment
items:
$ref: '#/components/schemas/Accessorial_Codes'
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
examples:
- Manny Delgato
description: Full name of who should be contacted in the case of a hazardous materials-related issue.
phone:
type: string
examples:
- '7775558899'
pattern: ^\d{10}$
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 (Collect on delivery) is present in the accessorial.codes list.
properties:
amount:
type: number
format: double
description: |
Amount to be received for the COD.
currency:
description: |
Optional attribute to indicate currency of COD. Defaults to USD.
$ref: '#/components/schemas/Currencies'
terms:
type: string
enum:
- Prepaid
- Collect
description: |
Payment terms associated with the COD (Collect on delivery).
customerCheckAcceptable:
type: boolean
description: Indicates whether or not a customer check or cash is acceptable.
remitTo:
description: |
Required when accessorial code COD (Collect on delivery) is present in the accessorial.codes list.
$ref: '#/components/schemas/AddressInformation'
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
examples:
- 25
fullValueCoverageDetails:
type: object
description: |
Required when accessorial code FVC is present in the accessorial.codes list.
properties:
monetaryValue:
type: number
format: double
description: |
Value of the cargo.
currency:
description: |
Optional attribute to indicate currency of monetaryValue.
$ref: '#/components/schemas/Currencies'
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
examples:
- 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:
description: |
Optional attribute to indicate the limited access type when accessorial code LTDAP is present in the accessorial.codes list.
See the Limited Access Types schema for valid value descriptions.
$ref: '#/components/schemas/Limited_Access_Types'
destination:
description: |
Optional attribute to indicate the limited access type when accessorial code LTDAD is present in the accessorial.codes list.
See the Limited Access Types schema for valid value descriptions.
$ref: '#/components/schemas/Limited_Access_Types'
timeCriticalDetails:
type: object
properties:
type:
description: |
Type of delivery required for the requested Time Critical Service.
Required when accessorials.code list include TCS.
See the Time Critical Types schema for valid value descriptions.
$ref: '#/components/schemas/Time_Critical_Types'
date:
type: object
properties:
start:
type: string
format: date-time
description: |
The date (with or without time) the shipment is requested to be delivered.
Required when timeCriticalDetails.type is populated with any valid value.
end:
type: string
format: date-time
description: |
The end date (with or without time) of the requested delivery window.
Required when the timeCriticalDetails.type is Delivery Window.
appointmentDetails:
type: object
properties:
pickup:
type: object
properties:
start:
type: string
format: date-time
description: |
Starting appointment date (with or without time) the shipment is requested to be picked up.
Required when accessorials.code list include APTP.
end:
type: string
format: date-time
description: |
Ending appointment date (with or without time) the shipment is requested to be picked up.
delivery:
type: object
properties:
start:
type: string
format: date-time
description: |
Starting appointment date (with or without time) the shipment is requested to be delivered.
Required when accessorials.code list include APTD.
end:
type: string
format: date-time
description: |
Ending appointment date (with or without time) the shipment is requested to be delivered.
ContactInformation:
title: Contact Information
allOf:
- $ref: '#/components/schemas/AddressInformation'
- type: object
properties:
contact:
type: object
description: |
Object containing contact details
required:
- phone
properties:
phone:
type: string
examples:
- '5552226666'
pattern: ^\d{10}$
description: |
Ten digit phone number, without country code and/or dashes
Valid Formats: * ########## (10 digits - Area code + phone)
phoneExt:
type: string
examples:
- '99'
description: Phone extension
name:
type: string
examples:
- Jay Pritchett
description: Name of the contact person.
email:
type: string
format: email
description: Email address of the contact person.
Origin:
title: Origin
allOf:
- type: object
properties:
account:
type: string
description: Company's account number/id for the origin.
examples:
- '12345'
locationId:
type: string
description: Company's location id for the origin
examples:
- '808'
required:
- name
- address1
- city
- stateProvince
- postalCode
- country
- contact
- $ref: '#/components/schemas/ContactInformation'
Destination:
title: Destination
allOf:
- type: object
properties:
account:
type: string
description: Company's account number/id for the destination.
examples:
- '12345'
locationId:
type: string
description: Company's location id for the destination
examples:
- '808'
required:
- name
- address1
- city
- stateProvince
- postalCode
- country
- contact
- $ref: '#/components/schemas/ContactInformation'
BillTo:
title: Bill To
allOf:
- type: object
properties:
account:
type: string
description: Company's account number/id for the billTo.
examples:
- '12345'
locationId:
type: string
description: Company's location id for the billTo.
examples:
- '808'
required:
- name
- address1
- city
- stateProvince
- postalCode
- country
- contact
- $ref: '#/components/schemas/ContactInformation'
CustomsBroker:
title: Customs Broker
type: object
properties:
type:
type: string
examples:
- Import
description: |
Used to identify a customs broker that is involved in a cross-border freight move.
Valid Values: Import or Export
* Import: customs broker handling the destination-side of the cross-border freight move
* Export: customs broker handling the origin-side of the cross-border freight move
allOf:
- type: object
properties:
type:
type: string
enum:
- Import
- Export
description: |
Used to identify a customs broker that is involved in a cross-border freight move.
Valid Values: Import or Export
* Import: customs broker handling the destination-side of the cross-border freight move
* Export: customs broker handling the origin-side of the cross-border freight move
- $ref: '#/components/schemas/ContactInformation'
BOL_Request-2:
title: FTL BOL Request
description: The request object for creating or updating an Electronic Bill of Lading.
type: object
required:
- bol
- commodities
- payment
- origin
- destination
- billTo
properties:
bol:
$ref: '#/components/schemas/BOL_Header'
images:
$ref: '#/components/schemas/Images'
notifications:
$ref: '#/components/schemas/Notifications'
referenceNumbers:
$ref: '#/components/schemas/ReferenceNumbers'
payment:
$ref: '#/components/schemas/Payment'
commodities:
$ref: '#/components/schemas/Commodities'
shipmentTotals:
$ref: '#/components/schemas/Shipment_Totals'
accessorials:
$ref: '#/components/schemas/Accessorials'
origin:
$ref: '#/components/schemas/Origin'
destination:
$ref: '#/components/schemas/Destination'
billTo:
$ref: '#/components/schemas/BillTo'
customsBroker:
$ref: '#/components/schemas/CustomsBroker'
specialInstructions:
type: string
examples:
- Gate code 123 to enter complex
description: Special delivery instructions that need to be followed for the shipment's delivery.
Result_Status_Codes:
description: |
Numerical codes describing any logical status outcomes. Not all codes apply to this API, but are included to encourage adoption of these standards across API specifications.
Valid Values:
* 100 - Informational General Information {{addl_info}}
* 200 - Warning Non-Critical Error {{addl_info}}
* 300 - Failure Data Error {{addl_info}}
* 400 - Failure Formatting Error {{addl_info}}
* 500 - Failure Business Logic Error {{addl_info}}
* 600 - Failure Carrier Specific Error {{addl_info}}
* 700 - Failure Outside Ship Window {{addl_info}}
* 800 - Failure No Freight - Will be re-attempted {{addl_info}}
* 900 - Failure No Freight - Pick UP Closed {{addl_info}}
* 1000 - Failure Freight Not ready {{addl_info}}
* 1100 - Failure Packaging Problem {{addl_info}}
* 1200 - Failure BoL PDF Image Not Created {{addl_info}}
* 1300 - Failure Label PDF Image not Created {{addl_info}}
* 1400 - Failure Duplicate Pro {{addl_info}}
* 1500 - Failure Unknown Reason {{addl_info}}
* 1600 - Failure Shipper Closed {{addl_info}}
* 1700 - Failure Duplicate PO {{addl_info}}
BOL_Response:
title: LTL BOL Response
type: object
properties:
version:
type: string
example: 2.1.0
description: Indicates which version of the Digital LTL Council Bill of Lading spec was returned
transactionDate:
type: string
example: '2022-11-20T00:00:00.000'
description: The date associated with this electronic bill of lading transaction.
referenceNumbers:
type: object
properties:
pro:
type: string
example: PRO1234
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.
shipmentConfirmationNumber:
type: string
example: SCN1234
description: Number provided by the carrier to acknowledge they accepted the BOL.
scac:
type: string
example: AAAB
description: 4-letter, Standard Carrier Alpha Code, returned by the carrier.
images:
type: object
properties:
bol:
type: string
description: Base 64 encoded PDF of the populated Bill Of Lading. Any bar code within the image(s) should include the check digit when applicable.
example: JVBERi0xLjcKCjQgMCBvYmoKPDwKL0JpdHNQZXJDb21wb25lbnQgOAovQ29sb3JTcGFjZSAvRGV2a......
shippingLabels:
type: string
description: Base 64 encoded PDF of the populated shipping Labels. Any bar code within the image(s) should include the check digit when applicable.
example: JVBERi0xLjcKCjQgMCBvYmoKPDwKL0JpdHNQZXJDb21wb25lbnQgOAovQ29sb3JTcGFjZSAvRGV2a......
termsAndConditions:
type: string
example: Terms and Conditions text available for download at www.myurl-nmfta.org
description: 'Add terms and conditions here if desired, or a link to your terms and conditions. '
messageStatus:
type: object
description: Object containing message status details.
properties:
status:
type: string
description: |
Indicates the status of the request.
PASS - Request is successful with no exceptions.
FAIL - Request is unsuccessful due to some exception.
WARNING - Request is successful with some exception.
example: PASS
code:
type: string
description: Indicates response detail code.
example: '10000000'
message:
type: string
description: Provides information pertaining to the response code.
example: Transaction was successful.
resolution:
type: string
description: Provides guidance pertaining to the response code.
example: ''
information:
type: array
items:
type: object
properties:
code:
type: string
type:
type: string
message:
type: string
example: []
resultStatusCodes:
description: Error response
type: array
items:
$ref: '#/components/schemas/Result_Status_Codes'
Result_Status_Codes-2:
title: Result Status Codes
type: string
description: |
Numerical codes describing any logical status outcomes. Not all codes apply to this API, but are included to encourage adoption of these standards across API specifications.
Valid Values:
* 100 - Informational General Information
* 200 - Warning Non-Critical Error
* 300 - Failure Data Error
* 400 - Failure Formatting Error
* 500 - Failure Business Logic Error
* 600 - Failure Carrier Specific Error
* 700 - Failure Outside Ship Window
* 800 - Failure No Freight - Will be re-attempted
* 900 - Failure No Freight - Pick UP Closed
* 1000 - Failure Freight Not ready
* 1100 - Failure Packaging Problem
* 1200 - Failure BoL PDF Image Not Created
* 1300 - Failure Label PDF Image not Created
* 1400 - Failure Duplicate Pro
* 1500 - Failure Unknown Reason
* 1600 - Failure Shipper Closed
* 1700 - Failure Duplicate PO enum:
- '100'
- '200'
- '300'
- '400'
- '500'
- '600'
- '700'
- '800'
- '900'
- '1000'
- '1100'
- '1200'
- '1300'
- '1400'
- '1500'
- '1600'
- '1700'
BOL_Response-2:
title: FTL BOL Response
type: object
properties:
transactionDate:
type: string
format: date
description: The date associated with this electronic bill of lading transaction.
referenceNumbers:
allOf:
- type: object
properties:
shipmentConfirmationNumber:
type: string
examples:
- SCN1234
description: Number provided by the carrier to acknowledge they accepted the BOL.
- $ref: '#/components/schemas/ReferenceNumbers'
scac:
type: string
examples:
- AAAB
description: 4-letter, Standard Carrier Alpha Code, returned by the carrier.
images:
type: object
properties:
bol:
type: string
description: Base 64 encoded PDF of the populated Bill Of Lading. Any bar code within the image(s) should include the check digit when applicable.
examples:
- JVBERi0xLjcKCjQgMCBvYmoKPDwKL0JpdHNQZXJDb21wb25lbnQgOAovQ29sb3JTcGFjZSAvRGV2a......
shippingLabels:
type: string
description: Base 64 encoded PDF of the populated shipping Labels. Any bar code within the image(s) should include the check digit when applicable.
examples:
- JVBERi0xLjcKCjQgMCBvYmoKPDwKL0JpdHNQZXJDb21wb25lbnQgOAovQ29sb3JTcGFjZSAvRGV2a......
termsAndConditions:
type: string
examples:
- Terms and Conditions text available for download at www.myurl-nmfta.org
description: 'Add terms and conditions here if desired, or a link to your terms and conditions. '
messageStatus:
type: object
description: Object containing message status details.
properties:
status:
type: string
description: |
Indicates the status of the request.
PASS - Request is successful with no exceptions.
FAIL - Request is unsuccessful due to some exception.
WARNING - Request is successful with some exception.
enum:
- PASS
- FAIL
- WARNING
code:
type: string
description: Indicates response detail code.
examples:
- '10000000'
message:
type: string
description: Provides information pertaining to the response code.
examples:
- Transaction was successful.
resolution:
type: string
description: Provides guidance pertaining to the response code.
information:
type: array
items:
type: object
properties:
code:
type: string
type:
type: string
message:
type: string
resultStatusCodes:
description: Error response
type: array
items:
$ref: '#/components/schemas/Result_Status_Codes-2'