API v2: air, hotels, agencies and corporates

Base URL: https://searchurtrip.com/api/v2 · Spec: /api/v2/openapi.json · Interactive reference

v2 adds air and hotel search-and-book flows with live supplier inventory, plus endpoints specific to agencies (wallet) and corporates (employees, cost centres, policies). Keys, scopes, rate limits, request signing, idempotency, errors and webhooks work exactly as in v1, so one key works on both versions. v1 stays available.

Your account type decides the price

Every offer carries a price object shaped for you:

Account	`price` fields	Booking is paid by
Agency	`total` (net — what your wallet is debited), `sellPrice` (net plus your own markup), `commission`	Wallet balance plus credit line
Corporate	`total`, `baseAmount`, `tax`, `fee`	Your invoice

GET /me returns tenantType (agency, corporate or unlinked), whether flights and hotels are live or simulated, and — for agencies — the wallet.

Scopes

v2 reuses the v1 scopes and adds two:

Scope	Allows
`search:read`	`/air/`, `/hotels/` (search, rooms, revalidate), `/cars/search`
`bookings:write`	`POST /air/bookings`, `POST /hotels/bookings`, `POST /bookings/{id}/cancel`
`bookings:read`	`GET /bookings`, `GET /bookings/{id}`
`wallet:read`	`GET /wallet`, `GET /wallet/ledger` (agencies only)
`corporate:read`	`GET /corporate/*` (corporates only)

Flights

POST /air/search           { "from": "DEL", "to": "BOM", "departDate": "2026-11-12", "adults": 1 }
POST /air/bookings         { "offerToken": "…", "passengers": [ … ] }     # Idempotency-Key required

Pick a fareOptions[].offerToken (or the flight's own offerToken) from the results and book it. For live fares the airline needs every traveller's details: send one passengers entry per adult and child on the offer; each needs title, firstName, lastName and dob, and the first needs a mobile or email.

Live fares are re-confirmed with the airline when you book. If the price moved you get 409 fare_changed; the new offerToken and prices are in error.details. Show the new price and book again with the new token. POST /air/revalidate does the same check earlier if you want to show a final price first.

Ticketing completes in the background. GET /bookings/{id} shows tickets.status and, once issued, tickets.ticketNumbers; subscribe to booking.created / booking.cancelled webhooks for changes.

Hotels

POST /hotels/search        { "city": "Mumbai", "checkIn": "2026-11-12", "checkOut": "2026-11-14" }
POST /hotels/rooms         { "offerToken": "<hotel offerToken>" }          # live inventory only
POST /hotels/bookings      { "offerToken": "<room offerToken>", "passengers": [ <lead guest> ] }

With live inventory, search returns hotels; open one with /hotels/rooms to get bookable room rates, then book a room token. The room is blocked with the supplier when you book and the price is confirmed (same fare_changed rule). With simulated inventory the search tokens are bookable directly.

Agencies: wallet bookings

A booking debits the wallet by price.total and credits your commission; upline markups and commissions are posted as in the portal. If the wallet plus credit line can't cover it you get 402 insufficient_credit and nothing is booked. Cancelling a booking refunds the wallet and reverses commission and upline payouts.

GET /wallet                                 balance, credit line, available, status
GET /wallet/ledger?type=booking&limit=50    newest first

Send customerRef to attach your end-customer's reference; reference is your own order id and is returned on every read.

Corporates: employees, cost centres and approvals

GET /corporate/employees | /cost-centers | /policies | /approvers
GET /corporate/spend?from=2026-10-01&to=2026-10-31       spend by cost centre

Tag a booking by adding corporate to the booking request:

{ "offerToken": "…", "passengers": [ … ],
  "corporate": { "employeeId": 12, "costCenterId": 3, "purpose": "Client workshop", "approverId": 2 } }

The employee must be Active (422 employee_inactive otherwise); the cost centre and approver must belong to your organisation.
If the total is above the employee policy's approvalThreshold, approverId is required (409 approval_required), and the approver's approvalLimit must cover the amount (422 approver_limit_exceeded).
Corporate bookings are billed on the invoice; nothing is debited at booking time. Cancelled bookings are excluded from spend.

Sandbox

wk_test_… keys run every check (validation, price, wallet funds, corporate policy) but persist nothing, charge nothing and book nothing with a supplier. Responses carry livemode: false and a TEST… PNR; test bookings are not returned by GET /bookings.

Managing keys yourself

If the platform administrator has switched on self-service for your client, you can create, edit (permissions and IP allow-list), rotate and revoke keys, and register webhook endpoints, from API Access in your portal. Keys are shown once at creation. Test and live keys are created separately; scopes that don't apply to your account type (wallet:read for corporates, corporate:read for agencies) aren't offered.