Stop Guessing. Build Your Supply Chain Automation on Verifiable Coordinate Proof.
This comprehensive guide provides production-ready code for extracting bill of lading data with verifiable coordinate proof. Learn how to implement coordinate-backed extraction that provides both structured data and visual verification of data provenance.
Introduction
This comprehensive guide provides production-ready code for extracting bill of lading data with coordinate-backed verification. The implementation demonstrates how to obtain both structured data extraction and visual proof of data provenance, enabling the development of auditable logistics workflows.
15-Minute Setup
Copy our code and start processing BoLs today.
Build Trust
Get coordinate proof for every field. Never guess where data came from.
Eliminate Templates
Our AI adapts to any BoL layout, saving you from constant maintenance.
The Problem: 'Black Box' APIs Create Supply Chain Bottlenecks
Traditional OCR and generic AI APIs provide JSON output but create significant verification challenges. Without coordinate proof, there is no reliable method to validate whether extracted values such as `cargo_weight: "500kg"` are accurate or represent erroneous field detection.
This limitation necessitates the implementation of costly manual review processes, which undermines the efficiency benefits of automation. The fundamental challenge is not merely data extraction, but obtaining verifiable data suitable for regulatory compliance and supply chain tracking requirements.
Prerequisites
Before you start, you'll need:
- Ninjadoc Account & API Key: Sign up at ninjadoc.ai to get your API key
- BoL Processor: Create a document processor in your dashboard by asking questions like "What is the shipment number?" and "What is the cargo description?"
- PDF Upload: A bill of lading PDF file (digital or scanned, up to 50MB)
Security Note
Compatibility
Two Approaches: SDK vs Direct API
Ninjadoc offers two ways to integrate document processing into your application. Choose based on your needs:
🔧 SDK Approach (Recommended)
- • Best for: Full applications with UI components
- • Security: API keys stay server-side
- • Features: Built-in polling, overlays, error handling
- • Setup: Requires BFF routes in your app
- • Maintenance: Automatic updates with SDK
⚡ Direct API Approach
- • Best for: Server-side processing, quick prototypes
- • Security: Keep API key server-side only
- • Features: Full control over requests/responses
- • Setup: Simple fetch calls
- • Maintenance: Manual implementation
Important: Both approaches keep your API key secure by making calls from your server, not the browser. The SDK approach adds convenience and UI components at the cost of setting up BFF routes.
Quick Start Examples
Rather than developing brittle parsing rules for each carrier's document layout, the system employs natural language questions to train the AI. This approach creates a reusable processor that comprehends the semantic context of bill of lading documents, rather than relying on fixed positional coordinates.
Important
Implementation Examples
// Direct API Call (Server-side only - keep API key secure)
const formData = new FormData();
formData.append('document', bolFile);
formData.append('processor_id', 'your-bol-processor-uuid');
const response = await fetch('/api/extract', {
method: 'POST',
headers: { 'X-API-Key': process.env.NINJADOC_API_KEY },
body: formData
});
const job = await response.json();
console.log('Job started:', job.id);
The Workflow: From Raw BoL to Auditable Data
This production-ready function implements the complete extraction workflow. It manages document submission, result polling with exponential backoff, and structured JSON parsing that includes coordinate verification for each extracted field, ensuring data integrity for downstream logistics systems.
Reliability Tips
- • Use exponential backoff when polling (implemented above)
- • Set timeouts and implement retry logic for network failures
- • Handle partial results and flag documents for manual review when critical fields are missing
- • Monitor processing times and adjust polling intervals based on document size
Production-Ready Processing Function
// The full production workflow: Submit BoL -> Poll for Data -> Verify with Coordinates
async function processBoL(bolFile, processorId) {
try {
// 1. Submit the bill of lading and get a job ID
const formData = new FormData();
formData.append('document', bolFile);
formData.append('processor_id', processorId);
const submitResponse = await fetch('/api/extract', {
method: 'POST',
headers: { 'X-API-Key': process.env.NINJADOC_API_KEY },
body: formData
});
if (!submitResponse.ok) throw new Error(`Submit failed: ${submitResponse.status}`);
const job = await submitResponse.json();
// 2. Poll for completion until status is final (with exponential backoff)
let result;
let pollInterval = 2000;
const maxInterval = 30000;
do {
await new Promise(resolve => setTimeout(resolve, pollInterval));
const statusResponse = await fetch(`/api/jobs/${job.id}/status`, {
headers: { 'X-API-Key': process.env.NINJADOC_API_KEY }
});
if (!statusResponse.ok) throw new Error(`Status check failed: ${statusResponse.status}`);
result = await statusResponse.json();
// Exponential backoff with jitter
pollInterval = Math.min(pollInterval * 1.5 + Math.random() * 1000, maxInterval);
} while (['queued', 'processing'].includes(result.status));
if (result.status !== 'completed') throw new Error(`BoL processing failed: ${result.status}`);
// 3. Extract and structure the data for your logistics system
// API Response format for each field: { field_name, value, coordinates: [[x,y], ...] }
const extractedData = result.data.reduce((acc, f) => {
acc[f.field_name] = { value: f.value, coordinates: f.coordinates };
return acc;
}, {});
// You can now use this data for tracking, customs clearance, or verification UI
if (!extractedData.shipment_number?.value || !extractedData.cargo_description?.value) {
// Flag this BoL for manual review
throw new Error('Missing critical data for shipment processing');
}
return { success: true, data: extractedData };
} catch (error) {
console.error('BoL processing failed:', error);
return { success: false, error: error.message };
}
}
Frequently Asked Questions
Why are coordinates the most important part of a BoL API?
They build trust. Without coordinates, you're just getting a 'best guess' from a black box. With coordinates, you get undeniable proof. This allows you to build verification tools that show your logistics team *exactly* where the data came from, which is critical for customs compliance and dramatically speeds up manual reviews.
We get BoLs from hundreds of carriers. Do I really not need a template for each one?
Correct. Our AI understands the context and common patterns of bills of lading. It finds data based on your questions (e.g., 'what is the cargo weight?'), not on fixed coordinates. This means one 'BoL Processor' can handle countless layout variations from all your carriers, saving you from endless maintenance.
How does your API handle complex cargo line items?
Our AI is trained to recognize tabular structures. You can specify to 'extract all cargo items' and specify the columns you need ('description', 'quantity', 'weight', 'value'). The API will return a structured array of each item, each with its own value and coordinate proof.
What's the pricing model? Is it expensive?
It's simple pay-as-you-go. Plans start at just $10 for 4,500 credits. Credits never expire and there are no monthly subscriptions. 25 Credits per page + 5 Credits per field. Start with 1,250 free welcome credits!
What happens with scanned vs. digital PDFs?
Our AI handles both equally well. Scanned documents are automatically OCR'd before processing, and our coordinate system works the same way regardless of the source. Digital PDFs often have better accuracy due to cleaner text extraction.
What are the file size and page limits?
We support PDFs up to 50MB and 100 pages. For larger documents, we recommend splitting them before upload. Processing time scales with document size, but most BoLs complete within 30 seconds.
How do I handle multi-document bundles?
You can process multiple documents in a single API call by including them all in your FormData. Each document gets its own job ID and results. For very large bundles, consider processing them sequentially to manage rate limits.
Further reading
- →Document Overlay Guide: Build interactive PDF viewers with coordinate proof
- →Invoice Processing API Guide: Extract invoice data with coordinate proof
- →Ninjadoc vs Docsumo: developer-first Q&A vs enterprise workflows
- →Ninjadoc vs AWS Textract: developer-first Q&A vs foundation-model extraction
- →Complete API Documentation: SDK reference and examples
Ready to Implement Verifiable Data Extraction?
Integrate coordinate-backed bill of lading extraction to establish trust and efficiency in your supply chain operations.
- 1,250 Free Credits on Registration
- No Credit Card Required
- Production-Ready Code Examples
Implementation Steps: Register for an account, upload a sample bill of lading document, and test extraction with a query such as 'What is the cargo weight?' Evaluate the coordinate-verified results to determine suitability for your logistics workflow requirements.