Reference

API endpoints

All paths below are relative to https://api.bolscan.app/api/v1.

Production API

Integrate BolScan into your logistics system

Use sandbox keys for testing. For real production OCR, higher limits, storage behavior, webhooks, and rollout support, message us with your use case and expected monthly BOL volume.

Contact on WhatsApp
MethodPathPurpose
POST/extractSubmit a BOL document.GET/jobs/{job_id}Read job status.GET/bols/{bol_id}Retrieve extracted data.GET/bols/{bol_id}/downloadDownload original file.GET/bolsList recent BOL records.GET/languagesList supported OCR languages.
POST/extract

Submit a BOL document.

Sandbox keys return completed mock data without storing the file. Production keys store the original document and queue OCR.

Authentication

Header
Type
Description
X-API-Key
string
Required for every extraction endpoint

Form Data

Name
Type
Description
file
File
Required PDF or image
language
string
auto, en, zh-hans, zh-hant, es, ar, fr, de, ja, ko
include_cargo_items
boolean
Default true
confidence_threshold
number
Default 0.70
webhook_url
string
Optional completion callback

Response

{
  "job_id": "job_a1b2c3d4e5f6",
  "status": "queued",
  "estimated_seconds": 10,
  "created_at": "2026-05-25T20:30:00"
}
GET/jobs/{job_id}

Read job status.

Returns progress and failure information for a submitted extraction job.

Authentication

Header
Type
Description
X-API-Key
string
Required for every extraction endpoint

Response

{
  "job_id": "job_a1b2c3d4e5f6",
  "status": "processing",
  "progress_percent": 50,
  "current_step": "extraction"
}
GET/bols/{bol_id}

Retrieve extracted data.

Use bol_id by replacing the job_ prefix with bol_.

Authentication

Header
Type
Description
X-API-Key
string
Required for every extraction endpoint

Response

{
  "bol_id": "bol_a1b2c3d4e5f6",
  "status": "completed",
  "carrier_detected": "MAERSK",
  "overall_confidence": 0.95,
  "fields": {
    "bol_number": {
      "value": "MAEU9876543",
      "confidence": 0.95
    }
  }
}
GET/bols/{bol_id}/download

Download original file.

Production jobs return a 302 redirect to a temporary file URL. Sandbox jobs do not have an original file.

Authentication

Header
Type
Description
X-API-Key
string
Required for every extraction endpoint

Response

See endpoint description for response behavior.

GET/bols

List recent BOL records.

Supports limit and offset query parameters.

Authentication

Header
Type
Description
X-API-Key
string
Required for every extraction endpoint

Response

See endpoint description for response behavior.

GET/languages

List supported OCR languages.

Returns language codes, display names, and RTL flags.

Authentication

Header
Type
Description
X-API-Key
string
Required for every extraction endpoint

Response

See endpoint description for response behavior.