Cases

A case is the unit of work. This page is the operator's field manual for creating, monitoring, modifying, and closing cases.

Creating a case

Cases are normally created by upstream airline systems via the POST /cases webhook — but you can create them manually for drills, tests, or when the airline feed is down.

curl -X POST https://us-central1.api.nexastudio.io/cases \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "externalEventId": "MANUAL-2026-04-22-001",
    "flight": { "number": "XX123", "origin": "MAD", "destination": "JFK",
                "scheduledDeparture": "2026-04-22T18:00:00Z", "status": "CANCELLED" },
    "nextFlight": { "number": "XX125", "scheduledDeparture": "2026-04-23T10:00:00Z" },
    "passengerGroups": [ ... ]
  }'

Bulk passenger upload

For large disruptions, upload passengers via Excel:

curl -X POST https://us-central1.api.nexastudio.io/cases/$CASE_URN/passengers:bulk \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@passengers.xlsx"

The Excel template is in the Ops Console under Cases → New → Bulk import.

Inspecting a case

curl https://us-central1.api.nexastudio.io/cases/$CASE_URN \
  -H "Authorization: Bearer $TOKEN" | jq

Key fields to watch:

• status — current lifecycle state.
• passengerGroups[].operationalStatus — per-passenger progress.
• wave.allocations[] — what was assigned and why.
• reservations[].status — booking state per group.
• manualReviewItems[] — anything stuck and why.

Re-accommodation

When the airline sends an updated next-flight, Nexa recomputes the stay plan automatically on PATCH /cases/:urn/reaccommodate. It will:

1. Extend or shorten active reservations through provider modification where possible.
2. Queue re-booking for groups whose new stay plan no longer fits their reservation.
3. Mark passengers as LOCAL_RESIDENT if the new connection leaves them without an overnight gap.

Audit captures the delta:

curl "https://us-central1.api.nexastudio.io/audit?entity=case&entityUrn=$CASE_URN&action=reaccommodate"

Splitting and merging groups

Groups default to their PNR. You can split a group when, for example, one PNR contains passengers with different accessibility needs:

curl -X POST https://us-central1.api.nexastudio.io/cases/$CASE_URN/groups/$GROUP_ID/split \
  -H "Authorization: Bearer $TOKEN" \
  -d '{ "into": [["PAX-1","PAX-2"], ["PAX-3"]], "reason": "accessibility" }'

Merging is the inverse, typically used when siblings under separate PNRs arrive on the same manifest:

curl -X POST https://us-central1.api.nexastudio.io/cases/$CASE_URN/groups:merge \
  -H "Authorization: Bearer $TOKEN" \
  -d '{ "groupIds": ["GRP-1","GRP-2"], "reason": "family-merge" }'

Split / merge after booking

Splitting or merging after a booking is confirmed requires a re-booking round. The orchestrator will cancel the affected reservation (where the provider supports it), re-allocate, and re-book.

Closing a case

Cases close automatically when all reservations reach CHECKED_OUT. You can close early with a reason:

curl -X POST https://us-central1.api.nexastudio.io/cases/$CASE_URN/close \
  -H "Authorization: Bearer $TOKEN" \
  -d '{ "reason": "airline-rerouted" }'

Closure locks audit state and prevents further state changes. If you need to reopen, contact ADMIN — they have a POST /cases/:urn/reopen endpoint gated by audit.

Operator actions and roles

Action	Role
Create case manually	OPS_SUPERVISOR, ADMIN
Approve demand	OPS_SUPERVISOR, ADMIN
Override allocation	OPS_SUPERVISOR, ADMIN
Resolve manual review	AIRPORT_OPERATOR (scoped to airport)
Close case	AIRPORT_OPERATOR, OPS_SUPERVISOR
Reopen case	ADMIN
Run a drill / shadow case	ADMIN

Role scoping is per-airport. An AIRPORT_OPERATOR with MAD in their claims cannot act on a GRU case, even via the API.