Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.0.0
info:
title: BNSF Waybill Management API
description: 'Electronic waybill management for carload shipments: submit a bill of lading with the required transit information
and retrieve the current active waybill for a given piece of equipment.'
termsOfService: http://www.bnsf.com/site-terms-of-use.html
contact:
name: BNSF Customer API
email: CustomerAPI@bnsf.com
version: '1.0'
servers:
- url: https://api.bnsf.com:6443
description: Production
- url: https://api-trial.bnsf.com:6443
description: Trial
paths:
/v1/bol:
post:
tags:
- Waybill Management
summary: Submit Bill of Lading - Submit required transit information in order to create a waybill/bill of lading (BOL).
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/billOfLading'
responses:
'200':
description: '**OK**
The request has succeeded.'
'201':
description: '**Created**
The request successfully created a new resource. '
'400':
description: '**Bad Request**
The request could not be understood by the server due to incorrect syntax. Do not repeat the request without modifications.'
content:
application/json:
schema:
type: array
items:
type: object
properties:
timestamp:
type: string
example: 2020-08-13T21:26:36.977+0000
internalErrorId:
type: string
example: '20003'
httpStatusCode:
type: string
example: '400'
message:
type: string
example: BOL submission invalid
messageLabel:
type: string
example: Invalid STCC code
'403':
description: "**Forbidden**\n\nUnauthorized request. Here are the most common causes:\n \n* You are getting 403\
\ Access Denied.\n\n * It takes a few days for us to get you set up after you register. When set up is complete,\
\ you will receive an email letting you know. If you have not received the email, please wait up to five business\
\ days. Let us know via API Support if you still have not received the email after five business days.\n * You\
\ can also get this error if your certificate is not configured properly on your side. Please review the Mutual\
\ Authentication in the Getting Started section of our documentation.\n\n\n* You are getting 403 \"message\":\
\ \"Insufficient privileges\" when accessing a restricted service for which you do not have permission. You can\
\ use our Registration form to request access. Be sure to explain the situation in the \"Please explain how you\
\ intend to use the API\" field."
'404':
description: '**Not Found**
The server cannot find the requested resource (URI). That is, the address of the endpoint in your request does
not exist. Please consult the documentation.'
'405':
description: '**Method Not Allowed**
The request HTTP method is known by the server but has been disabled and cannot be used for that resource. For
example, you may be using GET when POST is required. Please consult the documentation.'
'429':
description: "**Too Many Requests**\n\nThe BNSF API Gateway enforces rate limits to maintain application security\
\ and performance. Current rate limits are set as follows:\n* 1 API Request Per Second, Per Partner, Per Service\n\
* 15 API Requests Per Minute, Per Partner, Per Service\n* 100 API Request Per Minute, Per Service\n \nWhen requests\
\ exceed these limits the API Gateway will return a **429 Too Many Requests** error response. Upon receiving such\
\ exceptions, you can resubmit failed requests in a rate-limited manner, complying with the API Gateway throttle\
\ limits. "
'500':
description: '**Internal Server Error**
The server encountered an unexpected condition which prevented it from fulfilling the request. This is always
a problem on the server side. Our internal support systems will be made aware.'
'504':
description: '**Gateway Timeout**
The server is acting as a gateway and cannot get a response in time for a request. Wait about one minute then
try again.'
security:
- Restricted: []
operationId: postV1Bol
/v1/waybill:
get:
tags:
- Waybill Management
summary: Retrieve Waybill - Retrieve current active waybill/bill of lading information for a given equipment.
description: '<b>Changelog</b>
<ul>
<li>November 17, 2021: Added customerWaybillReferenceNumbers array.</li>
</ul>
'
parameters:
- name: equipmentInitial
in: query
description: Equipment initial.
required: true
schema:
type: string
example: BNSF
- name: equipmentNumber
in: query
description: Equipment number.
required: true
schema:
type: string
example: '12345'
responses:
'200':
description: '**OK**
The request has succeeded.'
content:
application/json:
schema:
$ref: '#/components/schemas/Waybill_Details'
'400':
$ref: '#/components/responses/400'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
'405':
$ref: '#/components/responses/405'
'429':
$ref: '#/components/responses/429'
'500':
$ref: '#/components/responses/500'
'504':
$ref: '#/components/responses/504'
operationId: getV1Waybill
components:
schemas:
billOfLading:
type: object
properties:
billOfLading:
type: object
properties:
billOfLadingEdiQualifierCode:
type: string
description: 'EDI Shipment Qualifier Code is an EDI-defined qualifier code value specifying the relationship
a shipment with respect to other shipments given to the carrier at the same time.
Sample Values Include: 1 (Master Bill for Empty Non-Revenue Equipment), 2 (Sea Waybill), E (Empty Equipment
Billing (Non-Revenue)), I (Intermodal)
**EDI Mapping:** DE147/BX07'
example: E
billOfLadingEdiWeightMethodTypeCode:
type: string
description: 'EDI Weight Method Type Code is an EDI-defined code value indicating the method by which freight
conveyance equipment weights are obtained for a shipment.
Sample Values Include: C (Consignee Scale Weight), E (Estimated Weight), H (Public Scale Weight on Behalf
of Shipper), O (Official Weight)
**EDI Mapping:** DE460/BNX01
'
example: C
billOfLadingEdiWeightUomCode:
type: string
description: 'EDI Weight Unit of Measure Code is an EDI-defined code value specifying the weight unit of an
associated measurement.
Sample Values Are: E (Metric Ton), G (Grams), K (Kilograms), L (Pounds), M (Measurement Ton), O (Ounces),
S (Short Ton), T (Long Ton)
**EDI Mapping:** DE188/BX06
'
example: L
billOfLadingEdiMethodOfPaymentCode:
type: string
description: 'EDI Method of Payment Code is an EDI-defined code value specifying payment terms for transportation
charges.
Sample Values Include: 11 (Association of American Railroads Accounting Rule 11 Shipment), CC (Collect), MX
(Mixed), NC (Service Freight, No Charge), NR (Non Revenue), PP (Prepaid (by Seller))
**EDI Mapping:** DE146/BX03
'
example: PP
billOfLadingEdiTransactionSetPurposeCode:
type: string
description: 'EDI Transaction Set Purpose Code is an EDI-defined code value specifying the purpose of an associated
transaction set.
Sample Values Include: 00 (Original), 04 (Change)
**EDI Mapping:** DE353/BX01
'
example: '00'
billOfLadingEdiTransportationTypeCode:
type: string
description: 'Is an EDI-defined code value specifying the method or type of transportation for a shipment.
**EDI Mapping:** DE91/ZC108/BX02
'
example: X
billOfLadingEdiSectionSevenCode:
type: string
description: 'Is an EDI-defined code value indicating the applicability of the section seven option on a shipment.
'
example: F
billOfLadingEdiBillingTypeCode:
type: string
description: Is an EDI-defined code value which indicates a type of bill.
example: S
equipmentEdiReleaseCode:
type: string
description: "EDI Equipment Release Code is an EDI-defined code value signifying whether or not the shipment\
\ information transaction set includes instructions for pickup and movement of the shipment.\r\r\n"
example: R
equipmentReleaseDateTime:
type: string
description: 'Equipment Release DateTime records the date and time which a shipper''s equipment is released
to BNSF.
'
example: '2021-03-06T21:17:07.187Z'
equipmentReleaseDateTimeOffsetNumber:
type: string
description: 'Equipment Release DateTime Offset Number is the amount of time subtracted from or added to the
Coordinated Universal Time to get the time supplied for the equipment release date-time.
'
example: CT
billOfLadingCargoManifests:
type: array
items:
type: object
properties:
billOfLadingCargoManifestSequenceNumber:
type: number
format: float
description: 'BOL Cargo Manifest Sequence Number allows for more than one Cargo Manifest per BOL. The
EDI standard allows for a maximum of two. '
example: 1
voyageNumber:
type: string
description: Identifying designator number for the particular ocean movement on which the cargo travels.
example: 537S
oceanPortFunctionalCode:
type: string
description: Code defining function performed at the port with respect to a shipment.
example: L
oceanPortName:
type: string
description: Free-form name for the place at which an offshore carrier/vessel originates or terminates
its actual ocean carriage of property.
example: LONGBEACH
vesselSailDockEdiDate:
type: string
format: date
description: The date the ship will sailed or docked at the port. Present if Ocean Port Functional Code
contains a 'L", 'D' or '1'.
example: '2022-09-01'
vesselBookingNumber:
type: string
description: Number assigned by the carrier for space reservation on a voyage.
example: LGB700188300
currentScac:
type: string
description: Current SCAC (Standard Carrier Alpha Code) provided by EDI
example: BNSF
previousScac:
type: string
description: Previous SCAC (Standard Carrier Alpha Code) provided by EDI
example: BNSF
billOfLadingManifestDate:
type: string
format: date
description: The date the manifest was established by the shipper.
example: '2022-09-01'
vesselName:
type: string
description: Name of the vessel as documented in "Lloyd's Register of Ships".
example: ANL BAREGA
oceanPierNumber:
type: string
description: Identifying number for the pier located within the Ocean Port Name.
example: '1234'
oceanPierName:
type: string
description: Identifying name for the pier located within the Ocean Port Name.
example: SANTIAGO
oceanTerminalName:
type: string
description: Identifying name for the terminal located within the Ocean Port Name.
example: ANL BAREGA
oceanTerminalStateCode:
type: string
description: Identifying state code for the terminal located within the Ocean Port Name.
example: CA
oceanTerminalCountryCode:
type: string
description: Identifying country code for the terminal located within the Ocean Port Name.
example: US
cargoManifestReferenceId:
type: string
description: Cargo Manifest Reference ID is a reference identifier for Vessel Agent Number.
example: CM123456
billOfLadingCommodities:
type: array
description: 'Specifies a shipment''s lading information for each commodity in terms of description, marks,
and numbers.
**EDI Mapping:** LX,L5
'
items:
type: object
properties:
billOfLadingCommoditySequenceNumber:
type: number
format: float
description: 'Is a sequence number that in combination with BOL ID and BOL Commodity Sequence Number,
uniquely identifies a row on the BOL Commodity Detail element.
'
example: 1
billOfLadingTransactionSetAssignedNumber:
type: number
format: float
description: 'Is a number assigned for differentiation within a BOL transaction set.
**EDI Mapping:** DE554/LX01
'
example: 1
ladingLineItemNumber:
type: number
format: float
description: 'Lading Line Item Number is the sequential line number for a lading item within a shipment.
**EDI Mapping:** DE213/L501
'
example: 1
stcc:
type: string
description: 'STCC (Standard Transportation Commodity Code) assigned to a lading commodity or group of
lading commodities.
**EDI Mapping:** DE22/L503
'
example: '4611110'
stccEdiQualifierCode:
type: string
description: 'Is an EDI-defined code value that identifies the commodity coding system used for an associated
Commodity Code.
Sample Values Include: 0 (National Association of Convenience Stores), 1 (Global Product Classification
Code (GPC)), 2 (Dun s SIC 2+2, Dun and Bradstreet), 3 (Empty Non-hazardous Last Contained (HMRC) Code)
**EDI Mapping:** DE23/L504/L508
'
example: '3'
ladingDescription:
type: string
description: 'Lading Description describes a lading item as required for rating and billing purposes.
**EDI Mapping:** DE79/L502
'
example: STANDARD NON-HAZARDOUS FREIGHT ALL KINDS
billOfLadingCommodityDetails:
type: array
description: 'Specifies a shipment''s detailed lading information for each line item, including packaging,
quantity, weight, and volume.
**EDI Mapping:** L0
'
items:
type: object
properties:
billOfLadingCommodityDetailSequenceNumber:
type: number
format: float
description: 'Is a sequence number that in combination with BOL ID and BOL Commodity Sequence Number,
uniquely identifies a row on the BOL Commodity Detail element.
'
example: 1
ladingQuantityCount:
type: number
format: float
description: 'Number of units (pieces) of the lading commodity.
**EDI Mapping:** DE80/X110
'
example: 1
ladingEdiPackagingFormCode:
type: string
description: 'Is an EDI-defined code value specifying the packaging form of a lading quantity.
Sample Values Include: BLK (Bulk), CAR (Carrier), CNT (Container), CRT (Crate), PLT (Pallet)
**EDI Mapping:** DE211/L009/L014
'
example: BLK
ladingWeight:
type: number
format: float
description: 'Lading Weight is a measure of the weight of a lading item. This must be qualified
with a code defining the unit of measure to be meaningful.
**EDI Mapping:** DE81/L004
'
example: 29118
ladingEdiWeightQualifierCode:
type: string
description: 'Is an EDI-defined code value that identifies the manner in which the weight of a piece
of freight conveyance equipment was calculated.
Sample Values Include: A (Consolidated Weight), B (Billed Weight), L (Legal Weight), N (Actual
Net Weight)
**EDI Mapping:** DE187/L005
'
example: A
ladingVolume:
type: number
format: float
description: 'Lading Volume is a volumetric measure of a lading item. This must be qualified with
a code defining the unit of measure used to be meaningful.
**EDI Mapping:** DE183/L006
'
example: 0
ladingEdiVolumeUnitCode:
type: string
description: 'Is an EDI-defined qualifier code value that provides context to a volume measurement.
Sample Values Include: C (Cubic Centimeters), E (Cubic Feet), G (Gallons), M (Cubic Decimeters)
**EDI Mapping:** DE184/L007
'
example: C
billOfLadingPrices:
type: array
description: 'Relates a line item in a shipment to the authority document, contract number, quote
number, and tariff number which are used to determine the basis of pricing.
**EDI Mapping:** LX Loop/LX,L0,PI
'
items:
type: object
properties:
billOfLadingPriceSequenceNumber:
type: number
format: float
description: 'Is a sequence number that is needed to uniquely identify a price associated
with a commodity on the BOL.
'
example: 1
billOfLadingLineItemPriceReferenceEdiQualifierCode:
type: string
description: 'Is an EDI-defined qualifier code value that provides context to the value present
in the EDI Reference ID column.
**EDI Mapping:** DE128/PI01
'
example: CT
billOfLadingLineItemPriceReferenceId:
type: string
description: 'Is a reference identification number for the BOL Price element.
**EDI Mapping:** DE127/PI02
'
example: QTTFDXFXF
publicationAuthorityEdiTypeCode:
type: string
title: publicationAuthorityEdiTypeCode
description: 'Is an EDI-defined code value that specifies the type of external price publication
provided for a line item in a shipment.
Sample Values Are: BR (Backward Reference), DR (Division Reference), GR (Group Reference),
OP (Other Publication), RR (Rate Reference), TP (Tariff Publication)
**EDI Mapping:** DE436/PI03
'
example: BR
priceAuthorityAgencyCode:
type: string
description: "Price Authority Agency Code is a code value, as defined by the National Motor\
\ Freight Traffic Association, specifying the tariff bureau or tariff publishing agent that\
\ governs the pricing/rates applied to a shipment.\n\nCodes sourced from the Directory of\
\ Standard Carrier Alpha Codes (SCAC), NMF 101 Series, available from the National Motor\
\ Freight Traffic Association, Inc.\n\n**EDI Mapping:** DE168/PI05 \n"
example: BNSF
priceAuthorityIssuingCarrierId:
type: string
description: 'Price Authority Issuing Carrier ID is an identification label used to identify
the issuing carrier of a price authority specified on a shipment.
**EDI Mapping:** DE965/PI06
'
example: BNSF
billOfLadingExportLicenses:
type: array
items:
type: object
properties:
billOfLadingExportLicenseSequenceNumber:
type: number
format: float
description: In combination with a BOL ID, uniquely identifies a row in the BOL Export License element.
example: 1
licensingAgencyEdiCode:
type: string
description: Is an EDI-defined code value used to identify a licensing, certification, registration,
or accreditation agency associated with a commodity being shipped.
example: '1'
exportLicenseId:
type: string
description: Export License ID is a government assigned identification number for exporter.
example: License1
exportLicenseEdiStatusCode:
type: string
description: Is an EDI-defined code value specifying whether the shipment completes the terms of
the export license, or the shipment is only a partial delivery relative to the license terms.
example: '1'
exportLicenseExpirationDate:
type: string
format: date
description: Is the day, month, and year when an export license expires (expressed as CCYYMMDD where
CC represents the first two digits of the calendar year).
example: '2022-01-01'
exportLicenseEdiSymbolCode:
type: string
description: Is an EDI-defined code value which specifies the export license symbol marked on a
shipment.
example: A1
exportLicenseEdiControlCode:
type: string
description: Is an EDI-defined code value specifying the type of control applicable to an export
license.
exportLicenseCountryCode:
type: string
description: Export License Country Code is an ISO 3166 code value specifying a country, dependency,
or geopolitical area in which an exporter operates.
example: US
commodityScheduleBNumber:
type: string
description: "Schedule B Number is a classification and identification code for commodities for\
\ use by exporters in preparing Shippers Export Declarations.\r\n\r\nThe code is a ten digit numeric\
\ of the form dddd.dd.dddd. \r\n\r\nCodes sourced from the Schedule B Statistical Classification\
\ of Domestic and Foreign Commodities Exported from the United States, 1990 Edition. Maintained\
\ by the U.S. Bureau of the Census."
example: A12
billOfLadingEdiInternationalDomesticCode:
type: string
description: Is an EDI-defined code value specifying whether a shipment is international or domestic.
example: A
ladingQuantityCount:
type: number
format: float
description: Lading Quantity Count is a count of the number of units (pieces) of the lading commodity.
example: 2900
ladingValueAmount:
type: number
format: float
description: Lading Value Amount specifies the monetary value of a shipment for export, expressed
in the standard monetary denomination for the currency specified.
example: 29.1
exportLicenseEdiFilingKeyCode:
type: string
description: Is an EDI-defined code value specifying whether the information contained on an export
license has been filed with Customs via an automatic or manual process.
example: '1'
ediUomCode:
type: string
description: Is an EDI-defined code value specifying the units in which a value is being expressed,
or manner in which a measurement has been taken.
example: AB
ladingUnitPrice:
type: number
format: float
description: Lading Unit Price is the price per unit of a commodity.
example: 2.1
usGovernmentLicenseTypeCode:
type: string
description: The type of U.S. government license being used on the export license associated with
a shipment.
example: A
eccn:
type: string
description: Export Control Classification Number is a designation used on the Commerce Control
List (CCL) to identify dual-use items for export control purposes.
example: AN993993
exportDeclarationLocationScheduledCode:
type: string
example: TX90345
billOfLadingEquipment:
type: array
description: 'Provides detail information about the rail conveyance equipment on the BOL.
**EDI Mapping:** N7 Loop/L0,N7,T2
'
items:
type: object
required:
- equipmentId
- equipmentLoadEmptyStatusCode
- equipmentExteriorLengthFeetInches
properties:
billOfLadingEquipmentSequenceNumber:
type: number
format: float
description: "Is a sequence number that in combination with BOL Identifer, uniquely identifies a piece\
\ of freight conveyance equipment on a BOL.\r\nThe purpose of the sequence number is to preserve the\
\ order of equipment as supplied on the EDI 404 or other channel. Sequence values should start from\
\ one (1) and increment by one for each piece of equipment on the request."
example: 1
equipmentId:
type: string
description: 'Equipment ID serves as an identifier for a piece of freight conveyance equipment. It consists
of a 4-character equipment initial followed by an up to 15-character equipment unit identifying number.
**EDI Mapping:** DE206-207/N804/N805
'
example: FDXU532684
equipmentLoadEmptyStatusCode:
type: string
description: 'Load Empty Status Code is used to convey whether a piece of rail conveyance equipment (i.e.,
a railcar) is being shipped while laden with cargo or while empty, as is the case if it does not pick
up another load at its destination.
'
example: L
equipmentEdiWeightQualifierCode:
type: string
description: 'EDI Weight Qualifier Code
# --- truncated at 32 KB (134 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bnsf/refs/heads/main/openapi/bnsf-waybill-openapi.yml