Routespring Crew Travel API (1.0.0)

• Automate hotel layover bookings — submit a roster and Routespring books, modifies, and cancels hotel stays as your schedule changes.
• Book deadhead positioning flights — when crew need repositioning, Routespring searches and books on your behalf.
• Handle IROPs in near real-time — submit out-of-band hotel or flight requirements directly, bypassing the roster cycle.
• Monitor every booking — track state transitions, retry failures, and export full audit trails per submission.

---

Schedule-driven                  IROP / ad-hoc
POST /crew/schedules             POST /crew/action-items
(diff against prior              POST /crew/bookings/request
 submission)
        │                               │
        └───────────────┬───────────────┘
                        ▼
                Booking engine
                (config · policy)
                        │
               ┌────────┴────────┐
               │                 │
            Hotels          Deadhead flights
               │                 │
               ▼                 ▼
          Auto-booked        Auto-booked
          ──────────────────────────────
          or NEEDS_REVIEW if price ceiling
          exceeded or policy blocks
               │                 │
               └────────┬────────┘
                        ▼
               Action Items → Bookings

Processing is asynchronous. Every POST /crew/schedules returns a schedule_id immediately — poll /processing-status to track progress, then retrieve action items and bookings once processing completes.

---

• Sandbox — all examples in this documentation run against the sandbox. Get credentials from your Routespring dashboard under Settings → Integrations → REST API.
• Interactive walkthrough — the fastest way to see the full flow in action without writing any code.
• Quickstart — a complete curl-based guide covering every step from authentication to booking retrieval.

What must be provisioned for you

Parts of the automation are controlled by settings that are not exposed on this API. Each one is silent when unset — the lifecycle still runs and returns 200/202, the work just lands as a review item instead of a booking. If automation looks inert, check these first.

Get them provisioned before your first POST /crew/schedules. Switching a hotel contract on for automated booking is a reviewed action, so it cannot be arranged in the moment: submit a schedule against a station whose contract is not yet approved and the layover comes back NEEDS_REVIEW — configuring the hotel is not on its own enough to make it bookable.

Prerequisite	What you see while it is unset	Where it is set
Schedules API access	registering an OAuth client does not offer the schedules:read / schedules:write scopes	ask Routespring
Crew booking account	automated bookings have no account to book under	you — PUT /crew/config/company (crew_booker_email)
Hotel contract + contracted rates	a layover returns NEEDS_REVIEW with No hotel configuration found for station: XXX, even though GET /crew/config/hotels shows the hotel	Hotel Manager UI, or these API routes
Deadhead auto-booking	every NEW_DEADHEAD comes back PENDING_REVIEW / BOOK_MANUALLY with a flight_options_url — pick an option and commit it with POST /crew/bookings/request	ask Routespring
Booking modification	a date or station change is surfaced as a review item instead of being amended with the supplier	ask Routespring
Crew rotation / swap execution	an A↔B swap is surfaced as a review item instead of being executed	ask Routespring
Cancellation execution	a dropped layover is surfaced as a review item instead of being cancelled (the window itself is yours: cancellation_lookback_days)	ask Routespring
Rate-match strictness	a supplier price that differs from the contracted rate fails the booking rather than flagging it for review	ask Routespring

PUT /crew/config/company accepts only crew_booker_email and cancellation_lookback_days. The switches above authorise automated spend, so they stay operator-controlled — there is no API call that turns them on.

---

▶ Launch the crew lifecycle walkthrough ↗

A guided, click-through demo of the full crew lifecycle against the sandbox. Paste your sandbox client_id / client_secret (from the dashboard) and a traveler email, then step through it live: get a token → configure → submit a schedule → poll → action items → bookings → select and confirm a deadhead flight → full trip details. This reference page (everything below) is the contract; the demo is the same flow, executed for you one step at a time.

A copy-paste guide for integrators. Walks the lifecycle in order: one-time configuration → schedule-driven booking → IROP / airline-injected booking → ops & retries → error responses you should handle.

Every block is a real curl invocation. Bodies are inline so each one is self-contained. Variables ($BASE, $BEARER) are set once in §0.

---

0. Get an access token

The crew API authenticates with an OAuth2 client_credentials flow served by the Routespring auth service. You exchange a long‑lived client_id / client_secret for a short‑lived access token (JWT), and send that token as the Bearer on every crew API call. (The gateway validates the access token and resolves it to your company — there is no airline id in the URL.)

# Base of the Routespring OAuth service.
export AUTH_BASE="https://oauth-sandbox.routespring.com"   # sandbox
# export AUTH_BASE="https://oauth.routespring.com"          # production (host confirmed at onboarding)

Step 1 — get client credentials (one-time). Register an OAuth2 client, or receive client_id/client_secret directly during onboarding. Registration authenticates as your Routespring user (Bearer <email>:<sToken>):

curl -sS -X POST "$AUTH_BASE/oauth/register?name=crew-integration&scopes=events:read%20events:write" \
  -H "Authorization: Bearer your-user@airline.com:YOUR_STOKEN"
# -> { "client_id": "0687e8bd-…", "client_secret": "vwWDwBbC5QJ…" }

Step 2 — exchange them for an access token. HTTP Basic (client_id:client_secret) + grant_type=client_credentials:

curl -sS -X POST "$AUTH_BASE/oauth/token?grant_type=client_credentials" \
  -u "CLIENT_ID:CLIENT_SECRET"
# -> { "access_token": "<JWT>", "refresh_token": "<UUID>", "token_type": "Bearer",
#      "expires_in": 899, "scope": "events:read events:write" }

Step 3 — refresh when it expires (~15 min). No credentials needed, just the refresh token:

curl -sS -X POST "$AUTH_BASE/oauth/refresh?refresh_token=YOUR_REFRESH_TOKEN"
# -> a fresh access_token (+ expires_in)

Now set the variables the rest of this guide uses — $BEARER is the access_token from Step 2:

export BASE="https://sandbox.routespring.com/api/v1"   # sandbox: gateway host + /api/v1
# export BASE="https://api.routespring.com/api/v1"      # production (host confirmed at onboarding)
export BEARER="<access_token from /oauth/token>"  # short-lived; refresh via Step 3

Why a Bearer token? Every endpoint under /crew/… requires Authorization: Bearer $BEARER. Your airline (tenant) is derived from the token itself — there is no airline id in the URL. The hotel directory at /hotels also requires it. Missing, malformed, or expired bearer → 401 UNAUTHORIZED (refresh and retry).

---

0.1 Before your first end-to-end — behaviors that will trip you up

These aren't obvious from the endpoint reference, but each one will cost you a debugging session if you don't know it up front:

• Everything off POST /schedules is asynchronous. The submit returns 202 with processing_status: QUEUED. Poll …/processing-status until it is terminal (COMPLETED / PARTIAL / FAILED) before trusting …/action-items. An empty action_items array immediately after submit usually just means processing hasn't finished — not that nothing was derived.

• Deadhead diffing is stateful. Deadhead (FLIGHT) action items are derived by diffing your submission against the previous submission's persisted legs, keyed on employee_id + pairing_number + duty_date + leg_sequence. Consequences:

  • Re-POSTing a byte-identical roster is a no-op — no new action items.
  • Changing any key field emits a DEADHEAD_CANCELLED for the old leg and a NEW_DEADHEAD for the new one.
  • When testing, use a fresh employee_id to get a clean NEW_DEADHEAD with no cancellation noise.

• Keep dates consistent within a duty period. A leg's duty_date must agree with the date of its dep_time_local / expected_dep_time_local. If they disagree, the leg is dropped during grouping and nothing derives (you'll see an empty action_items with no error).

• A deadhead books the positioning flight you submit. A DH leg books a flight on its explicit from_airport → to_airport, exactly as you submit them — the route is taken as-is, not derived from the crew's home base.

• Deadheads and hotels both book automatically. /schedules derives the need and books it — a hotel layover, or a NEW_DEADHEAD positioning flight on the DH leg's explicit from_airport → to_airport, is auto-booked through the supplier path. Auto-booking is gated by policy: a deviation (e.g. an early check-in, or a route/date the supplier can't fulfill) or a strict price mismatch surfaces the item as NEEDS_REVIEW for an agent to resolve instead.

• Flight booking requires a date of birth. The crew member's traveler profile must have a DOB (airline/GDS requirement). Without one, a flight POST /bookings/request returns 422.

• Flight options are short-lived and opaque. flight_option_id values from GET /flight-options expire (~20 min) and must be passed back verbatim to POST /bookings/request — never parse or construct them. Search fresh and commit promptly; an expired id fails the commit.

• Read a booking in two steps. GET /bookings/{id}/status refreshes the live supplier state (PNR / ticket / transaction / trip-session ids) and persists it; then GET /bookings/{id} returns the full record with those ids on the flight block (pnr, ticket_id, transaction_id, trip_session_id).

• Raw supplier itinerary (optional deep dive). Beyond the crew booking record, you can fetch the full supplier itinerary — complete PNR, fare breakdown, segments — from the flight API at GET $BASE/bookings/trips/{trip_session_id} (see the Flights tag), using the trip_session_id returned by GET /crew/bookings/{id}.

---

1. One-time airline setup

Run these once when onboarding a new airline. They are idempotent — re-running a PUT replaces the config (creating a new version under the hood).

1.0 Crew booking account + automation flags

crew_booker_email is the Routespring account under which engine-driven crew bookings — hotel layovers the diff engine books and later amends/cancels — are placed; set it first, before any roster flows. (A manual flight commit via POST /crew/bookings/request is booked under the user whose bearer token makes that call, not this account — so for flights the actor is the API caller.) The other setting exposed here is cancellation_lookback_days; omit a field on PUT to leave it unchanged. The automation execution levers (cancellation / modification / swap / deadhead-flight execution, strict price matching, NOC stats) are Routespring-managed and not part of this API. Deadhead positioning flights are booked automatically by the engine, the same as hotel layovers.

curl -sS -X PUT "$BASE/crew/config/company" \
  -H "Authorization: Bearer $BEARER" \
  -H "Content-Type: application/json" \
  -d '{
    "crew_booker_email": "crew-ops@flymx.com"
  }'

# Read the current config back any time:
curl -sS "$BASE/crew/config/company" -H "Authorization: Bearer $BEARER"

1.1 Hotel inventory + contract rates

Tell Routespring which preferred hotel to book at each crew base (one hotel per base). The booking engine prefers it over open-market searches.

curl -sS -X PUT "$BASE/crew/config/hotels" \
  -H "Authorization: Bearer $BEARER" \
  -H "Content-Type: application/json" \
  -d '{
    "bases": [
      {
        "base_station": "SLC",
        "hotels": [
          {
            "property_id": "hilton-slc-airport",
            "chain": "HILTON",
            "policy": "STANDARD",
            "standard_check_in_time": "15:00",
            "standard_check_out_time": "11:00",
            "buffer_minutes": 60,
            "contract_rate": { "amount": 149.00, "currency": "USD" },
            "rate_periods": [
              { "effective_from": "2026-01-01", "effective_to": "2026-06-30", "rate": { "amount": 149.00, "currency": "USD" } },
              { "effective_from": "2026-07-01", "effective_to": "2026-12-31", "rate": { "amount": 169.00, "currency": "USD" } }
            ]
          }
        ]
      },
      {
        "base_station": "JFK",
        "hotels": [
          {
            "property_id": "TVP-JFK-9001",
            "policy": "FLEXIBLE",
            "flex_window_minutes": 120,
            "buffer_minutes": 30
          }
        ]
      }
    ]
  }' | jq .

GDS vs DIRECT. GDS hotels are looked up against the GDS global inventory by property_id; an unknown id returns 422 UNKNOWN_HOTEL_PROPERTY at PUT time. DIRECT hotels are managed by you and not validated against any external system.

1.2 Flight rules (deadhead thresholds)

The price ceiling for auto-booking a positioning flight:

curl -sS -X PUT "$BASE/crew/config/flight-rules" \
  -H "Authorization: Bearer $BEARER" \
  -H "Content-Type: application/json" \
  -d '{
    "auto_book_max_price": { "amount": 800.00, "currency": "USD" }
  }' | jq .

1.3 Flight preferences

Preferred / blacklisted carriers and cabin:

curl -sS -X PUT "$BASE/crew/config/flights" \
  -H "Authorization: Bearer $BEARER" \
  -H "Content-Type: application/json" \
  -d '{
    "preferred_airlines": ["DL", "UA", "AA"],
    "blacklisted_airlines": ["F9"],
    "preferred_cabin": "ECONOMY",
    "same_carrier_preference": true
  }' | jq .

1.4 Verify the config landed

curl -sS "$BASE/crew/config/hotels"        -H "Authorization: Bearer $BEARER" | jq '.bases | length'
curl -sS "$BASE/crew/config/flight-rules"  -H "Authorization: Bearer $BEARER" | jq .

---

2. Schedule-driven flow (the normal happy path)

This is the standard loop: you POST a roster and Routespring diffs it, derives action items, and books against your config. Hotel layovers are diffed against existing booking actuals; deadhead positioning against the prior submission's persisted legs.

2.1 Submit a roster (JSON)

SUBMIT_RESPONSE=$(curl -sS -X POST "$BASE/crew/schedules" \
  -H "Authorization: Bearer $BEARER" \
  -H "Content-Type: application/json" \
  -d '{
    "external_ref": "MX-20260527-4821",
    "as_of": "2026-05-27T08:00:00Z",
    "schedule_start_date": "2026-05-16",
    "schedule_end_date": "2026-05-31",
    "pairings": [
      {
        "pairing_number": "MX-20260527-4821",
        "origin_base": "SLC",
        "crew": [
          { "employee_id": "EMP-1042", "name": "Jordan Reyes", "rank": "CA", "home_base": "SLC", "traveller_email": "jreyes@flymx.com" },
          { "employee_id": "EMP-2317", "name": "Alex Pham", "rank": "FO", "home_base": "SLC", "traveller_email": "apham@flymx.com" }
        ],
        "duty_periods": [
          {
            "duty_period_num": 1,
            "duty_date": "2026-05-27",
            "fdp_start_local": "2026-05-26T23:30:00-06:00",
            "fdp_end_local": "2026-05-27T12:15:00-04:00",
            "legs": [
              { "leg_sequence": 1, "activity_code": "FLT", "flight_number": "MX401", "from_airport": "SLC", "to_airport": "LAX", "dep_time_local": "2026-05-27T01:00:00-06:00", "arr_time_local": "2026-05-27T01:30:00-07:00", "aircraft_type": "A220-300", "aircraft_tail": "N412MX" },
              { "leg_sequence": 2, "activity_code": "FLT", "flight_number": "MX588", "from_airport": "LAX", "to_airport": "IAD", "dep_time_local": "2026-05-27T03:00:00-07:00", "arr_time_local": "2026-05-27T14:15:00-04:00", "aircraft_type": "A220-300", "aircraft_tail": "N412MX" }
            ],
            "layover": { "station": "IAD", "booking_required": true, "checkin_time_local": "2026-05-27T14:45:00-04:00", "checkout_time_local": "2026-05-28T01:00:00-04:00" }
          },
          {
            "duty_period_num": 2,
            "duty_date": "2026-05-28",
            "fdp_start_local": "2026-05-28T02:00:00-04:00",
            "fdp_end_local": "2026-05-28T09:30:00-05:00",
            "legs": [
              { "leg_sequence": 3, "activity_code": "FLT", "flight_number": "MX210", "from_airport": "IAD", "to_airport": "TUL", "dep_time_local": "2026-05-28T04:00:00-04:00", "arr_time_local": "2026-05-28T05:45:00-05:00", "aircraft_type": "A220-300", "aircraft_tail": "N388MX" },
              { "leg_sequence": 4, "activity_code": "DH", "from_airport": "TUL", "to_airport": "DAL", "expected_dep_time_local": "2026-05-28T07:00:00-05:00", "expected_arr_time_local": "2026-05-28T08:15:00-05:00", "booking_required": true }
            ],
            "layover": { "station": "DAL", "booking_required": true, "checkin_time_local": "2026-05-28T08:45:00-05:00", "checkout_time_local": "2026-05-29T00:30:00-05:00" }
          },
          {
            "duty_period_num": 3,
            "duty_date": "2026-05-29",
            "fdp_start_local": "2026-05-29T01:30:00-05:00",
            "fdp_end_local": "2026-05-29T04:00:00-06:00",
            "legs": [
              { "leg_sequence": 5, "activity_code": "FLT", "flight_number": "MX305", "from_airport": "DAL", "to_airport": "SLC", "dep_time_local": "2026-05-29T03:00:00-05:00", "arr_time_local": "2026-05-29T03:45:00-06:00", "aircraft_type": "A220-300", "aircraft_tail": "N401MX" }
            ]
          }
        ]
      }
    ]
  }')
echo "$SUBMIT_RESPONSE" | jq .

# Capture the minted schedule_id for the next steps.
export SCHEDULE_ID=$(echo "$SUBMIT_RESPONSE" | jq -r .schedule_id)
echo "SCHEDULE_ID=$SCHEDULE_ID"

Expected: 202 Accepted with processing_status: QUEUED and a generated schedule_id like UPL-35-1779633752601.

Deadhead in v1. The JSON POST /schedules path derives both HOTEL and FLIGHT (deadhead) action items from the same submission. JSON is the only ingestion format — there is no file-upload endpoint.

2.2 Poll processing status

curl -sS "$BASE/crew/schedules/$SCHEDULE_ID/processing-status" \
  -H "Authorization: Bearer $BEARER" | jq .

status walks: QUEUED → PROCESSING → BOOKING → COMPLETED (or FAILED).

Why status can revert from COMPLETED to BOOKING. The hotel branch can flip the upload to COMPLETED before the deadhead (flight) branch finishes its supplier calls. If any FLIGHT task is still non-terminal, this endpoint reports BOOKING rather than COMPLETED so you don't stop polling early. Once every flight task is BOOKED / FAILED / CANCELLED, status reports COMPLETED.

2.3 List derived action items

# All action items for the submission
curl -sS "$BASE/crew/schedules/$SCHEDULE_ID/action-items" \
  -H "Authorization: Bearer $BEARER" | jq '.action_items[] | {action_id, type, classification, priority, disposition}'

# Just FLIGHT (deadhead) items
curl -sS "$BASE/crew/schedules/$SCHEDULE_ID/action-items?type=FLIGHT" \
  -H "Authorization: Bearer $BEARER" | jq .

# Just items needing human review
curl -sS "$BASE/crew/schedules/$SCHEDULE_ID/action-items?disposition=PENDING&priority=P1" \
  -H "Authorization: Bearer $BEARER" | jq .

Action-item classifications you'll see: NEW_LAYOVER, LAYOVER_DATE_CHANGE, LAYOVER_CITY_CHANGE, LAYOVER_CANCELLED, NEW_DEADHEAD, DEADHEAD_TIME_CHANGE, DEADHEAD_CANCELLED, and the data-quality / IROP groups documented in openapi.yaml.

2.4 List the resulting bookings

# By employee
curl -sS "$BASE/crew/bookings?employee_id=EMP-12047" \
  -H "Authorization: Bearer $BEARER" | jq '.bookings[] | {booking_id, type, status, hotel, flight}'

# By pairing
curl -sS "$BASE/crew/bookings?pairing_number=P-23845" \
  -H "Authorization: Bearer $BEARER" | jq .

# By IROP reference
curl -sS "$BASE/crew/bookings?irop_ref=IROP-2026-06-15-EWR-001" \
  -H "Authorization: Bearer $BEARER" | jq .

# Only flight bookings in a date range
curl -sS "$BASE/crew/bookings?type=FLIGHT&from_date=2026-06-01&to_date=2026-06-30" \
  -H "Authorization: Bearer $BEARER" | jq .

Filter is required. GET /bookings with no filter returns 400 INVALID_REQUEST. Pass any anchor key: employee_id, pairing_number, flight_number, irop_ref, schedule_id. The booking index is denormalised so any one anchor is a single-indexed lookup.

2.5 Get a specific booking + its status history

export BOOKING_ID="BKG-..."  # from §2.4

curl -sS "$BASE/crew/bookings/$BOOKING_ID" \
  -H "Authorization: Bearer $BEARER" | jq .

curl -sS "$BASE/crew/bookings/$BOOKING_ID/status" \
  -H "Authorization: Bearer $BEARER" | jq .
# returns current_status + the full transition history

2.6 Modify a booking (date change / hotel swap / fare upgrade)

# In-place hotel date-window change (preserves booking_id + supplier confirmation)
curl -sS -X PATCH "$BASE/crew/bookings/$BOOKING_ID" \
  -H "Authorization: Bearer $BEARER" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "PAIRING_EXTENDED",
    "hotel": { "check_out_date": "2026-06-16" }
  }' | jq .

Side effect: manual_override becomes true. After a successful PATCH, the diff engine will not modify this booking on subsequent schedule submissions. Release it back to auto-management by PATCHing { "manual_override": false } (alone or alongside other changes).

2.7 Cancel a booking

curl -sS -X DELETE "$BASE/crew/bookings/$BOOKING_ID?reason=roster_change" \
  -H "Authorization: Bearer $BEARER" | jq .

A cancelled booking whose pairing later reappears in a schedule will not auto-recreate — re-issue explicitly with POST /bookings/request.

---

3. IROP / airline-injected flow

When ops already knows what they need and the roster system hasn't caught up.

3.1 Inject an IROP hotel requirement (engine still picks the property)

Use POST /action-items when the airline has identified the requirement but wants Routespring to auto-select against the active hotel config.

curl -sS -X POST "$BASE/crew/action-items" \
  -H "Authorization: Bearer $BEARER" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "HOTEL",
    "classification": "IROP_HOTEL_EXTEND",
    "priority": "P1",
    "source": "IROP",
    "irop_ref": "IROP-2026-06-15-EWR-001",
    "anchors": {
      "traveller_email": "jordan.reyes@flymx.com",
      "employee_id": "EMP-12047",
      "pairing_number": "P-23845"
    },
    "hotel": {
      "city": "EWR",
      "check_in_date": "2026-06-15",
      "check_out_date": "2026-06-16",
      "num_nights": 1
    },
    "notes": "Crew weather-diverted to EWR; extend layover."
  }' | jq .

3.2 Commit a specific hotel

curl -sS -X POST "$BASE/crew/bookings/request" \
  -H "Authorization: Bearer $BEARER" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "HOTEL",
    "classification": "IROP_HOTEL_EXTEND",
    "source": "IROP",
    "irop_ref": "IROP-2026-06-15-EWR-001",
    "anchors": {
      "traveller_email": "jordan.reyes@flymx.com",
      "employee_id": "EMP-12047",
      "pairing_number": "P-23845"
    },
    "hotel": {
      "city": "EWR",
      "property_id": "24355",
      "check_in_date": "2026-06-15",
      "check_out_date": "2026-06-16"
    }
  }' | jq .

Omit property_id to let Routespring auto-select per priority order.

3.3 Search flight options (manual deadhead picker)

curl -sS "$BASE/crew/flight-options?from_airport=EWR&to_airport=SLC&date=2026-06-15&arrive_by=2026-06-15T20:00:00Z" \
  -H "Authorization: Bearer $BEARER" | jq '.options[] | {flight_option_id, airline_code, flight_number, dep_time, arr_time, price}'

Returns options each carrying a flight_option_id (a supplier offer id) — held for 20 minutes. To commit one, POST it back with the crew member's traveller_email on anchors.

3.4 Commit a specific flight from §3.3

curl -sS -X POST "$BASE/crew/bookings/request" \
  -H "Authorization: Bearer $BEARER" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "FLIGHT",
    "classification": "IROP_NEW_DEADHEAD",
    "source": "IROP",
    "irop_ref": "IROP-2026-06-15-EWR-001",
    "anchors": {
      "traveller_email": "jordan.reyes@flymx.com",
      "employee_id": "EMP-12047",
      "pairing_number": "P-23845"
    },
    "flight": {
      "flight_option_id": "REPLACE_ME_FROM_3.3"
    },
    "notes": "Manager-selected from /flight-options"
  }' | jq .

Or commit a flight without a prior /flight-options search by passing the route + date:

curl -sS -X POST "$BASE/crew/bookings/request" \
  -H "Authorization: Bearer $BEARER" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "FLIGHT",
    "classification": "IROP_NEW_DEADHEAD",
    "source": "IROP",
    "irop_ref": "IROP-2026-06-15-EWR-002",
    "anchors": { "traveller_email": "jordan.reyes@flymx.com", "employee_id": "EMP-12047" },
    "flight": {
      "from_airport": "EWR",
      "to_airport": "SLC",
      "depart_date": "2026-06-15",
      "depart_after": "2026-06-15T09:00:00Z",
      "arrive_by":    "2026-06-15T20:00:00Z",
      "cabin_class": "ECONOMY"
    }
  }' | jq .

---

4. Ops & retries

4.1 Hotel directory (GDS global search, airline-independent)

Use to look up property_ids before adding hotels to your config. Any combination of name, city, airport_code (at least one required).

# By partial name
curl -sS "$BASE/hotels?name=Hilton%20Newark&limit=10" \
  -H "Authorization: Bearer $BEARER" | jq '.hotels[] | {property_id, name, city}'

# By city
curl -sS "$BASE/hotels?city=Newark&limit=10" \
  -H "Authorization: Bearer $BEARER" | jq '.hotels[] | {property_id, name, city}'

# By IATA airport code (3 letters) - matches hotels that name the airport
# AND hotels in the airport's city per Routespring's airport directory
curl -sS "$BASE/hotels?airport_code=EWR&limit=10" \
  -H "Authorization: Bearer $BEARER" | jq '.hotels[] | {property_id, name, city}'

# Combine filters - results are unioned and deduplicated on property_id
curl -sS "$BASE/hotels?airport_code=EWR&name=Hilton&limit=10" \
  -H "Authorization: Bearer $BEARER" | jq '.hotels[] | {property_id, name, city}'

4.2 Audit events for a schedule

Data-quality flags and duplicate-row detections from the diff engine:

curl -sS "$BASE/crew/schedules/$SCHEDULE_ID/audit-events" \
  -H "Authorization: Bearer $BEARER" | jq .

4.3 Exports

# Action items as CSV
curl -sS -o actions.csv "$BASE/crew/schedules/$SCHEDULE_ID/actions.csv" \
  -H "Authorization: Bearer $BEARER"

4.4 Retry a failed booking

# Single retry
curl -sS -X POST "$BASE/crew/bookings/$BOOKING_ID/retry" \
  -H "Authorization: Bearer $BEARER" | jq .

# What is queued
curl -sS "$BASE/crew/bookings/retry-queue?limit=20" \
  -H "Authorization: Bearer $BEARER" | jq .

# Recent bulk-retry jobs
curl -sS "$BASE/crew/bookings/retry-jobs?limit=10" \
  -H "Authorization: Bearer $BEARER" | jq '.retry_jobs[] | {retry_job_id, status, total, succeeded, failed}'

# Single job detail
curl -sS "$BASE/crew/bookings/retry-jobs/JOB-..." \
  -H "Authorization: Bearer $BEARER" | jq .

---

5. Error responses you should handle

The same envelope is used everywhere:

{ "error": { "code": "<UPPER_SNAKE>", "message": "<human>", "details": [...] }, "status": <int> }

5.1 401 UNAUTHORIZED — missing / malformed bearer

curl -sS "$BASE/crew/schedules" | jq .
# => { "error": { "code": "UNAUTHORIZED", ... }, "status": 401 }

5.2 404 NOT_FOUND — unknown id, or cross-tenant access

curl -sS "$BASE/crew/bookings/BKG-DOES-NOT-EXIST" \
  -H "Authorization: Bearer $BEARER" | jq .

Cross-tenant requests return 404, not 403. A resource owned by a different airline looks identical to a non-existent resource — we don't leak existence across tenants.

5.3 409 CONFLICT — duplicate booking on /bookings/request

A live booking already exists for the same anchors and booking type. Use PATCH /bookings/{id} to modify the existing one, or release it with manual_override: false first.

# Run the §3.2 hotel commit twice. The second call should return 409:
# { "error": { "code": "CONFLICT", "message": "a live HOTEL booking already exists for ..." }, "status": 409 }

5.4 Expired flight option on /bookings/request

A flight_option_id is a supplier offer held for 20 minutes after the originating /flight-options query. Committing an expired offer doesn't pre-fail — the request is accepted (202) and the booking comes back NEEDS_REVIEW (the commit failed at the supplier). Re-search and pick a fresh option.

5.5 422 VALIDATION_FAILED — structural validation

curl -sS -X POST "$BASE/crew/schedules" \
  -H "Authorization: Bearer $BEARER" \
  -H "Content-Type: application/json" \
  -d '{ "pairings": [] }' | jq .
# => { "error": { "code": "VALIDATION_FAILED", ... }, "status": 422 }

---

6. Full setup-and-smoke-test in one block

For an automated airline-onboarding script:

#!/usr/bin/env bash
set -euo pipefail

: "${BASE:?set BASE first}"
: "${BEARER:?set BEARER first}"

call() {
  curl -fsS -H "Authorization: Bearer $BEARER" -H "Content-Type: application/json" "$@"
}

echo "1/4  Push hotel config…"
call -X PUT "$BASE/crew/config/hotels" \
  -d '{"bases":[{"base_station":"SLC","hotels":[{"property_id":"hilton-slc-airport","policy":"STANDARD","standard_check_in_time":"15:00","standard_check_out_time":"11:00","buffer_minutes":60}]}]}' >/dev/null

echo "2/4  Push flight rules…"
call -X PUT "$BASE/crew/config/flight-rules" \
  -d '{"auto_book_max_price":{"amount":800.00,"currency":"USD"}}' >/dev/null

echo "3/4  Submit a smoke-test roster…"
SCHEDULE_ID=$(call -X POST "$BASE/crew/schedules" \
  -d '{"external_ref":"SMOKE-TEST","as_of":"2026-06-15T08:00:00Z","schedule_start_date":"2026-06-14","schedule_end_date":"2026-06-15","pairings":[{"pairing_number":"P-SMOKE","origin_base":"SLC","crew":[{"employee_id":"EMP-SMOKE","name":"Smoke Test","home_base":"SLC","rank":"CA","traveller_email":"smoke@example.invalid"}],"duty_periods":[{"duty_period_num":1,"duty_date":"2026-06-14","fdp_start_local":"2026-06-14T16:00:00-06:00","fdp_end_local":"2026-06-14T20:45:00-04:00","legs":[{"leg_sequence":1,"activity_code":"FLT","from_airport":"SLC","to_airport":"JFK","dep_time_local":"2026-06-14T17:00:00-06:00","arr_time_local":"2026-06-14T20:45:00-04:00"}],"layover":{"station":"JFK","booking_required":true,"checkin_time_local":"2026-06-14T21:15:00-04:00","checkout_time_local":"2026-06-15T11:00:00-04:00"}},{"duty_period_num":2,"duty_date":"2026-06-15","fdp_start_local":"2026-06-15T13:15:00-04:00","fdp_end_local":"2026-06-15T16:30:00-06:00","legs":[{"leg_sequence":2,"activity_code":"FLT","from_airport":"JFK","to_airport":"SLC","dep_time_local":"2026-06-15T14:15:00-04:00","arr_time_local":"2026-06-15T16:30:00-06:00"}]}]}]}' \
  | jq -r .schedule_id)
echo "    schedule_id=$SCHEDULE_ID"

echo "4/4  Poll until COMPLETED (or BOOKING with all flight tasks terminal)…"
for i in 1 2 3 4 5 6 7 8 9 10; do
  STATUS=$(call "$BASE/crew/schedules/$SCHEDULE_ID/processing-status" | jq -r .status)
  echo "    [$i] status=$STATUS"
  case "$STATUS" in
    COMPLETED|FAILED) break ;;
    *) sleep 2 ;;
  esac
done

echo "Done. Bookings:"
call "$BASE/crew/bookings?schedule_id=$SCHEDULE_ID" | jq '.bookings[] | {booking_id, type, status}'

Airline-industry terminology used in this API. Only terms that actually appear in the spec are listed here. Many field descriptions cross-reference these definitions.

Crew

• Crew Member — A pilot or flight attendant assigned to operate or accompany a flight in a working capacity. Maps to CrewMember.
• Rank — Role / seniority code: CA Captain, FO First Officer, FA Flight Attendant, PU Purser, SO Second Officer. Airline-conventional. Maps to CrewMember.rank.
• Crew Base / Home Base / Domicile — The airport a crew member is contractually based at; pairings begin and end here, and TAFB is measured against it. The three terms are interchangeable. Maps to CrewMember.home_base (IATA code).
• Union Code — The crew member's union (e.g. ALPA, APFA, AFA-CWA, APA). Can affect hotel-tier entitlements and per-diem rules at some carriers. Maps to CrewMember.union_code.

Schedule structure

Hierarchy, largest to smallest: Roster (a crew member's monthly schedule) → Pairings (multi-day trips) → Duty Periods (one operational day each) → Legs (individual flight segments).

• Schedule / Roster — The published assignment of work to crew over a planning horizon (typically a month). Maps to what you submit at POST /schedules and the Schedule resource Routespring builds from it.
• Pairing — The atomic unit of crew scheduling: a sequence of duty periods that originates and terminates at the same domicile, typically 1–4 days, separated by layovers. Maps to Pairing; identified by pairing_number.
• Duty Period (FDP — Flight Duty Period) — Roughly one working day: begins at sign-in (~60–90 min before the first flight) and ends after the last flight. Numbered sequentially within a pairing. Maps to DutyPeriod (duty_period_num, duty_date, fdp_start_local, fdp_end_local).
• Leg (also: Segment) — One movement of one aircraft from one airport to another. Numbered within a duty period (leg_sequence). Maps to Leg.

Activity codes

A leg's activity_code says what the crew is doing during that leg (industry-conventional, not regulated):

Code	Meaning	Counts as duty?
FLT	Revenue flight — crew is operating	Yes
DH	Deadhead — see below	Yes (duty, not rest)
TRG	Training (sim, ground school, line check)	Yes
OFF	Scheduled day off	No
RSV	Reserve — crew on call for assignment	Yes
SBY	Standby — available for immediate call-out	Yes
SL	Sick leave	No
RST	Rest period at layover hotel	No

• Deadhead (DH) — Transportation of a crew member as a passenger to position them for an upcoming duty. Deadhead time counts as duty, not rest — it eats into the crew's daily duty budget, which is what makes positioning expensive and worth automating. This is the FLIGHT booking category in this API.

Time / duty / rest

• Block Time (also: Block Hours) — Ramp-blocks-out to ramp-blocks-in; most pilots' pay clock, always less than the surrounding FDP. Maps to Leg.block_hours.
• FDP Start / End — The times that bound a duty period; used by the engine to tell on-duty from scheduled rest (hotel check-in timing, rest minimums). Maps to DutyPeriod.fdp_start_local / fdp_end_local.
• Layover — A scheduled rest period at an out-station between two duty periods of the same pairing; the crew is off duty and entitled to hotel accommodation. Maps to DutyPeriod.layover.
• TAFB — Time Away From Base — Total wall-clock duration of a pairing, measured from pairing check-in to pairing check-out — including all duty periods, layovers, and deadhead positioning. Used for per-diem and pairing-bid preferences. Maps to Pairing.tafb_hours.

Aircraft

• Aircraft Type / Tail — Type is the model designator (B777, A350, B737; ICAO/IATA codes). Tail is the unique registration of one airframe (A6-EBA). Maps to Leg.aircraft_type / Leg.aircraft_tail.

Operations

• IROPS — Irregular Operations — Disruptions to planned schedules caused by weather, mechanical issues, ATC delays, or other unforeseen events. Reach the engine via the airline-injection path and are treated as high-priority (P1/P2) — typically only hours to react.

Booking & supplier

• GDS — Global Distribution System — The intermediary inventory and booking platform (e.g. Amadeus, Sabre, Travelport) through which Routespring searches and books hotels and flights. GDS hotels are validated against Routespring's inventory at config time — an unknown property_id returns 422. DIRECT hotels bypass GDS and are managed by the airline directly.
• PNR — Passenger Name Record — The airline reservation record created when a flight is ticketed. Routespring returns the pnr, ticket_id, transaction_id, and trip_session_id on a FLIGHT booking after the booking is confirmed and the status is refreshed via GET /crew/bookings/{id}/status.

Four conceptual domains:

1. Schedule ingestion — the airline POSTs the complete current state of all open pairings to POST /schedules (JSON). Routespring computes the diff server-side against the prior submission and derives booking action items. There is no delta mode — always send everything you have open.
2. Booking configuration — the airline defines per-base hotel preferences, flight preferences, and flight rules. PUTs are idempotent and versioned; every booking snapshots the active config version (see Booking.config_version_used) so historical bookings can be replayed against the exact rules that were in force.
3. Booking engine — Routespring processes action items asynchronously, applying configuration to decide between auto-booking and human review.
4. Retrieval & management — the airline queries bookings by any anchor key, and modifies / cancels bookings out-of-band.

Action items reach the booking engine via two distinct paths. Both produce the same downstream artifacts: action items with the same classification taxonomy, bookings with the same lifecycle, the same retry semantics.

Path	When to use	Endpoint(s)
Schedule diff	Normal flow — airline publishes the roster, Routespring derives every needed booking from the diff against the prior submission	POST /schedules
Airline injection	IROPs and ad-hoc requirements where the airline already knows what's needed and the roster system hasn't caught up	POST /action-items (let engine search + auto-book) or POST /bookings/request (airline already picked the option)

Use Booking.source and ActionItem.source (SCHEDULE_DIFF / AIRLINE_INJECTED / IROP) to distinguish the origin downstream.

Crew, pairing, and leg identity all come from the airline's own identifiers — Routespring does not mint a parallel crew_id / pairing_id / duty_id / leg_id. Every booking record is denormalized with these keys so retrieval by any of them is a single indexed lookup:

Anchor	Issued by	Notes
employee_id	Airline	Your HR system's employee id — the crew anchor
pairing_number	Airline	e.g. MX-20260527-4821
flight_number	Airline	e.g. MX401
irop_ref	Airline	IROP correlation id for IROP-injected artifacts
schedule_id	Routespring	The submission id returned by POST /schedules

Query GET /bookings?<any-key>=<value> and get the same record set regardless of which anchor you pass.

POST /schedules returns 202 Accepted immediately. Outcomes surface asynchronously at three levels — track all three:

┌──────────────────────────────────────────────────────────────────┐
│  1. Submission level — ProcessingStatus                          │
│     QUEUED → PROCESSING → BOOKING → COMPLETED                    │
│                                  └─ or FAILED (file unparseable) │
│                                                                  │
│  2. Action item level — ActionItem.disposition                   │
│     AUTO_BOOKED | AUTO_CANCELLED | PENDING_REVIEW | FAILED        │
│                                                                  │
│  3. Booking level — Booking.status                               │
│     PENDING → CONFIRMED → MODIFIED → CANCELLED                   │
│             └─ or FAILED / NEEDS_REVIEW                          │
└──────────────────────────────────────────────────────────────────┘

ProcessingStatus: COMPLETED does not imply every action succeeded — individual bookings can still be FAILED. Always check the booking level too. The schedule-level summary.action_items_* counts give you the breakdown at a glance.

Disposition vs status vs auto-eligibility

Three closely-related fields that confuse first-time readers:

• ActionItem.disposition (AUTO_BOOKED / AUTO_CANCELLED / PENDING_REVIEW / FAILED) — what the engine decided to do with the action.
• ActionItem.auto_eligible (boolean) — whether the action passed all auto-book eligibility checks (preferred vendor available, within auto_book_max_price, etc.). Independent of supplier success. An action can be auto_eligible: true but still end up disposition: FAILED if the supplier call failed — a retry could succeed. Use this to distinguish "ineligible, don't retry" from "eligible but supplier failed, retry might work".
• Booking.status — the booking's lifecycle state at the supplier.

Any of these actions sets Booking.manual_override = true automatically: PATCH /bookings/{id}, DELETE /bookings/{id}, POST /bookings/request, POST /action-items. Once manual_override is true, the diff engine will NOT modify or cancel this booking on subsequent schedule submissions, even if the upstream pairing changes.

This prevents the diff engine from silently reverting a deliberate manual change (e.g. an IROP rebooking made before the catch-up roster arrives). To release a booking back to automatic management, PATCH with {"manual_override": false} — the diff engine resumes ownership on the next submission.

A cancelled booking whose pairing later reappears in a schedule will not auto-recreate — re-issue explicitly.

ActionItem.classification describes why an action exists. The taxonomy (new values may be added in future versions — handle unknown values gracefully):

Group	Values
Hotel — diff-derived	NEW_LAYOVER, LAYOVER_DATE_CHANGE, LAYOVER_CITY_CHANGE, LAYOVER_CANCELLED, LAYOVER_EXTENDED
Flight — diff-derived	NEW_DEADHEAD, DEADHEAD_TIME_CHANGE, DEADHEAD_CANCELLED
Pairing-level	PAIRING_NEW, PAIRING_EXTENDED, PAIRING_SHORTENED, PAIRING_CANCELLED, SWAP_OUT, SWAP_IN, STATUS_TRANSITION
IROP — airline-injected	IROP_NEW_DEADHEAD, IROP_REROUTE, IROP_HOTEL_EXTEND, IROP_HOTEL_CANCEL
Data quality	DATA_QUALITY_FLAG, DATA_QUALITY_QUARANTINE, DUPLICATE_ROW
No-op	UNCHANGED (only when the Routespring-managed emit_nop_tasks toggle is on — off by default in v1, not set via this API)

v1 diff-derived subset. A POST /schedules diff in v1 derives the hotel, deadhead, swap, and data-quality classifications — NEW_LAYOVER, LAYOVER_DATE_CHANGE, LAYOVER_CITY_CHANGE, LAYOVER_EXTENDED, LAYOVER_CANCELLED, NEW_DEADHEAD, DEADHEAD_TIME_CHANGE, DEADHEAD_CANCELLED, SWAP_OUT, SWAP_IN, DUPLICATE_ROW, DATA_QUALITY_FLAG, and UNCHANGED. Pairing-level classifications are not emitted by the diff path. The IROP_* values are airline-supplied on POST /action-items / POST /bookings/request and are accepted in v1.

ActionItem.priority drives queue ordering and human-review SLAs:

Priority	Typical use	Target time to disposition
P1	IROPs requiring immediate action — flights departing in hours	~5 minutes
P2	Same-day pairing changes; default for airline injections	~30 minutes
P3	Routine layover bookings several days out	within the hour
P4	Backfills, no-op annotations, low-urgency cleanup	next batch window

Airline injections (POST /action-items) default to P2. Bump to P1 for IROPs with tight SLAs.

v1: priority is recorded on every action item, but review-SLA enforcement is not active — the target times above are advisory.

All endpoints require Authorization: Bearer <access_token>. The token is obtained via an OAuth2 client_credentials flow on the Routespring auth service — see Quickstart §0 ("Get an access token") for the full sequence:

• One-time: register an OAuth2 client (or receive credentials at onboarding) → client_id + client_secret.
• POST /oauth/token — Basic client_id:client_secret, grant_type=client_credentials → a short-lived JWT access_token (expires_in ≈ 15 min) plus a refresh_token.
• POST /oauth/refresh — exchange the refresh_token for a new access token when it expires.

The access token resolves to the calling airline (tenant); there is no airline id in the URL path — every request is scoped to the company the token belongs to. An expired token returns 401 UNAUTHORIZED.

The Schedules APIs are where every booking workflow begins. Submit your airline's current roster as a complete snapshot — Routespring compares it against the bookings that already exist in the system and derives everything that needs to happen: new bookings, cancellations, modifications, and crew swaps.

You do not send deltas. Every submission is the full picture of your open pairings for a given date window. Routespring handles the reconciliation server-side, so your integration stays simple — re-export from your crew management system and POST.

Processing is asynchronous. The submit returns immediately with a schedule_id; use the processing-status endpoint to track progress. The booking decisions Routespring derives are surfaced as Action Items — see the Action Items section for how to retrieve and act on them.

Downloadable artifacts (output workbook, actions CSV, record mapping, summary, source file)

Booking configuration (hotels, flights, rules)