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

Flugauftrag erstellen

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

Property	Type	Details	Required	Notes
`gdsprovider`	`number`		Yes	-
`offerId`	`string`		Yes	-

Request Body Schema

Property	Type	Details	Required	Notes
`currency`	`enum`	`EURUSDCNY`	Yes	Currency requested for the public booking. Internal price is resolved by offerId or tracked offer data
`passengers`	`array`		Yes	-
`passengers[]id`	`string`		Yes	Passenger id from the selected offer. For gdsprovider=1, reuse the empty value if the offer sends an empty id
`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`	`string`		No	Required when the passenger is attached to an infant
`passengers[]identity_documents`	`array`		No	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`	`string`		Yes	Satisfies `passengers[].name` from required-fields
`passengers[]lastName`	`string`		Yes	Satisfies `passengers[].lastName` from required-fields
`passengers[]gender`	`enum`	`mf`	Yes	-
`passengers[]email`	`string`		Yes	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`	`string`		No	2-letter ISO country code. Use when required-fields marks `nationality` as true
`passengers[]NationalID`	`string`		No	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`	`array`		No	Optional loyalty account objects. Example: `[{ airlineIataCode, accountNumber }]`. Use only when supportedLoyaltyPrograms includes the airline code

`totalSegments`	`array`		Yes	-
`totalSegments[]originCode`	`string`		Yes	Mapped from offer.slices[].segments[].departure.iataCode
`totalSegments[]destinationCode`	`string`		Yes	Mapped from offer.slices[].segments[].arrival.iataCode
`totalSegments[]flightNumber`	`string`		Yes	Mapped from offer.slices[].segments[].flightNumber
`totalSegments[]departureDate`	`string`	`Format: ISO 8601`	Yes	Mapped from offer.slices[].segments[].departure.departingAt

`holdId`	`string`		No	Only for providers that support hold payment
`type`	`enum`	`instanthold`	No	Default instant. hold only applies when the selected provider supports it

Success Response

Returns order identifiers, status and provider booking payload.

Response Body Schema

Property	Type	Details	Required	Notes
`orderId`	`string`		Yes	-
`holdExpiresAt`	`string`	`Format: ISO 8601`	No	-
`holdPriceGuaranteed`	`string`		No	-

Operational Notes

passengers[].id is the passenger id from the selected offer, not an internal user identifier.
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. Public hold bookings require a tracked offer for the same profile, gdsprovider and offerId; without it the API returns Tracked flight offer is required to complete this public booking.
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"}]}'