Tutorial · Day of operations
Build an automated IROPS recovery workflow.
When a disruption breaks a pairing, the workflow should identify the crew need once, execute the eligible travel quickly, and preserve a clear record for people and finance. This tutorial shows how to build that loop with the current v1 API.
Updated Current v1 tutorial
Implementation summary
- Trigger
- A disruption decision from the airline flight-status, crew scheduling, or OCC system.
- Current v1 input
- POST /crew/action-items or an operator-selected POST /crew/bookings/request.
- Human boundary
- The airline detects the event and owns operational judgment; review and failed states remain visible.
- Result
- Hotel and flight bookings grouped by one irop_ref for operations and finance reporting.
The real-life scenario
An EWR cancellation leaves a crew member unable to reach the next duty in SLC. OCC decides that the crew needs one hotel night and a replacement deadhead flight arriving before 14:00 UTC. Instead of opening separate hotel, flight, support, and reporting threads, the integration creates both travel requirements under one IROP reference.
Design the operating loop
1. Detect and decide in the airline operation
Your flight-status, crew scheduling, or OCC system identifies the disruption and decides which crew need a hotel, deadhead flight, extension, reroute, or cancellation.
2. Create one correlated IROP event
Assign one airline-owned irop_ref and reuse it across every booking created for the event. This becomes the operational and financial join key.
3. Execute against configured policy
Let Routespring search and auto-select with POST /crew/action-items, or present live flight choices and commit a selected option with POST /crew/bookings/request.
4. Route exceptions to people
Treat NEEDS_REVIEW and PENDING_REVIEW as work queues. Retry FAILED supplier calls only when the underlying failure is retryable.
Path A: let Routespring select and book
Use POST /crew/action-items when the airline knows the required route or hotel stay but wants Routespring to search, apply configured policy, select a supplier, and book asynchronously. Send a unique idempotency key for each crew member and requirement so an OCC retry cannot create a duplicate booking.
export IROP_REF="IROP-2026-05-18-EWR-001"
ACTION=$(curl -sS -X POST "$BASE/crew/action-items" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $IROP_REF-EMP-12047-hotel-1" \
-d '{
"type": "HOTEL",
"classification": "IROP_HOTEL_EXTEND",
"priority": "P2",
"source": "IROP",
"irop_ref": "IROP-2026-05-18-EWR-001",
"anchors": {
"traveller_email": "jordan.reyes@flymx.com",
"employee_id": "EMP-12047",
"pairing_number": "P-23845"
},
"hotel": {
"city": "SLC",
"check_in_date": "2026-05-18",
"check_out_date": "2026-05-19"
},
"notes": "Pairing extended after the original positioning leg was cancelled."
}')
echo "$ACTION" | jq .Path B: let an operator select the exact flight
Use this path when policy or operational judgment requires a person to choose the exact itinerary. Search live offers, display them in the OCC tool, then commit the selected flight_option_id. Offers are time-sensitive, so re-search if a commit returns an expiration-related review state.
# Reuse the same IROP reference assigned for this disruption event.
export IROP_REF="IROP-2026-05-18-EWR-001"
# Search live options when an operator must select the exact flight.
OPTIONS=$(curl -sS -G "$BASE/crew/flight-options" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
--data-urlencode "from_airport=EWR" \
--data-urlencode "to_airport=SLC" \
--data-urlencode "date=2026-05-18" \
--data-urlencode "arrive_by=2026-05-18T14:00:00Z")
export FLIGHT_OPTION_ID=$(echo "$OPTIONS" | jq -r '.options[0].flight_option_id')
curl -sS -X POST "$BASE/crew/bookings/request" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $IROP_REF-EMP-12047-flight-1" \
-d "{
\"type\": \"FLIGHT\",
\"classification\": \"IROP_NEW_DEADHEAD\",
\"source\": \"IROP\",
\"irop_ref\": \"$IROP_REF\",
\"anchors\": {
\"traveller_email\": \"jordan.reyes@flymx.com\",
\"employee_id\": \"EMP-12047\",
\"pairing_number\": \"P-23845\"
},
\"flight\": { \"flight_option_id\": \"$FLIGHT_OPTION_ID\" }
}" | jq .Monitor the event, not separate tickets
Query by irop_ref to retrieve every hotel and flight booking created for the disruption. For each booking, refresh the supplier state until it is confirmed or reaches a state that requires action.
# Retrieve every booking tied to the disruption.
curl -sS -G "$BASE/crew/bookings" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
--data-urlencode "irop_ref=$IROP_REF" | jq .
# Refresh a booking and read its full state-transition history.
curl -sS "$BASE/crew/bookings/$BOOKING_ID/status" \
-H "Authorization: Bearer $ACCESS_TOKEN" | jq .CONFIRMED or MODIFIED
The booking is in place. Persist the supplier confirmation and final rate.
PENDING
The supplier call is still running. Continue polling with bounded backoff.
NEEDS_REVIEW
No supplier call was made. Send the item to an operator with the policy reason.
FAILED
The supplier call failed. Inspect error_message before using the retry endpoints.
Close the disruption record
- Store the airline irop_ref on the incident record before creating any booking.
- Store every action_id, booking_id, supplier confirmation, status, and booked rate returned for the event.
- Keep injected bookings under manual_override while OCC owns the recovery decision.
- Release manual_override only when later roster submissions should manage the booking again.
- Feed the IROP booking set into the reconciliation workflow for event-level cost review.