border.bot
Esc
  • Loading…
↑ ↓ to move↵ to openEsc to close
Docs menu

API reference

Generate an air waybill PDF

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

Requires an access token from an API client (Authorization: Bearer <access_token>).

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 client 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 Description
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 or expired access token, or a revoked or expired API client (unauthorized). (Error)
  • 402: Not enough credits (insufficient_credits). Nothing was charged. (Error)
  • 403: Workspace suspended, action disabled, or the client 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 request#

curl -X POST https://api.border.bot/v1/documents/waybill \
  -H "Authorization: Bearer $BORDERBOT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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
  }'

Example response (200)#

JSON
{
  "data": {
    "number": "125-1234 5675",
    "filename": "AWB-125-12345675.pdf",
    "pages": 6,
    "contentType": "application/pdf",
    "pdf": "string"
  },
  "credits": {
    "charged": 0,
    "remaining": 0,
    "usageId": "string"
  },
  "replayed": false
}