Generate an air waybill PDF | border.bot API docs

POST https://staging-api.border.bot/v1/documents/waybill

Requires an API key (Authorization: Bearer bb_live_…).

A master or house air waybill on the IATA Resolution 600a face, with the Resolution 600b conditions of contract after each copy (conditions), as 3 originals or the full set of 8 (copies). Validated before charging: a wrong check digit or non-Latin text answers 400 without a charge. The PDF is an unsigned draft until the issuing carrier or its agent executes it, and acceptance by any airline, agent or authority is not guaranteed: use is subject to the Terms’ Shipping documents section (https://border.bot/legal/terms#shipping-documents). Costs 1 credit.

API key scope: documents.

Headers#

Name	Type	Required	Description
`idempotency-key`	string	no	Make retries safe: a repeat with the same key returns the original result without charging again (keys are scoped to your workspace).

Request body (JSON)#

Name	Type	Required
`kind`	"master" \| "house"	no
`prefix`	string	no
`number`	string	yes
`masterNumber`	string	no
`shipper`	object	yes
`consignee`	object	yes
`issuer`	object	yes
`agent`	object	no
`accountingInformation`	string	no
`departure`	string	yes
`departureName`	string	no
`destination`	string	yes
`destinationName`	string	no
`routing`	object[]	no
`firstCarrierName`	string	no
`flights`	string[]	no
`referenceNumber`	string	no
`optionalShippingInformation`	string	no
`currency`	string	yes
`weightValuation`	"PP" \| "CC"	no
`otherChargesPaid`	"PP" \| "CC"	no
`declaredValueCarriage`	number	no
`declaredValueCustoms`	number	no
`insurance`	number	no
`handlingInformation`	string	no
`sci`	string	no
`weightUnit`	"kg" \| "lb"	no
`dimensionUnit`	"cm" \| "in"	no
`volumeDivisor`	integer	no
`lines`	object[]	yes
`otherCharges`	object[]	no
`valuationCharge`	number	no
`tax`	number	no
`shipperSignature`	string	no
`executedOn`	string (date)	yes
`executedAt`	string	yes
`carrierSignature`	string	no
`copies`	"originals" \| "full"	no
`conditions`	boolean	no

Responses#

200: The PDF (base64) and the credits charged. (AirWaybillResponse)
400: Invalid input (invalid_input). (Error)
401: Missing, invalid, revoked or expired API key (unauthorized). (Error)
402: Not enough credits (insufficient_credits). Nothing was charged. (Error)
403: Workspace suspended, action disabled, or the key lacks the scope (org_suspended, action_disabled, forbidden). (Error)
409: A request with this Idempotency-Key is still in progress (conflict). (Error)
429: Rate limited (rate_limited). Retry after Retry-After seconds; RateLimit says which limit was hit (r=0, t seconds until its window ends) and RateLimit-Policy its quota. (Error)
500: Unexpected error (internal). (Error)
502: The engine failed (upstream_error). The credits are refunded automatically. (Error)
504: The engine timed out (upstream_timeout). The credits are refunded automatically. (Error)

Example#

bash

curl -X POST 'https://staging-api.border.bot/v1/documents/waybill' \
  -H 'Authorization: Bearer bb_live_...' \
  -H 'Content-Type: application/json' \
  -d '{"kind":"master","prefix":"125","number":"12345675","shipper":{"name":"Northwind Apparel Ltd","address":"Unit 4, Bath Road Trading Estate","city":"Hounslow","postcode":"TW4 6HG","country":"GB","phone":"+44 20 7946 0000"},"consignee":{"name":"Harbor Street Retail Inc","address":"1200 Harbor Street, Suite 300","city":"Los Angeles","postcode":"CA 90021","country":"US","phone":"+1 213 555 0100"},"issuer":{"name":"British Airways World Cargo","address":"Heathrow Airport, Hounslow TW6 2JS"},"agent":{"name":"Skyline Forwarding Ltd","city":"London","iataCode":"91-4 7712/0010"},"accountingInformation":"FREIGHT PREPAID","departure":"LHR","departureName":"London Heathrow","destination":"LAX","destinationName":"Los Angeles","routing":[{"to":"LAX","by":"BA"}],"firstCarrierName":"British Airways","flights":["BA0283/14OCT"],"currency":"GBP","weightValuation":"PP","otherChargesPaid":"PP","handlingInformation":"NOTIFY CONSIGNEE ON ARRIVAL. COMMERCIAL INVOICE AND PACKING LIST ATTACHED.","sci":"X","lines":[{"pieces":4,"grossWeight":86.4,"rateClass":"Q","rate":3.85,"description":"Cotton knitted T-shirts and hoodies, 480 units","hsCodes":["610910","611020"],"dimensions":[{"pieces":4,"length":60,"width":40,"height":45}]}],"otherCharges":[{"code":"AW","dueTo":"A","amount":25},{"code":"MY","dueTo":"C","amount":51.84},{"code":"SC","dueTo":"C","amount":12.96}],"shipperSignature":"Skyline Forwarding Ltd","executedOn":"2026-10-13","executedAt":"London","copies":"originals","conditions":true}'