Dynamic Passenger Details
When creating bookings through the Distribusion API, different carriers may require different sets of passenger information. These requirements can include fields such as passenger name, date of birth, nationality, document details, and more, depending on the carrier’s operational and regulatory needs.
To ensure successful bookings, retailers have 2 options:
- Get required fields from the /marketing_carriers/{marketing_carrier_id}/booking/schema endpoint.
- Get required fields from /connections/vacancy and /reservations/create endpoints.
By integrating this schema into your application, you can dynamically adapt your booking forms and validation logic to enhance user experience, reduce booking errors, and ensure compliance with carrier requirements.
Using Booking Schema Endpoint
In case you prefer to cache the required fields for each carrier in advance, you can retrieve the data from the booking schema endpoint regularly (e.g. once a week).
/booking/schema Response
The /marketing_carriers/{marketing_carrier_id}/booking/schema endpoint response outlines which passenger fields are required or optional for the /reservations/create and /reservations/confirm request.
{
"data": {
"id": "IRYO",
"type": "booking_schema",
"attributes": {
"mandatory": [
"arrival_station",
"arrival_time",
"city",
"currency",
"departure_station",
"departure_time",
"email",
"execute_payment",
"first_name",
"last_name",
"locale",
"marketing_carrier",
"passengers",
"passengers[].birthdate",
"passengers[].government_id",
"passengers[].government_id_type",
"payment_method",
"retailer_partner_number",
"send_customer_email",
"street_and_number",
"terms_accepted",
"title",
"total_price",
"zip_code"
],
"optional": [
"discount_code",
"fare_class",
"flight_number",
"government_id",
"government_id_type",
"passengers[].nationality",
"passengers[].tax_id",
"payer_id",
"payment_token",
"phone"
]
},
"relationships": {
"required_attributes": {
"data": [
{
"id": "IRYO-reservations/confirm-default-e0092493-6b69-4ac7-bf6c-9320e9ee7bea",
"type": "required_attributes"
},
{
"id": "IRYO-reservations/create-default-4602cb0e-ba01-41ee-84b1-d7b0d90b987e",
"type": "required_attributes"
}
]
}
}
},
"jsonapi": {
"version": "1.0"
},
"included": [
{
"id": "IRYO-reservations/confirm-default-e0092493-6b69-4ac7-bf6c-9320e9ee7bea",
"type": "required_attributes",
"attributes": {
"mandatory": [
"city",
"email",
"first_name",
"last_name",
"street_and_number",
"title",
"zip_code",
"terms_accepted",
"passengers[].birthdate",
"passengers[].government_id",
"passengers[].government_id_type",
"passengers[].first_name",
"passengers[].last_name"
],
"endpoint": "reservations/confirm",
"context": "default",
"description": "Required data for all requests"
},
"relationships": {
"allowed_values": {
"data": [
{
"id": "IRYO-reservations/confirm-default-passengers[].government_id_type-fa118a3d-905a-4a5b-8123-185a2752c0f0",
"type": "allowed_values"
}
]
}
}
},
{
"id": "IRYO-reservations/create-default-4602cb0e-ba01-41ee-84b1-d7b0d90b987e",
"type": "required_attributes",
"attributes": {
"mandatory": [],
"endpoint": "reservations/create",
"context": "default",
"description": "Required data for all requests"
},
"relationships": {
"allowed_values": {
"data": []
}
}
},
{
"id": "IRYO-reservations/confirm-default-passengers[].government_id_type-fa118a3d-905a-4a5b-8123-185a2752c0f0",
"type": "allowed_values",
"attributes": {
"attribute": "passengers[].government_id_type",
"allowed": [
"birth_certificate",
"drivers_license",
"entry_visa",
"marine_id",
"military_supplement",
"national_id",
"naturalisation_certificate",
"passport_id",
"permanent_resident_id",
"refugee_id",
"resident_id",
"tax_number",
"tsa_precheck_id",
"us_i872_card",
"us_tribal_card",
"international_passport"
]
}
}
]
}
The upper part of the response shows the fields that are required when using the booking flow, and the lower part shows the fields required for the reservations flow, including the breakdown for the /reservations/create and /reservations/confirm requests.
Understanding the Response
In the case of this sample carrier, we have the following scenario:
/reservations/create
- No fields are required
/reservations/confirm
Top-level:
- city
- email
- first_name
- last_name
- street_and_number
- title
- zip_code
- terms_accepted
Nested in passengers[]:
- birthdate
- government_id
- government_id_type
- first_name
- last_name
ID Types Allowed
When government_id is a required field for a carrier, the response from any of the endpoints listed above also includes additional information on what types of ID are allowed for the government_id_type field. For instance, in the case of this sample carrier the following fields are allowed:
- birth_certificate
- drivers_license
- entry_visa
- marine_id
- military_supplement
- national_id
- naturalisation_certificate
- passport_id
- permanent_resident_id
- refugee_id
- resident_id
- tax_number
- tsa_precheck_id
- us_i872_card
- us_tribal_card
- international_passport
Using /connections/vacancy and /reservations/create Endpoints
In case you prefer to get the list of fields required dynamically as part of the flow, you can retrieve the data from the response from the /connections/vacancy and /reservations/create endpoints.
/connections/vacancy Response
The response from the /connections/vacancy endpoint outlines which passenger fields are required or optional for the /reservations/create and /reservations/confirm request.
/reservations/create Response
The response from the /reservations/create endpoint outlines which passenger fields are required or optional for the /reservations/confirm request.
Understanding the Response
In the case of this sample carrier, we have the following scenario:
/reservations/create
- No fields are required
/reservations/confirm
Top-level:
- city
- email
- first_name
- last_name
- street_and_number
- title
- zip_code
- terms_accepted
Nested in passengers[]:
- birthdate
- government_id
- government_id_type
- first_name
- last_name
What made this section helpful for you?
What made this section unhelpful for you?
On this page
- Dynamic Passenger Details