Public REST API

Two rules decide whether your first calls book or bounce.

1. Search the way you sell. One-way, round trip, connections and multi-city all book. The one thing withheld from results by default is a connection where a partner airline operates a leg, because the carrier does not confirm it at booking — see the airline’s page. Mind max_stops: absent means “no constraint”, 0 means “non-stop only”.
2. Price the offer before you book it. The offer ID from search is transient and the airline will not book it. POST /v1/offers/price mints a new ID, and only that one is accepted by POST /v1/orders.

export NORBA_KEY="nbr_live_…"

curl --request POST \
  --url https://api.norba.io/v1/shopping/offers \
  --header "X-API-Key: $NORBA_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "origin": "BCN",
    "destination": "JFK",
    "departure_date": "2026-10-20",
    "adults": 1,
    "cabin_class": "economy",
    "currency": "EUR",
    "max_stops": 0
  }'

A search like this returns real offers, every one with a resolved segment graph, fare family and parsed fare rules.

American Airlines supports all eleven NDC operations through the API: AirShopping, OfferPrice, ServiceList, SeatAvailability, OrderCreate, OrderRetrieve, OrderChange, OrderCancel, OrderReShop, OrderQuote and OrderCommit. Where a carrier does not offer an operation, the API answers with a clear error rather than fabricated data.

New carriers are announced in the changelog as they become available.

SearchRequest body

{
  "origin":         "BCN",          // IATA code; required unless "legs" is used
  "destination":    "JFK",
  "departure_date": "2026-10-20",   // YYYY-MM-DD; a past date is refused with 400
  "return_date":    "2026-10-27",   // optional — makes it a round trip (2 segments)
  "adults":         1,              // must be >= 1
  "children":       0,              // ages 2-11
  "infants":        0,              // under 2, no seat; more than "adults" is a 400
  "cabin_class":    "economy",      // economy | premium_economy | business | first
  "currency":       "EUR",          // ISO 4217
  "max_stops":      0               // absent = no constraint; 0 = non-stop only
}

Multi-city itineraries

{
  "adults": 1,
  "cabin_class": "economy",
  "legs": [
    { "origin": "MAD", "destination": "JFK", "departure_date": "2026-10-20" },
    { "origin": "JFK", "destination": "LAX", "departure_date": "2026-10-24" },
    { "origin": "LAX", "destination": "MAD", "departure_date": "2026-10-28" }
  ]
}

2–5 bounds, flown in order, chronological dates, each leg’s origin and destination must differ. legs replaces origin/destination/departure_date/return_date, and one offer covers the whole itinerary.

Order create request

{
  "offer_id": "AA-P2E80EC16-51FD-48AD-924B-1|P2E80EC16-51FD-48AD-924B-1-1",
  "airline":  "AA",
  "passengers": [
    {
      "id":            "T1",
      "type":          "ADT",
      "first_name":    "MARIA",
      "last_name":     "GARCIA",
      "date_of_birth": "1985-04-12",
      "gender":        "F",
      "document": {
        "type":            "P",
        "number":          "XDA123456",
        "issuing_country": "ES",
        "expiry_date":     "2032-05-30",
        "nationality":     "ES"
      },
      "contact": { "email": "traveller@example.com", "phone": "34600111222" }
    }
  ],
  "contact": { "email": "traveller@example.com", "phone": "34600111222" },

  "payment": { "method": "CARD", "currency": "EUR", "amount": 380.62 }
}

Note first_name/last_name (not given_name/family_name), issuing_country for the document, and thepayment block, which is optional — omit it entirely to create an unpaid hold, which is the normal agency flow.

The structured post-booking surface is a quote → confirm pair for changes and cancellations, plus refund endpoints. There are no /orders/{id}/seats, /ancillaries or /ssrs endpoints — seats and ancillaries are sold inside POST /v1/orders, and travel documents go in the passenger objects there.

Worth wiring up early: flight search answers 200 with an empty offers array both when there is genuinely no availability and when the route filter dropped the carrier, so search alone cannot tell you a connector is unreachable.

NDC endpoints return, at minimum, a single-field body — { "error": "<human sentence>" } — carrying the airline’s own message on a 502, with no request_id in the body; correlate with the X-Request-Id header instead. A few responses add a stable field on top of it: an unrecognised order id carries code: "order_not_found" (and did_you_mean when one of your own orders is a close typo), and the quota/feature-gate responses covered below carry reason. Aviation Data endpoints are different again: they use the envelope { data, meta, errors[] } with errors[{ code, message }] inside it.

There is no platform capacity limit. What is enforced on shopping and booking exists because airlines police the look-to-book ratio — searches per booking — and throttle or fine agencies that drift: the per-minute search rate, the daily/monthly search and order ceilings, and the look-to-book policy (an X-Norba-L2B warning header before any throttle) are the same idea over different windows. An identical search repeated within a short window is served from cache and never reaches the airline, so caching works in your favour here. On 429 the response carries a Retry-After header.

What consumes the quota, what a 402 means, how the free allowance and any card on file interact with booking, and how usage settles into an invoice each month are covered in full on Billing & Payments. The session-authenticated routes that manage a card and read invoices — /v1/dev/billing/* and the public GET /v1/dev/pricing rate card — are covered there too; they take a developer-portal session cookie, not an X-API-Key, so they are not part of this page’s contract.

The complete OpenAPI 3.0 document is published at /openapi.yaml and covers every schema referenced here, including the Aviation Data envelope. Generate a client from it, or load it into your API tooling.