Connector API · v1

API reference

One REST API for every supplier on Supplier.Travel. Your system calls Connector. Connector calls each supplier your account can use, normalises the answers into one contract and keeps the booking record. Supplier connections, credentials and protocols are operated by Supplier.Travel, so nothing in this reference changes when a supplier is added.

All requests and responses are JSON over HTTPS (TLS 1.2+). Contracts are versioned per vertical (/hotels/v1, /flights/v1). Additive fields can appear at any time, so ignore fields you don't know. Breaking changes ship only as a new major version.

Quickstart

1. Create an agency account. It starts on the free Sandbox plan.
2. In the console, open API keys and create a key. Copy it once; it is never shown again.
3. Search hotels:

curl https://sandbox.connector.supplier.travel/hotels/v1/search \
  -H "Authorization: Bearer $CONNECTOR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "checkin": "2026-12-10", "checkout": "2026-12-12",
    "rooms": [{ "adults": 2 }],
    "destination": { "city_name": "Dubai", "country_code": "AE" },
    "currency": "USD", "guest_nationality": "AE"
  }'

Then prebook a rates[].id from the response and book the prebook. The booking flow walks through each step.

Authentication

Send your API key as a bearer token (or as X-API-Key):

Authorization: Bearer stk_9Kd2ZwBe…

• Keys belong to your agency. They inherit its supplier access, plan and markup.
• Create one key per system (booking engine, staging, back office) so you can revoke one without touching the others. Revocation is immediate.
• Keep keys server-side. Never embed them in browsers or mobile apps.
• A missing, unknown or revoked key returns 401 UNAUTHENTICATED.

Conventions

Money

Every amount is an integer in the currency's minor unit. decimals is the exponent: USD 2, KWD/OMR/BHD 3, JPY 0. Divide by 10^decimals for display. Nothing is hidden: total = supplier_total + platform_fee + markup.

"price": {
  "currency": "USD", "decimals": 2,
  "base": 17829,          // supplier base before included taxes
  "taxes": 3922,          // taxes and fees included in supplier_total
  "supplier_total": 21751,
  "platform_fee": 0,
  "markup": 544,          // your account markup
  "total": 22295
}

pay_at_property[] lists mandatory fees that are not in total and are collected by the hotel, such as tourism fees. Show them before checkout.

Identifiers

Ids are opaque strings such as nuitee~lp1b30d1, pb_7sptjqj2j3qre5iy or bk_vnio3epwl2pccmcx. Store them as text; rate ids can exceed 1,000 characters, so they always travel in JSON bodies.

Dates and times

Stay dates are YYYY-MM-DD. Timestamps are RFC 3339 in UTC (2026-12-08T10:00:00Z).

Partial results

Searches go to all your suppliers in parallel under one deadline. Every search response includes supplier_status[], one entry per supplier, with an outcome: ok, no_results, timeout, error, circuit_open, overloaded or skipped. partial: true means at least one supplier did not answer completely. A failed supplier never contributes results, so "no availability" and "supplier unavailable" are always distinguishable.

Request ids

Every response carries X-Request-Id. Send your own ([A-Za-z0-9._-]{1,64}) to correlate logs, and quote it when contacting support.

Limits

Hotels — booking flow

1. Destination GET /hotels/v1/destinations?q=: autocomplete for cities, hotels and landmarks. Each suggestion carries a ready-made destination object.
2. Search POST /hotels/v1/search: priced offers across every supplier available to you, stored as a search session. The response holds page 1, facets for filters, and a search_id.
3. Refine GET /hotels/v1/searches/{search_id}: filter, sort and page the session for 20 minutes without calling suppliers again.
4. Hotel page GET /hotels/v1/hotels/{id} and …/reviews: photos, room types, facilities, policies and guest reviews.
5. Prebook POST /hotels/v1/prebooks: the supplier confirms price and conditions, valid for 20 minutes.
6. Book POST /hotels/v1/bookings with an Idempotency-Key. The agency net is charged to your account.
7. Service: list, retrieve, refresh, change the lead guest, quote and cancel.

Destinations

{ "suggestions": [
  { "type": "city", "id": "city:AE:Dubai", "name": "Dubai", "subtitle": "United Arab Emirates",
    "country_code": "AE", "hotel_count": 8209, "destination": { "city_name": "Dubai", "country_code": "AE" } },
  { "type": "place", "id": "place:ChIJ…", "name": "Dubai Marina", "subtitle": "Dubai, AE",
    "destination": { "place_id": "ChIJ…" } },
  { "type": "hotel", "id": "hotel:nuitee~lp1b30d1", "name": "Rove Dubai Marina", "subtitle": "Dubai, AE",
    "destination": { "hotel_ids": ["nuitee~lp1b30d1"] } } ] }

Matching ignores case and accents. Cities and hotels come from our synced master data and are instant; areas and landmarks come from the supplier. Pass a suggestion's destination unchanged into search. limit is 1–25, default 10.

Search

{
  "checkin": "2026-12-10",
  "checkout": "2026-12-13",
  "rooms": [ { "adults": 2, "children_ages": [5] } ],
  "destination": { "country_code": "AE", "city_name": "Dubai" },
  "currency": "USD",
  "guest_nationality": "AE",
  "max_hotels_per_supplier": 100,
  "max_rates_per_hotel": 20,
  "sort": "recommended",
  "page_size": 20,
  "filters": { "star_ratings": [4, 5], "refundable_only": true }
}

Response:

{
  "request_id": "req_8d96fda5", "service": "hotels", "schema_version": "1.0",
  "generated_at": "2026-10-09T05:25:10Z",
  "search_id": "srch_054c05d48b0b6fe4899f0acb", "expires_at": "2026-10-09T05:45:10Z",
  "nights": 3, "partial": false,
  "supplier_status": [ { "supplier_id": "nuitee", "outcome": "ok", "duration_ms": 11821, "offer_count": 169 } ],
  "sort": "recommended", "filters": { … }, "page": 1, "page_size": 20,
  "total_offers": 109, "total_hotels": 169,
  "facets": {
    "star_ratings": { "0": 7, "3": 19, "4": 43, "5": 100 },
    "board_types": { "room_only": 147, "breakfast": 30, "half_board": 2 },
    "refundable": 109, "price_min": 17800, "price_max": 533400, "currency": "USD",
    "property_types": [ { "id": 204, "name": "Hotels", "count": 131 } ],
    "chains": [ { "id": 1763, "name": "Jumeirah", "count": 6 } ]
  },
  "offers": [ {
    "id": "nuitee~lp40986", "supplier_id": "nuitee", "price_recheck_required": true,
    "hotel": { "id": "nuitee~lp40986", "name": "Holiday Inn Express Dubai Internet City", "star_rating": 3,
               "review_score": 8.4, "review_count": 4289, "address": "Knowledge Village",
               "city": "Dubai", "country_code": "AE", "latitude": 25.1042, "longitude": 55.1662,
               "distance_m": 483, "chain": "Holiday Inn Express", "property_type": "Hotels",
               "thumbnail": "https://…", "main_photo": "https://…" },
    "from_price": { "currency": "USD", "decimals": 2, "base": 23518, "taxes": 0,
                    "supplier_total": 23518, "platform_fee": 0, "markup": 706, "total": 24224 },
    "rates": [ {
      "id": "nuitee~3gAYonJz…", "name": "Standard King Room",
      "board_code": "RO", "board_name": "Room Only", "board_type": "room_only",
      "rooms": [ { "room_number": 1, "name": "Standard King Room", "adults": 2, "children_ages": [5],
                   "max_occupancy": 3, "room_type_id": "1321525043" } ],
      "cancellation": { "refundable": true, "free_cancellation_until": "2026-12-08T10:00:00Z",
                        "penalties": [ { "from": "2026-12-08T10:00:00Z", "amount": 23518, "currency": "USD" } ] },
      "pay_at_property": [ { "description": "Tourism fee", "amount": 816, "currency": "USD" } ],
      "price": { … }, "price_per_night": 8075, "suggested_retail": 27100,
      "payment_type": "prepaid", "perks": ["Free WiFi"]
    } ]
  } ]
}

• total_hotels counts the whole session; total_offers counts what matches the current filters. Facets always describe the whole session, so filter options never disappear while the user narrows down.
• recommended ranks by guest score weighted by review volume, star rating, price relative to the result set, and flexibility. It is deterministic for a session.
• distance_m is measured from the search point, or for city searches from the median position of the results (robust to mis-geocoded hotels).
• board_type normalises supplier meal codes to room_only, breakfast, half_board, full_board, all_inclusive or other. board_code and board_name stay as the supplier sent them.
• price_per_night is price.total ÷ nights in minor units, for display only.
• room_type_id joins a rate to rooms[].id on the hotel page for photos, beds and size.
• cancellation.refundable is false for non-refundable rates and absent when the supplier did not say. Penalties apply from from onwards.
• suggested_retail is the supplier's recommended public price. Selling below it publicly can breach rate-parity terms.

Refine a search

Returns the same response shape for the stored session, with no supplier calls, so it answers in milliseconds. Every filter is a query parameter; lists are comma-separated. A session belongs to the account that created it and expires at expires_at (20 minutes); after that you get 410 SEARCH_EXPIRED and should search again.

Hotel page

Returns every hotel field plus description (plain text), images[], facilities[], checkin_from, checkout_by, phone, important_information, reviews_url, and:

"rooms": [ { "id": "1321525043", "name": "Standard King Room with Sofa Bed", "size_sqm": 26,
             "max_adults": 2, "max_children": 2, "max_occupancy": 3,
             "beds": [ { "type": "Extra-large double bed", "quantity": 1, "size": "181-210 cm wide" } ],
             "amenities": ["Free WiFi", "Rain shower", …], "views": ["City view"], "images": [ { "url": "https://…" } ] } ],
"policies": { "children_allowed": true, "pets_allowed": false, "parking": "free" }

Content is cached for 24 hours.

{ "hotel_id": "nuitee~lp40986", "total": 4289, "average_score": 9.5,
  "reviews": [ { "score": 10, "name": "Ahmad", "country": "AE", "traveller_type": "solo traveller",
                 "date": "2026-09-19T00:00:00Z", "headline": "…", "pros": "…", "cons": "…", "language": "en-gb" } ] }

total is the property's lifetime review count. average_score averages only the reviews returned; show the hotel's review_score as the headline score. limit is 1–100. Reviews are cached for 6 hours.

Master data

Static content synced daily from suppliers, for building your own catalogue, mapping and filters. Hotels carry ids, name, address, coordinates, stars, review score and count, chain, property type, facility ids and photos, and are paged up to 1,000 at a time with a total. Cities include hotel_count. Reference data lists countries, facilities, chains and property_types with the ids used by filters. Only suppliers available to your account are included. Prices and availability are never cached: they always come from search.

Prebook

{ "rate_id": "nuitee~3gAYonJz…" }

201 Created returns the prebook: id (pb_…), hotel_id, checkin, checkout, rooms[], board, cancellation, pay_at_property[], price, suggested_retail, terms, expires_at and three change flags: price_changed, cancellation_changed and board_changed. If any flag is true, show the new terms before booking. A rate that has gone returns 409 SUPPLIER_REJECTED_REQUEST; search again.

Book

Requires an Idempotency-Key header: 8–128 characters of A-Z a-z 0-9 . _ : -. Create one per checkout and store it with your order, so every retry of that checkout reuses it.

Idempotency-Key: order-4815-attempt-1

{
  "prebook_id": "pb_7sptjqj2j3qre5iy",
  "client_reference": "agency-ref-1001",
  "holder": { "first_name": "Ana", "last_name": "Lee", "email": "ana@example.com", "phone": "+971500000000" },
  "guests": [ { "room_number": 1, "first_name": "Ana", "last_name": "Lee", "remarks": "late arrival" } ]
}

Send exactly one lead guest per prebooked room. Use legal names: letters, spaces and ' . -, up to 50 characters. client_reference is your own id; it is echoed back and searchable.

Payment. Rates are payment_type: "prepaid": the agency net (price.supplier_total + price.platform_fee) is held on your account when the booking starts, charged when the supplier confirms and released if it fails. Your markup is never charged; you collect it from the traveller. Without enough available credit the call returns 402 INSUFFICIENT_CREDIT before any supplier call.

Retrieve and list

The first form returns the stored booking. refresh=true re-reads it from the supplier; for an unknown booking it looks up our reference at the supplier, and after 30 minutes with no match the booking becomes failed. The list returns {bookings, total, page, page_size}, newest first, for API and console bookings alike. q matches the booking id, your reference, the supplier reference, the hotel and guest names. page_size is 1–500.

Change the lead guest

{ "holder": { "first_name": "Tess", "last_name": "Lee", "email": "tess@example.com" }, "remarks": "name correction" }

Sends a name change to the supplier and returns the booking with a new entry in amendments[] (status: "requested"). Suppliers process it asynchronously; refresh to see the result. Dates, rooms and rates cannot be amended: cancel and rebook. Only confirmed bookings can be amended (409 NOT_AMENDABLE).

Cancel

{ "booking_id": "bk_23bkvteay6qvpika", "cancellable": true, "free_cancellation_until": "2026-11-18T08:01:00Z",
  "fee": 0, "refund": 20102, "currency": "USD", "as_of": "2026-10-08T11:22:37Z",
  "note": "Estimate from the cancellation policy agreed at booking; the supplier confirms the final fee." }

Show the quote before the user confirms. The fee is the latest penalty that applies now.

Cancels a confirmed booking under the supplier's policy. The response is the booking with status: "cancelled" and cancellation_result {cancelled_at, fee, refund, currency}. The refund is credited to your account (never more than was charged). Refund your markup under your own terms. A repeat cancel is a no-op. An unknown booking returns 409 NOT_CANCELLABLE until a refresh resolves it.

Account and statement

{ "account": { "id": "org_t8e1akym0r_h", "currency": "USD", "credit_limit": 1000000, "balance": -20102,
               "held": 0, "available": 979898, "updated_at": "…" },
  "entries": [ { "id": "le_61b9…", "at": "…", "type": "charge", "amount": -20102, "currency": "USD",
                 "booking_id": "bk_23bk…", "note": "booking confirmed", "actor": "api:stk_Q3pX7aLm", "balance_after": -20102 } ] }

available = credit_limit + balance − held. Entry types are topup, adjustment, charge and refund; holds appear in held. actor is the console user or api: plus the key prefix that made the booking.

Flights — search beta

{
  "slices": [ { "origin": "DXB", "destination": "LHR", "departure_date": "2027-02-15" } ],
  "passengers": { "adults": 1, "children": 0, "infants": 0 },
  "cabin_class": "economy",
  "currency": "AED",
  "market": "AE",
  "max_offers_per_supplier": 50
}

One slice is one-way, two make a return trip, and more make multi-city (up to 6). The response uses the same envelope with offers[]. Each offer has itineraries[].segments[] (carriers, flight number, airports, local times, cabin, booking class, aircraft), fare (brand, fare basis, refundable, changeable, baggage), price and expires_at. Flight booking is on the roadmap.

Suppliers

Lists the suppliers available to your account, their services and their health:

{ "suppliers": [ { "id": "nuitee", "name": "Nuitee", "kind": "nuitee", "api_version": "liteapi-v3.0",
                   "services": ["hotels"], "circuit_state": "closed" } ] }

circuit_state is closed when healthy and open while a supplier is temporarily skipped after repeated failures. Which suppliers you see depends on your plan and on each supplier's distribution settings, and can change without any change on your side.

Liveness check; no authentication.

Objects

Booking

Errors

{ "error": { "code": "INVALID_REQUEST", "message": "request failed validation",
             "request_id": "req_…", "fields": [ { "field": "checkout", "message": "must be after checkin" } ] } }

Branch on code, never on message. retryable: true marks errors that are safe to retry with backoff.

Go-live checklist

• API keys live on your servers only; one key per system.
• When partial is true, tell users some suppliers did not respond.
• Results use search_id refinement for filters, sorting and paging instead of new searches.
• Checkout shows total, board, cancellation policy and pay_at_property fees from the prebook.
• Show the cancellation quote before cancelling, and keep enough account credit for your booking volume.
• One Idempotency-Key per checkout, stored with the order and reused on retry.
• On 202 unknown, poll GET …?refresh=true (for example every 20 s for 5 minutes) before telling the traveller anything.
• Store both id and supplier_booking_id; use id for follow-ups.
• Log X-Request-Id with every call.

Changelog

Questions? developers@supplier.travel · Quote your X-Request-Id.