OSOW Quote API

Overview

One endpoint, POST /api/v1/quotes, prices an oversize/overweight lane: send origin, destination, and dimensions; get back per-state permit fees, escort counts, police / superload / survey / utility flags, and lane totals.

• Coverage: the lower 48 states. Canadian lanes are in the calculator but not on the API yet; they return unsupported_region rather than a guess.
• Same numbers as the calculator: same engine, same state data, same rate logic. Rates default to your account’s saved Bid Builder config (one exception, noted in rates).
• Latency: typically 2 to 5 seconds. The lane is routed live and priced through every state it crosses; this is a quote engine, not a cache lookup. Parallel requests are fine.

Quickstart

A real 7-axle load, 134″ wide, 161″ tall, 134,075 lbs, Savannah GA to Birmingham AL. Four required fields: idempotency_key, origin, destination, dims.

curl -X POST https://osowloads.com/api/v1/quotes \
  -H "Authorization: Bearer osow_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotency_key": "lane-2041-rev1",
    "origin": "Savannah, GA",
    "destination": "Birmingham, AL",
    "dims": {
      "length_in": 960,
      "width_in": 134,
      "height_in": 161,
      "weight_lbs": 134075,
      "axles": 7
    }
  }'

Abridged response (... marks omitted fields; the response reference lists everything):

{
  "quote_id": "q_01M0SWMHBB36QW785RH1014XJE",
  "engine": "here",
  "route_mi": 470.7,
  "total_permits": 100,
  "total_escorts": 0,
  "states": [
    { "abbr": "GA", "mi": 365.5, "permit": 30, "permit_status": "priced", "escRequired": "No", "escRequiredQty": "", "escTravelingQty": 0, ... },
    { "abbr": "AL", "mi": 104.4, "permit": 70, "permit_status": "priced", "escRequired": "No", "escRequiredQty": "", "escTravelingQty": 0, ... }
  ],
  "assumptions": [
    { "field": "dims.trailer_length_in", "applied": 720,
      "rule": "trailer_length_in not supplied: total length minus 240 in (20 ft), floor 0" },
    { "field": "rates", "applied": { "escort_dpm": 1.85, ... },
      "rule": "unspecified rates fall back to the account Bid Builder config (exceptions: service_fee_per_state defaults to 0; esl_mode defaults to 1)" }
  ],
  "warnings": [],
  "meta": {
    "data_version": "statesv3@2026-08-15",
    "rate_card": { "escort_dpm": 1.85, ... },
    "usage": { "charge": "allowance", "remaining_allowance": 199, "remaining_lot_credits": 0 }
  }
}

Authentication

Bearer key in the Authorization: Bearer osow_live_… header. Keys are minted from your dashboard (org owners, any paid plan) and shown once; we store only a hash, so a lost key means revoke and re-mint. Treat it like a password: server-side only, never in client code or a public repo.

Create a quote

Prices one lane and charges one call on success. Unknown fields are rejected with a 422 rather than ignored, so a typo fails loudly instead of silently skewing a quote. Bodies over 64 KB are rejected. When you omit an optional field that affects the math, the default we applied is reported back in assumptions[].

Idempotency & retries

Every POST includes an idempotency_key: a receipt number you make up (any string up to 128 chars). It is not your API key. It makes retries safe — you cannot double-bill yourself:

Billing & limits

Prepaid, no surprise bills. One successful quote = one call. Not charged: errors of any kind, replays of an already-answered request, and any quote where our own data or routing could not answer (a state with permit_status: “unavailable”). Charged: everything else that returns 200 — including lanes where a state is agency_priced or not_permittable, because that determination is the answer. Every response shows where you stand in meta.usage.

Examples & resources

Three real request/response pairs from the production API — a four-field minimum, a typical quote with a rate card, and a fully specified request — so you can see what each level of input buys you before writing a line of code.

{
  "idempotency_key": "devdemo-2026-08-24-l1",
  "origin": "Charlotte, NC",
  "destination": "Nashville, TN",
  "dims": {
    "length_in": 900,
    "width_in": 106,
    "height_in": 160,
    "weight_lbs": 66188
  }
}

{
  "quote_id": "q_01M0TRVP17S28F9X27RXVDVM5W",
  "idempotency_key": "devdemo-2026-08-24-l1",
  "client_ref": null,
  "metadata": null,
  "engine": "here",
  "route_mi": 423.4,
  "total_permits": 32,
  "total_escorts": 0,
  "total_survey": 0,
  "total_service": 0,
  "any_super": "No",
  "super_qty": "",
  "any_police": "No",
  "police_qty": "",
  "any_survey": "No",
  "survey_qty": "",
  "any_engr": "No",
  "engr_qty": "",
  "any_util": "No",
  "util_qty": "",
  "orig_tier_flag": "no",
  "orig_tier_note": "",
  "dest_tier_flag": "no",
  "dest_tier_note": "",
  "states": [
    {
      "abbr": "NC",
      "mi": 177.3,
      "permit": 12,
      "permit_status": "priced",
      "permit_label": null,
      "permit_reason": null,
      "permit_note": null,
      "extras": "",
      "escRequired": "No",
      "escRequiredQty": "",
      "escTravelingQty": 0,
      "superload": "No",
      "police": "No",
      "policeQty": "",
      "survey": "No",
      "engr": "No",
      "engrType": "",
      "util": "No",
      "utilType": "",
      "tooltips": null
    },
    {
      "abbr": "TN",
      "mi": 245.3,
      "permit": 20,
      "permit_status": "priced",
      "permit_label": null,
      "permit_reason": null,
      "permit_note": null,
      "extras": "",
      "escRequired": "No",
      "escRequiredQty": "",
      "escTravelingQty": 0,
      "superload": "No",
      "police": "No",
      "policeQty": "",
      "survey": "No",
      "engr": "No",
      "engrType": "",
      "util": "No",
      "utilType": "",
      "tooltips": null
    }
  ],
  "polyline": null,
  "alternate": null,
  "assumptions": [
    {
      "field": "dims.trailer_length_in",
      "applied": 660,
      "rule": "trailer_length_in not supplied: total length minus 240 in (20 ft), floor 0"
    },
    {
      "field": "rates",
      "applied": {
        "escort_dpm": 2,
        "escort_day_base": 125,
        "escort_day_min": 550,
        "hotel_per_night": 125,
        "miles_per_day": 450,
        "esl_mode": 1,
        "survey_dpm": 2,
        "survey_minimum": 550,
        "survey_report_fee": 250,
        "service_fee_per_state": 0
      },
      "rule": "unspecified rates fall back to the account Bid Builder config (service_fee_per_state defaults to 0)"
    }
  ],
  "warnings": [],
  "meta": {
    "data_version": "statesv3@2026-08-15",
    "rate_card": {
      "escort_dpm": 2,
      "escort_day_base": 125,
      "escort_day_min": 550,
      "hotel_per_night": 125,
      "miles_per_day": 450,
      "esl_mode": 1,
      "survey_dpm": 2,
      "survey_minimum": 550,
      "survey_report_fee": 250,
      "service_fee_per_state": 0,
      "out_of_route_percent": 0,
      "escort_safety_net": 0
    },
    "routed_at": "2026-08-24T20:54:42.951Z",
    "provider": {
      "engine": "here",
      "alternatives_offered": 1
    },
    "resolved": {
      "origin": "Charlotte, NC",
      "destination": "Nashville, TN"
    },
    "unpriced_states": [],
    "compare_mi": null,
    "usage": {
      "charge": "allowance",
      "remaining_allowance": 198,
      "remaining_lot_credits": 20
    }
  }
}