Skip to main content

Quick Start

This walk-through drives one disruption end-to-end against your sandbox tenant — policy → case → demand → allocation → booking → voucher. Every call hits the live Nexa SaaS API; nothing is installed locally.

Time: ~10 minutes.

0. Set up your shell​

Before you start, get a service token from the operations console (see API Access) and export it together with the regional base URL.

export NEXA_BASE_URL="https://us-central1.api.nexastudio.io"
export TOKEN="<your service token>"

All curl commands below assume Authorization: Bearer $TOKEN.

1. Create and activate a policy​

A policy defines how hotels are searched and scored for a given tier.

curl -X POST "$NEXA_BASE_URL/policies" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Economy — default",
    "airport": "MAD",
    "tiers": ["ECONOMY", "PREMIUM_ECONOMY"],
    "constraints": {
      "minStars": 3,
      "maxDistanceKm": 30,
      "maxNightlyRate": 180
    },
    "mode": "BATCH",
    "autoApproveDemand": true,
    "maxAutomaticRoomsPerWave": 200
  }'

Grab the policyUrn from the response and activate it:

curl -X POST "$NEXA_BASE_URL/policies/$POLICY_URN/activate" \
  -H "Authorization: Bearer $TOKEN"

2. Post a disruption event​

curl -X POST "$NEXA_BASE_URL/cases" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "externalEventId": "EVT-MAD-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": [
      {
        "pnr": "ABC123",
        "tier": "ECONOMY",
        "passengers": [
          { "referenceId": "PAX-1", "type": "ADT" },
          { "referenceId": "PAX-2", "type": "ADT" }
        ]
      }
    ]
  }'

Nexa dedupes on externalEventId, calculates the stay plan from the reaccommodation, and returns a caseUrn in status OPEN.

3. Create demand​

curl -X POST "$NEXA_BASE_URL/demand/case/$CASE_URN" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "type": "INITIAL", "roomsRequested": 1 }'

Because autoApproveDemand is true and the request is within maxAutomaticRoomsPerWave, the demand transitions straight to APPROVED and enqueues an allocation job.

If you want a manual checkpoint, create the policy with autoApproveDemand: false and call:

curl -X POST "$NEXA_BASE_URL/demand/$DEMAND_URN/approve" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{ "reason": "ops-reviewed" }'

4. Watch allocation and booking​

Allocation and booking happen asynchronously on Nexa's workers. Poll the case:

watch -n 2 "curl -s '$NEXA_BASE_URL/cases/$CASE_URN' \
  -H 'Authorization: Bearer $TOKEN' | jq '.status, .wave.allocations'"

You will see the case progress through:

OPEN → ALLOCATING → BOOKING → CONFIRMED

For each allocation the engine persists:

  • candidateHotelUrns — every candidate evaluated
  • rankingInputs — cost, distance, amenities, score
  • allocations[] — the assignments finally selected, with per-group cost

For a real-time push view, subscribe to the case event stream:

curl -N "$NEXA_BASE_URL/events/stream?case=$CASE_URN" \
  -H "Authorization: Bearer $TOKEN"

5. Fetch the voucher​

curl "$NEXA_BASE_URL/booking/reservations/$RESERVATION_URN/voucher/html" \
  -H "Authorization: Bearer $TOKEN" \
  -o voucher.html
open voucher.html

The voucher contains the hotel, dates, next-flight info, passenger list, and the corporate-billing confirmation code.

6. Trigger notifications​

In sandbox the SendGrid adapter runs as a limited delivery channel: the "send" is captured with a synthetic message ID and shown in the console.

curl -X POST "$NEXA_BASE_URL/notifications/$CASE_URN/send" \
  -H "Authorization: Bearer $TOKEN"

Promoting the tenant to production swaps the limited channel for real SendGrid delivery — the API surface is identical.

7. Inspect the audit trail​

Every state change, approval, provider call, and agent action is recorded immutably:

curl "$NEXA_BASE_URL/audit/case/$CASE_URN" \
  -H "Authorization: Bearer $TOKEN" | jq

Where to next​

Was this helpful?