Quickstart

This walks through one complete one-way booking against staging. You’ll need an API user and a funded staging wallet from your account manager.

export BASE_URL="https://api.staging.ttool.travel/hub"

Authenticate

curl -X POST "$BASE_URL/api/v1/flights/authenticate" \
  -H "Content-Type: application/json" \
  -d '{ "username": "agency.api@example.com", "password": "********" }'

Keep the accessToken. It’s valid for expiresIn seconds (normally 3600).

export TOKEN="eyJhbGciOiJSUzI1NiIsImtpZCI6..."

curl -X POST "$BASE_URL/api/v1/flights/search" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Correlation-Id: my-booking-0001" \
  --max-time 120 \
  -d '{
    "adults": 1,
    "cabinType": "Economy",
    "flightType": "OneWay",
    "segments": [
      { "origin": "BGW", "destination": "DXB", "departureDate": "2026-12-07" }
    ]
  }'

Searches take 5 to 90 seconds. Note the requestId and pick an offer’s offerId from offers. Carrier and airport names for the codes in each offer are in dictionaries.

Check the offer

curl -X POST "$BASE_URL/api/v1/flights/details" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "requestId": "{requestId}", "proposalId": "{offerId}" }'

If priceHasChanges is true, show the new offer.price.total to the customer before going on.

Pick a fare family (optional)

Only when offer.hasFareBrands is true. Call fare-brands, choose a brand, then apply its key with change-options. Create the order with the offerId that change-options returns. See Fare families.

Create the order

curl -X POST "$BASE_URL/api/v1/flights/orders" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  --max-time 60 \
  -d '{
    "requestId": "{requestId}",
    "flightProposalId": "{offerId}",
    "contactInfo": { "email": "customer@example.com", "phoneNumber": "+9647701234567", "countryCode": "IQ" },
    "flightPassengers": [{
      "type": "Adult", "gender": "Male",
      "firstName": "JOHN", "lastName": "DOE",
      "birthDate": "1990-01-15", "birthCountryCode": "IQ",
      "docType": "Passport", "passportNumber": "A12345678",
      "passportIssueCountryCode": "IQ", "passportExpirationDate": "2030-01-15"
    }]
  }'

Nothing is booked and no money moves here. The response is the order with status Submit and its price.total: confirm it with the customer, and keep the orderId. To hold the seats without paying yet, add "holdOnly": true when the offer’s supportsOnHold is true. See On-hold bookings.

Creating an order isn’t idempotent. Never retry it automatically.

Issue

curl -X POST "$BASE_URL/api/v1/flights/orders/184233/issue" \
  -H "Authorization: Bearer $TOKEN" \
  --max-time 120

This books the seats and charges your wallet, in one call that takes 10 to 60 seconds. If the wallet is short you get 402 before anything is booked. Check status: IssuedSucceeded means you have ticket numbers in tickets. On a 504, wait 10 to 30 seconds and call again with the same orderId; the wallet isn’t charged twice.

Round trips come back in two shapes. Read Round trips before you build the results page.
Run the same flow with the Postman collection.

Get started

Guides

Reference

API endpoints

Next

​Next

Next