Set Up Cargo and Shipper Fields for Bills of Lading

Configure bill of lading fields in the dashboard — extract shipper, consignee, cargo tables, and hazmat flags from shipping documents.

Ready to set this up? Sign up for PerfectParser and get 20 free credits — no credit card required.

What this guide helps you do

This guide shows how to configure a bill of lading parser in PerfectParser, define shipper, consignee, and cargo fields, run a test batch, and export logistics data. Leave the prompt blank on the first auto-detect pass unless you need tighter control over party and cargo field names.

Why bills of lading are hard to parse

Bills of lading mix party blocks, routing metadata, and cargo tables in formats that vary by carrier and trade lane. Shipper and consignee names sit in labeled boxes that OCR often reads out of order, especially on scanned ocean BOLs. Origin and destination may be labeled "Port of Loading" and "Place of Delivery" on one form and "Pickup" / "Delivery" on another. Cargo tables split weight, piece count, and description across columns with inconsistent units (kg vs lbs). Hazmat declarations appear as checkbox flags, marginal notes, or UN numbers embedded in description text. Multi-stop shipments attach rider pages with additional cargo lines. Vessel name and voyage number are frequently confused with BOL number in auto-detect unless field descriptions are explicit.

Recommended Fields

We suggest configuring the following schema fields for your Bill of Lading Parser to capture all essential logistics and cargo data.

Field Name	Type	Description
`bol_number`	Text	The unique Bill of Lading reference number.
`shipper_name`	Text	The company or exporter shipping the goods.
`consignee_name`	Text	The buyer or company receiving the goods.
`carrier_name`	Text	The freight line or transport carrier (e.g., DHL, Maersk).
`ship_date`	Text	The date the cargo was shipped.
`origin_port`	Text	Port of loading or pickup location.
`destination_port`	Text	Port of discharge or delivery destination.
`total_weight`	Text	The overall gross weight of the cargo.
`cargo_items`	Table	Table containing `package_count`, `weight`, `description`, and `hazmat` status for each cargo unit.

AI Prompt (Optional)

Use this only when you want to guide auto-detect toward a specific set of fields.

If you want PerfectParser to discover additional fields on its own, leave the AI Prompt (Optional) box blank for the first pass, review the detected schema, then add a prompt only if you need tighter consistency.

When you do use a prompt, copy and paste the following instructions into the AI Prompt (Optional) field during setup:

Extract the BOL number, shipper name, consignee name, carrier name, ship date, origin port, destination port, and total gross weight. Also extract the cargo items table containing the package count, individual weight, description of goods, and whether it is hazardous materials (hazmat).

Set up this parser in the dashboard

Create a parser

Go to Parsers → New Parser in the dashboard. Give it a name like "Bill of Lading Parser" and optionally select the document category.

Upload a sample document

Drag and drop a representative bill of lading (PDF, PNG, or JPEG). Use a real BOL from your freight workflow — the AI uses it to learn party block and cargo table placement.

Detect fields or use standard fields

Paste the AI Prompt from the section above into the AI Prompt (Optional) box if you want tighter field mapping, then click Auto-Detect. To discover more fields automatically, leave the prompt blank and click Auto-Detect. Or skip auto-detect and add fields manually using the Recommended Fields table above.

Review and save your schema

Check that shipper and consignee are separate fields and that cargo_items includes a hazmat column if you handle regulated freight. Confirm bol_number is not confused with booking or container numbers. Click Save.

Run a test batch

Navigate to Bulk Extraction, choose how your files are organised, upload a small test set of BOLs, and click Extract All Files. Review the results in Batch History and export to CSV or Excel.

Common mistakes

Swapping shipper_name and consignee_name because both appear in similar boxed regions on the form.
Omitting the hazmat column from cargo_items when compliance workflows depend on UN number or hazmat flag extraction.
Mapping vessel name or voyage reference into bol_number — add explicit field descriptions to disambiguate.
Skipping cargo_items and capturing only total_weight — you lose piece-level detail needed for customs or warehouse receiving.

Next steps

Test your first extraction free — sign up for PerfectParser, no credit card needed.

FAQs

Do I need a sample bill of lading to set up this parser?

Yes. Upload a BOL that matches your freight mode — ocean, air, or domestic trucking layouts differ. Include a sample with a cargo item table and hazmat notation if your workflow handles regulated goods.

Should shipper and consignee be separate fields?

Always define shipper_name and consignee_name as separate Text fields. They appear in adjacent blocks on most BOLs and are easy to swap if field descriptions are vague. Never merge them into a single 'party' field.

How many credits does setup and a test extraction use?

Parser setup is free. Each BOL page costs 1 credit. Single-page domestic BOLs use 1 credit; multi-page ocean bills of lading with attached rider pages cost 1 credit per page.