Manual Review

Manual review is Nexa's escape hatch. When automation cannot resolve a case, a review item is created with everything an operator needs to decide — including recommendations from the exception agent.

Categories

Category	Priority	What happened
ALLOCATION_FAILED	HIGH	No policy-compliant hotels available
BOOKING_FAILED	HIGH	Every attempted hotel refused or errored
PAYMENT_FAILED	MEDIUM	PSP rejected the card / token
PARTIAL_FULFILLMENT	MEDIUM	Some groups booked, others failed
POLICY_VIOLATION	LOW	No policy matched the case context
MIXED_TIER_GROUP	LOW	A group's passengers span multiple tiers
DATA_INCOMPLETE	LOW	Manifest missing required fields

Review item shape

{
  "urn": "urn:nexa:review:abc",
  "caseUrn": "urn:nexa:case:xyz",
  "category": "BOOKING_FAILED",
  "priority": "HIGH",
  "attemptedHotels": [
    { "hotelUrn": "...", "reason": "hotel-full", "providerError": "..." },
    { "hotelUrn": "...", "reason": "payment-refused" }
  ],
  "affectedGroups": ["GRP-3", "GRP-5"],
  "recommendations": [
    { "action": "rebook",    "hotelUrn": "...", "reason": "policy-compliant, 18km", "source": "agent" },
    { "action": "relaxPolicy","fields": ["maxDistanceKm"], "value": 40, "source": "agent" }
  ],
  "state": "OPEN",
  "assignedTo": "urn:nexa:user:opsA"
}

Operator workflow

1. Claim

Claiming an item prevents two operators from working on the same thing:

curl -X POST https://us-central1.api.nexastudio.io/manual-review/$ITEM_URN/claim \
  -H "Authorization: Bearer $TOKEN"

2. Review the context

Everything lives on the item:

• What was attempted
• Why each attempt failed (provider error, policy gate, payment refusal)
• The agent's top 3 recommendations, ranked by viability
• Links to the relevant case, wave, and reservations

3. Act

The item exposes the safe actions:

# Re-book against a specific hotel
curl -X POST https://us-central1.api.nexastudio.io/manual-review/$ITEM_URN/rebook \
  -H "Authorization: Bearer $TOKEN" \
  -d '{ "hotelUrn": "urn:nexa:hotel:alt", "reason": "agent rec #1" }'

# Relax policy for this case only
curl -X POST https://us-central1.api.nexastudio.io/manual-review/$ITEM_URN/relax \
  -H "Authorization: Bearer $TOKEN" \
  -d '{ "fields": { "maxDistanceKm": 40 }, "reason": "airport hotels all booked" }'

# Split a mixed-tier group
curl -X POST https://us-central1.api.nexastudio.io/manual-review/$ITEM_URN/split \
  -H "Authorization: Bearer $TOKEN" \
  -d '{ "into": [["PAX-1"], ["PAX-2","PAX-3"]], "reason": "accessibility" }'

# Override with manual booking
curl -X POST https://us-central1.api.nexastudio.io/manual-review/$ITEM_URN/override \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "hotelUrn": "urn:nexa:hotel:abc",
    "providerOfferId": "...",
    "reason": "front-desk phone confirmation"
  }'

4. Resolve

curl -X POST https://us-central1.api.nexastudio.io/manual-review/$ITEM_URN/resolve \
  -H "Authorization: Bearer $TOKEN" \
  -d '{ "resolution": "REBOOKED", "reason": "booked backup hotel via agent rec" }'

The item is closed, the case transitions back into the normal flow, and the audit log captures the actor + reason.

The exception agent's role

When a review item is created, the Nexa Exception Agent — a Nexa Trained Model on Google, enabled per-tenant — is invoked to produce recommendations. It operates via an allow-list of tools — it can:

• Search alternate hotels (within and outside the current policy).
• Calculate the cost of a proposed policy relaxation.
• Classify the failure cause.

It cannot directly book, cancel, or send notifications. Every recommendation is a proposal the human approves. See Exception agent.

SLA and escalation

Manual review items carry a priority. Each tenant can configure SLAs per priority (for example: HIGH → 15 min, MEDIUM → 1 h, LOW → 4 h). Breached SLAs:

• Page the on-call via the tenant's configured alerting channel.
• Escalate priority one level.
• Append an audit entry.

Post-mortem

Closed items contribute to weekly ops reports:

• Breakdown by category
• Mean time to resolve
• % resolved by agent recommendation acceptance
• Top failing policies and providers

Use this to tune policies, provider weights, and agent prompts.