POST/v1/flights/order/:gdsprovider/:offerId

Create flight order

Creates an instant flight booking or hold order from a selected offer. Public bookings resolve internal price from offerId or tracked offer data.

POST/v1/flights/order/:gdsprovider/:offerId

API console

Try it

Send a real request to the sandbox API and inspect the response.

Credentials

Profile code

Public key

Secret key

Path parameters

2 fields

gdsproviderenumRequired

GDS provider

Global Distribution System used to source flight content. Select 0 for the default provider.

offerIdstringRequired

Offer ID

Identifier of the offer returned by a previous flight search request.

Request body

{
  "currency": "EUR",
  "passengers": [
    {
      "id": "pas_0000B7VCW4ca7emwcBOyUf",
      "type": "adult",
      "title": "mr",
      "phone_number": "+573128837058",
      "firstName": "Alejandro",
      "lastName": "Toledo",
      "gender": "m",
      "email": "jairotoledo2003@gmail.com",
      "bornDate": "2003-08-14"
    }
  ],
  "type": "instant"
}

cURL request

cURL

bash

curl -X POST 'https://api.sandbox.travelandz.com/v1/flights/order/0/:offerId' \
  -H 'Authorization: Bearer YOUR_SECRET_KEY' \
  -H 'X-Travelandz-Id: YOUR_PUBLIC_KEY:YOUR_PROFILE_CODE' \
  -H 'Content-Type: application/json' \
  -d '{"currency":"EUR","passengers":[{"id":"pas_0000B7VCW4ca7emwcBOyUf","type":"adult","title":"mr","phone_number":"+573128837058","firstName":"Alejandro","lastName":"Toledo","gender":"m","email":"jairotoledo2003@gmail.com","bornDate":"2003-08-14"}],"type":"instant"}'

Add your credentials to send a request.

Response

Click "Try it!" to send a request and see the response here.

Creates an instant flight booking or hold order from a selected offer. Public bookings resolve internal price from offerId or tracked offer data.

Endpoint

Method	Path	Auth
`POST`	`/v1/flights/order/:gdsprovider/:offerId`	Required API key

Required headers:

Header	Description
`Authorization`	`Bearer <secret_key>`. The secret is shown only once when the credential is created.
`X-Travelandz-Id`	`<public_key>:<profile_code>`. The `profile_code` is the `dp_`-prefixed Developer Profile code shown in your dashboard. This binds the request to a profile and credential.
`Content-Type`	Use `application/json` for requests with a body.

Request Params Schema

gdsprovider

numberYes

offerId

stringYes

Request Body Schema

currency

enum

EURUSDCNY

Yes

Currency requested for the public booking. Internal price is resolved by offerId or tracked offer data

passengers

arrayYes

passengers[]id

stringYes

Passenger id from the selected tracked public offer. It must exactly match the offer passenger id and type. Empty, missing, duplicate or extra passenger ids are rejected. Mystifly offers generate ids such as mystifly_pax_1.

passengers[]type

enum

adultchildinfant_without_seat

Yes

passengers[]title

enum

mrmsmrsmiss

Yes

passengers[]phone_number

string

Format: E.164 phone number

Yes

Satisfies passengers[].phone. In gdsprovider=1 flows, passengers[0].phone_number also satisfies holder.phone and derives holder.countryCode

passengers[]infant_passenger_id

stringNo

Required when the passenger is attached to an infant

passengers[]identity_documents

arrayNo

Identity document objects. Example: [{ type, unique_identifier, issuing_country_code, expires_on }]. Required when the offer or required-fields response asks for them

passengers[]firstName

stringYes

Satisfies passengers[].name from required-fields

passengers[]lastName

stringYes

Satisfies passengers[].lastName from required-fields

passengers[]gender

enum

mf

Yes

passengers[]email

stringYes

Satisfies passengers[].email. Some gdsprovider=1 flows only consume the first passenger email as the top-level holder email

passengers[]bornDate

string

Format: YYYY-MM-DD

Yes

passengers[]country

stringNo

2-letter ISO country code. Use when required-fields marks nationality as true

passengers[]NationalID

stringNo

Use when the selected flow requires a national identity number. In current gdsprovider=1 responses this can be implied by allowedDocuments including dni even without an explicit nationalId flag

passengers[]loyaltyProgrammeAccounts

arrayNo

Optional loyalty account objects. Example: [{ airlineIataCode, accountNumber }]. Use only when supportedLoyaltyPrograms includes the airline code

totalSegments

arrayYes

totalSegments[]originCode

stringYes

Mapped from offer.slices[].segments[].departure.iataCode

totalSegments[]destinationCode

stringYes

Mapped from offer.slices[].segments[].arrival.iataCode

totalSegments[]flightNumber

stringYes

Mapped from offer.slices[].segments[].flightNumber

totalSegments[]departureDate

string

Format: ISO 8601

Yes

Mapped from offer.slices[].segments[].departure.departingAt

holdId

stringNo

Only for providers that support hold payment

type

enum

instanthold

Default instant. hold only applies when the selected provider supports it

Success Response

Returns order identifiers, status and provider booking payload.

Response Body Schema

orderId

stringYes

holdExpiresAt

string

Format: ISO 8601

holdPriceGuaranteed

stringNo

liveMode

booleanYes

True when the request is served by the live Travelandz environment. This value comes from Travelandz, not the provider payload.

Operational Notes

Public booking always requires a tracked snapshot of the selected public offer for the same profile, gdsprovider and offerId.
passengers[].id is the passenger id from the tracked offer, not an internal user identifier.
passengers[].id and passengers[].type must exactly match the tracked offer passengers. Empty ids, duplicates, missing passengers, extra passengers or type mismatches are rejected.
Mystifly public offers generate internal passenger ids such as mystifly_pax_1, mystifly_pax_2, etc. Reuse those ids exactly as returned by the offer.
Do not send internal user identifiers; they are not part of the public booking contract.
Do not send originalPrice in public bookings. The API resolves internal price and currency from offerId or the tracked offer payload. If originalPrice is sent, public validation rejects the request as a non-whitelisted field.
Send identity_documents[] when the offer or required-fields endpoint indicates identity documents are required.
type=hold and holdId only apply when the selected booking flow supports hold payment.
totalSegments[] is only required when the selected booking flow needs segment metadata. Build it from every offer.slices[].segments[] item.

required-fields to create-order mapping

required-fields response	create-order field	Notes
`passengers[].title`	`passengers[].title`	Direct match
`passengers[].type`	`passengers[].type`	Direct match
`passengers[].name`	`passengers[].firstName`	Rename on booking body
`passengers[].lastName`	`passengers[].lastName`	Direct match
`passengers[].gender`	`passengers[].gender`	Direct match
`passengers[].bornDate`	`passengers[].bornDate`	Direct match
`passengers[].nationality`	`passengers[].country`	Use 2-letter ISO country code
`passengers[].phone`	`passengers[].phone_number`	E.164 format
`passengers[].email`	`passengers[].email`	In gdsprovider=1 flows, only the first passenger email can be consumed as holder email
`passengers[].documentIdentifier`	`passengers[].identity_documents[].unique_identifier`	Only when a document object is required
`passengers[].documentType`	`passengers[].identity_documents[].type`	Limited by `allowedDocuments`
`passengers[].documentExpiresAt`	`passengers[].identity_documents[].expires_on`	Only when required
`passengers[].documentCountryCode`	`passengers[].identity_documents[].issuing_country_code`	Only when required
`passengers[].allowedDocuments`	`passengers[].identity_documents[].type`	If it includes `dni`, also collect `passengers[].NationalID`
`holder.phone`	`passengers[0].phone_number`	Some flows derive holder contact from the first passenger
`holder.email`	`passengers[0].email`	Some flows derive holder contact from the first passenger
`holder.countryCode`	derived from `passengers[0].phone_number`	No separate booking field; use E.164 phone prefix

The generic flags age, address, city, postalCode and documentIssuedAt do not currently map to explicit public booking fields.

Nested passenger payloads

json

{
  "identity_documents": [
    {
      "type": "passport",
      "unique_identifier": "X1234567",
      "issuing_country_code": "ES",
      "expires_on": "2030-12-31"
    }
  ],
  "loyaltyProgrammeAccounts": [
    {
      "airlineIataCode": "BA",
      "accountNumber": "123456789"
    }
  ]
}

totalSegments example

json

[
  {
    "originCode": "MAD",
    "destinationCode": "BCN",
    "flightNumber": "1234",
    "departureDate": "2026-08-20T08:15:00"
  }
]

`totalSegments`	Source in `offer.slices[].segments[]`
`originCode`	`segment.departure.iataCode`
`destinationCode`	`segment.arrival.iataCode`
`flightNumber`	`segment.flightNumber`
`departureDate`	`segment.departure.departingAt`

Example

bash

curl -X POST https://api.sandbox.travelandz.com/v1/flights/order/0/offer_123 \
  -H "Authorization: Bearer $TRAVELANDZ_SECRET_KEY" \
  -H "X-Travelandz-Id: $TRAVELANDZ_PUBLIC_KEY:$TRAVELANDZ_PROFILE_CODE" \
  -H "Content-Type: application/json" \
  -d '{"currency":"EUR","type":"instant","passengers":[{"id":"pas_0001","type":"adult","title":"mr","phone_number":"+34612345678","firstName":"John","lastName":"Doe","gender":"m","email":"john.doe@example.com","bornDate":"1990-01-15","country":"ES"}]}'

Request Body - Example Value

json

{
  "currency": "EUR",
  "passengers": [
    {
      "id": "pas_0000B7VCW4ca7emwcBOyUf",
      "type": "adult",
      "title": "mr",
      "phone_number": "+573128837058",
      "firstName": "Alejandro",
      "lastName": "Toledo",
      "gender": "m",
      "email": "jairotoledo2003@gmail.com",
      "bornDate": "2003-08-14"
    }
  ],
  "type": "instant"
}

Responses

Code	Description
`200`	Flight order created successfully.
`400`	Bad request – invalid payload.
`401`	Unauthorized – invalid or missing credentials.
`403`	Forbidden – invalid credentials.
`500`	Internal server error

200 Response Body

Media type: application/json

json

{
  "orderId": "ord_0000B7VCdoZtPDdnjqCYIe",
  "liveMode": false
}