POST/v1/flights/order/required-fields/:gdsprovider/:offerId

Get required flight booking fields

Returns the dynamic passenger, document and identity fields required to complete booking for a selected flight offer.

POST/v1/flights/order/required-fields/: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

{
  "offerId": "off_0000B7VCW4q5OD5G49hmKn",
  "passengers": [
    {
      "type": "adult"
    }
  ]
}

cURL request

cURL

bash

curl -X POST 'https://api.sandbox.travelandz.com/v1/flights/order/required-fields/0/:offerId' \
  -H 'Authorization: Bearer YOUR_SECRET_KEY' \
  -H 'X-Travelandz-Id: YOUR_PUBLIC_KEY:YOUR_PROFILE_CODE' \
  -H 'Content-Type: application/json' \
  -d '{"offerId":"off_0000B7VCW4q5OD5G49hmKn","passengers":[{"type":"adult"}]}'

Add your credentials to send a request.

Response

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

Returns the dynamic passenger, document and identity fields required to complete booking for a selected flight offer.

Endpoint

Method	Path	Auth
`POST`	`/v1/flights/order/required-fields/: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

Accepted values: 0, 1

offerId

stringYes

Request Body Schema

offerId

stringYes

Selected offer id

passengers

arrayYes

passengers[]type

enum

adultchildinfant_without_seat

Yes

Success Response

Returns required field definitions for the offer.

Response Body Schema

holder

objectYes

holderphone

booleanYes

When true, provide passengers[0].phone_number in E.164 format for flows that consume holder contact data

holderemail

booleanYes

When true, provide passengers[0].email for flows that consume a holder email

holdercountryCode

booleanYes

No separate field exists in create-order. For gdsprovider=1 flows this is derived from passengers[0].phone_number in E.164 format

passengers

arrayYes

passengers[]idx

numberYes

Passenger index from the required-fields response

passengers[]title

booleanYes

Maps to passengers[].title

passengers[]type

booleanYes

Maps to passengers[].type

passengers[]name

booleanYes

Maps to passengers[].firstName

passengers[]lastName

booleanYes

Maps to passengers[].lastName

passengers[]age

booleanYes

Informational only. No direct field exists in create-order and this is currently false in public flight flows

passengers[]nationality

booleanYes

When true, maps to passengers[].country

passengers[]gender

booleanYes

Maps to passengers[].gender

passengers[]phone

booleanYes

When true, maps to passengers[].phone_number

passengers[]email

booleanYes

When true, maps to passengers[].email. Some gdsprovider=1 flows only consume the first passenger email

passengers[]address

booleanYes

Informational only. No direct field exists in create-order and this is currently false in public flight flows

passengers[]city

booleanYes

Informational only. No direct field exists in create-order and this is currently false in public flight flows

passengers[]postalCode

booleanYes

Informational only. No direct field exists in create-order and this is currently false in public flight flows

passengers[]bornDate

booleanYes

When true, maps to passengers[].bornDate

passengers[]documentIdentifier

booleanYes

When true, maps to passengers[].identity_documents[].unique_identifier

passengers[]documentType

booleanYes

When true, maps to passengers[].identity_documents[].type when a document object is used

passengers[]documentIssuedAt

booleanYes

Informational only. No direct field exists in create-order and this is currently false in public flight flows

passengers[]documentExpiresAt

booleanYes

When true, maps to passengers[].identity_documents[].expires_on

passengers[]documentCountryCode

booleanYes

When true, maps to passengers[].identity_documents[].issuing_country_code

passengers[]allowedDocuments

arrayNullable

Allowed values for the booking document flow: passport, tax_id, known_traveler_number, passenger_redress_number, dni. If dni is allowed, also collect passengers[].NationalID because the current response does not expose a dedicated nationalId flag

liveMode

booleanYes

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

Operational Notes

Prefer this POST endpoint because it accepts passenger context in the request body.
GET /v1/flights/order/required-fields/:gdsprovider/:offerId exists for compatibility, but integrations should use POST.
The real response contract is holder plus passengers[]; it is not a requiredFields[] wrapper.
Use the response to decide whether identity_documents, NationalID, nationality or document expiration must be collected before booking.
allowedDocuments limits valid values for passengers[].identity_documents[].type. If it includes dni, also collect passengers[].NationalID even though the current response does not expose a dedicated nationalId boolean.
In gdsprovider=1 flows, holder.countryCode does not correspond to a separate booking field. It is satisfied by passengers[0].phone_number in E.164 format.
In gdsprovider=1 flows, passengers[].email can be marked as required even though only the first passenger email may be consumed as the holder email.

Example

bash

curl -X POST https://api.sandbox.travelandz.com/v1/flights/order/required-fields/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 '{"offerId":"offer_123","passengers":[{"type":"adult"}]}'

Request Body - Example Value

json

{
  "offerId": "off_0000B7VCW4q5OD5G49hmKn",
  "passengers": [
    {
      "type": "adult"
    }
  ]
}

Responses

Code	Description
`200`	Required booking fields resolved 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

{
  "holder": {
    "phone": false,
    "email": false,
    "countryCode": false
  },
  "passengers": [
    {
      "idx": 0,
      "title": true,
      "type": true,
      "name": true,
      "lastName": true,
      "age": false,
      "nationality": false,
      "gender": true,
      "phone": true,
      "email": true,
      "address": false,
      "city": false,
      "postalCode": false,
      "bornDate": true,
      "documentIdentifier": false,
      "documentType": false,
      "documentIssuedAt": false,
      "documentExpiresAt": false,
      "documentCountryCode": false,
      "allowedDocuments": null
    }
  ],
  "liveMode": false
}