Sending BOLs and Shipment Files

This guide describes how to submit your Bills of Lading (BOLs) and shipment documents to our system via SFTP.

Prefer HTTPS? Submit the same metadata and PDFs directly with the BOL Ingestion API.

Connect via SFTP

Secure file transfer

Package as Zip

One zip per load

Include Index File

JSON metadata required

SFTP Connection

All files must be transmitted over SFTP (SSH File Transfer Protocol). You will receive connection credentials during onboarding. Upload your zip files to the designated directory on the SFTP server.

Protocol:SFTP

Host:Provided during onboarding

Port:22

Authentication:Username + SSH key or password

Zip File Structure

Each load must be packaged as a single .zip file. The zip must contain an index.json file along with all referenced shipment documents (PDFs).

shipment_1001538844.zip

index.json(required)

131187Bol.pdf(Bill of Lading)

131187Packing.pdf(Packing List)

Important: Every file referenced in the attachments.files array of your index.json must be present in the zip archive. Mismatched filenames will cause processing errors.

Index File Specification

The index.json file must be a valid JSON document. The root object must contain a shipmentMetadata key containing an array of shipment objects with their details and file references.

shipmentMetadata Fields

Matching keys

Send at least one of bolNumber or shipmentNumber. Sending both gives the best match rate.

Field	Type	Required	What it does
bolNumber	string	One of	Bill of Lading number (e.g. "08934172000451263"). Primary key for deduplication and appointment matching.
shipmentNumber	string	One of	Shipment tracking number (e.g. "1001538844"). Secondary dedupe key and appointment-matching candidate.

Parties

Field	Type	Required	What it does
carrierId	string	Required	Links the shipment to a carrier. SCAC or carrier identifier (e.g. "FDXT").
carrierName	string	Optional	Full name of the carrier company (e.g. "Truck Systems Inc").
shipperId	string	Required	Links the shipment to the origin facility (e.g. "US123").
shipper	string	Optional	Name or address of the shipper (e.g. "Fort Worth, TX 76177").
customerId	string	Optional	Unique identifier for the customer (e.g. "RETAIL00").
customerName	string	Optional	Full name of the customer (e.g. "NATIONAL RETAILER").
receiverId	string	Optional	Unique identifier for the receiver (e.g. "RETAIL01").
receiver	string	Optional	Name and location of the receiver (e.g. "NATIONAL RETAILER NY").

Identification numbers

Field	Type	Required	What it does
deliveryNumbers	string[]	Optional	Delivery reference numbers (e.g. ["1234567899", "1234567900"]).
orderNumbers	string[]	Optional	Order numbers associated with the shipment.
poNumbers	string[]	Optional	Purchase order numbers associated with the shipment.
proNumber	string	Optional	Carrier PRO number (e.g. "1234567899").
sealNumber	string	Optional	Seal number on the shipment trailer (e.g. "12218008").

Equipment & status

Field	Type	Required	What it does
shipmentTrailerNumber	string	Optional	Trailer identifier used for the shipment (e.g. "NF13589").
podStatus	string	Optional	Proof of delivery status: "Not Applicable", "Pending", "Signed", or "Rejected".

Attachments

Field	Type	Required	What it does
attachments.files[]	object[]	Required	At least one document. Each entry describes a PDF included in the zip.
files[].name	string	Required	Filename of the PDF in the zip (e.g. "131187Bol.pdf"). Must match a file in the archive.
files[].type	string	Required	Document type: "Bill of Lading", "Packing List", "Proof of Delivery", or "Invoice".

What blocks ingestion

Only four things are required: at least one attachment, one of bolNumber / shipmentNumber, shipperId (to link the facility), and carrierId (to link the carrier). Every other field is optional and will not block ingestion.

Full Example

A complete, valid index.json file:

index.json

{
  "shipmentMetadata": [
    {
      "bolNumber": "08934172000451263",
      "carrierId": "FDXT",
      "carrierName": "FedEx Freight (FDXT)",
      "customerId": "4821",
      "customerName": "Example Retail Holdings",
      "deliveryNumbers": ["554218763"],
      "orderNumbers": ["91820456", "91820479"],
      "poNumbers": ["4509821345", "4509821371"],
      "podStatus": "Not Applicable",
      "receiver": "TARGET DC 0551",
      "receiverId": "TARGET DC 0551",
      "sealNumber": "7721",
      "shipmentNumber": "50918422",
      "shipmentTrailerNumber": "TR8472",
      "shipper": "Example Distribution Center",
      "shipperId": "4821",
      "proNumber": "774512908",
      "attachments": {
        "files": [
          {
            "name": "554218763_20260317114532.pdf",
            "type": "Bill of Lading"
          },
          {
            "name": "554218763_20260317114532_packing.pdf",
            "type": "Packing List"
          }
        ]
      }
    }
  ]
}

Validate Your File

Use this tool to check your index.json before uploading. It validates JSON syntax, required fields, data types, and attachment structure.

index.json Validator

Paste your index.json content or drop a .json file to validate it against the shipment metadata schema.

Upload File