API

Passenger Types

Distribusion also makes it easier to integrate a large variety of carriers by harmonizing all available passenger types into standardized codes.

Codes

Carriers will support at least one of these 5 codes:

PINT: Infant
PCIL: Child
PYPO: Youth
PNOS: Adult
PSOE: Senior

Some carriers even support other passenger codes such as PSAD, PAOV, PCUU or PCUN, each with their own definition of age ranges.

Age Range

The availability and age range of each passenger type is dependent upon the respective marketing carrier’s policies. This information can be found in the /marketing_carriers/{marketing_carrier_id} endpoint. The response displays the available passenger types for the respective carrier and details the age brackets associated with each available passenger type.

We recommend that you cache this information regularly (once a week for example) and use it for the ages of passengers to the passenger types supported by the carrier.

JSON

    {
        "id": "PNOS",
        "type": "passenger_types",
        "attributes": {
            "code": "PNOS",
            "name": "Adult",
            "description": "",
            "min_age": 30,
            "max_age": 64
        }
    },
    {
        "id": "PCIL",
        "type": "passenger_types",
        "attributes": {
            "code": "PCIL",
            "name": "Child",
            "description": "",
            "min_age": 0,
            "max_age": 13
        }
    },
    {
        "id": "PYPO",
        "type": "passenger_types",
        "attributes": {
            "code": "PYPO",
            "name": "Youth",
            "description": "",
            "min_age": 14,
            "max_age": 29
        }
    },
    {
        "id": "PSOE",
        "type": "passenger_types",
        "attributes": {
            "code": "PSOE",
            "name": "Senior",
            "description": "",
            "min_age": 65,
            "max_age": 99
        }
    }

Infant Seats

Carriers handles infant tickets in two forms.

Free Infant Without Seat

Some carriers don't require a ticket at all for infants as long as they don't need a seat. In this scenario there is no passenger type and there is a gap in ages you get from /marketing_carriers/{marketing_carrier_id} endpoint.

For example PCIL (4-16) and PNOS (17-99). This indicates that infants (0-3) travel free and don't need to be booked, but also do not get a seat. In this case, if the pax wants a seat a ticket has to be booked as PCIL or PNOS.

Free/Paid Infant With Seats

Some carriers have the passenger type PINT (Infant) with 100% discount or some discount. In this case, the pax gets a seat.

Passenger Restrictions

Some passenger types, like children and infants, are not allowed to travel alone and must be accompanied by an adult. These requirements are defined by carriers using passenger_group_rule_parameters, which can be retrieved from the /marketing_carriers/{marketing_carrier_id} endpoint.

In the example below, the carrier lists these requirements:

Group Size Limit: You can book for up to 9 people at once.
Adults Required: If your group includes children (PCIL) or infants (PINT), there must be at least one adult (PNOS) traveling with them. Kids and infants can’t travel alone.
Infant Rule: For every infant (PINT) in the group, there must be at least one adult (PNOS). So, 2 infants need at least 2 adults, and so on.

Plain text

   {        "id": "IRYO-FARE-1-PASSENGER_GROUP_RULE-0",        "type": "passenger_group_rules",        "attributes": {            "rule_type": "max_passengers",            "description": "max passengers"        },        "relationships": {            "parameters": {                "data": [                    {                        "id": "IRYO-FARE-1-PASSENGER_GROUP_RULE-0-PARAMETER-0",                        "type": "passenger_group_rule_parameters"                    }                ]            }        }    },    {        "id": "IRYO-FARE-1-PASSENGER_GROUP_RULE-1",        "type": "passenger_group_rules",        "attributes": {            "rule_type": "passengers_type_requires_passengers_types",            "description": "Adult required"        },        "relationships": {            "parameters": {                "data": [                    {                        "id": "IRYO-FARE-1-PASSENGER_GROUP_RULE-1-PARAMETER-0",                        "type": "passenger_group_rule_parameters"                    },                    {                        "id": "IRYO-FARE-1-PASSENGER_GROUP_RULE-1-PARAMETER-1",                        "type": "passenger_group_rule_parameters"                    }                ]            }        }    },    {        "id": "IRYO-FARE-1-PASSENGER_GROUP_RULE-2",        "type": "passenger_group_rules",        "attributes": {            "rule_type": "passengers_type_ratio",            "description": "1 infant per adult"        },        "relationships": {            "parameters": {                "data": [                    {                        "id": "IRYO-FARE-1-PASSENGER_GROUP_RULE-2-PARAMETER-0",                        "type": "passenger_group_rule_parameters"                    },                    {                        "id": "IRYO-FARE-1-PASSENGER_GROUP_RULE-2-PARAMETER-1",                        "type": "passenger_group_rule_parameters"                    },                    {                        "id": "IRYO-FARE-1-PASSENGER_GROUP_RULE-2-PARAMETER-2",                        "type": "passenger_group_rule_parameters"                    }                ]            }        }    },    {        "id": "IRYO-FARE-1-PASSENGER_GROUP_RULE-0-PARAMETER-0",        "type": "passenger_group_rule_parameters",        "attributes": {            "name": "passengers_limit",            "value": 9        }    },    {        "id": "IRYO-FARE-1-PASSENGER_GROUP_RULE-1-PARAMETER-0",        "type": "passenger_group_rule_parameters",        "attributes": {            "name": "dependent_passengers_types",            "value": [                "PINT",                "PCIL"            ]        }    },    {        "id": "IRYO-FARE-1-PASSENGER_GROUP_RULE-1-PARAMETER-1",        "type": "passenger_group_rule_parameters",        "attributes": {            "name": "required_passengers_types",            "value": [                "PNOS"            ]        }    },    {        "id": "IRYO-FARE-1-PASSENGER_GROUP_RULE-2-PARAMETER-0",        "type": "passenger_group_rule_parameters",        "attributes": {            "name": "ratio_from_types",            "value": [                "PINT"            ]        }    },    {        "id": "IRYO-FARE-1-PASSENGER_GROUP_RULE-2-PARAMETER-1",        "type": "passenger_group_rule_parameters",        "attributes": {            "name": "ratio_to_types",            "value": [                "PNOS"            ]        }    },    {        "id": "IRYO-FARE-1-PASSENGER_GROUP_RULE-2-PARAMETER-2",        "type": "passenger_group_rule_parameters",        "attributes": {            "name": "ratio",            "value": 1        }    }   {        "id": "IRYO-FARE-1-PASSENGER_GROUP_RULE-0",        "type": "passenger_group_rules",        "attributes": {            "rule_type": "max_passengers",            "description": "max passengers"        },        "relationships": {            "parameters": {                "data": [                    {                        "id": "IRYO-FARE-1-PASSENGER_GROUP_RULE-0-PARAMETER-0",                        "type": "passenger_group_rule_parameters"                    }                ]            }        }    },    {        "id": "IRYO-FARE-1-PASSENGER_GROUP_RULE-1",        "type": "passenger_group_rules",        "attributes": {            "rule_type": "passengers_type_requires_passengers_types",            "description": "Adult required"        },        "relationships": {            "parameters": {                "data": [                    {                        "id": "IRYO-FARE-1-PASSENGER_GROUP_RULE-1-PARAMETER-0",                        "type": "passenger_group_rule_parameters"                    },                    {                        "id": "IRYO-FARE-1-PASSENGER_GROUP_RULE-1-PARAMETER-1",                        "type": "passenger_group_rule_parameters"                    }                ]            }        }    },    {        "id": "IRYO-FARE-1-PASSENGER_GROUP_RULE-2",        "type": "passenger_group_rules",        "attributes": {            "rule_type": "passengers_type_ratio",            "description": "1 infant per adult"        },        "relationships": {            "parameters": {                "data": [                    {                        "id": "IRYO-FARE-1-PASSENGER_GROUP_RULE-2-PARAMETER-0",                        "type": "passenger_group_rule_parameters"                    },                    {                        "id": "IRYO-FARE-1-PASSENGER_GROUP_RULE-2-PARAMETER-1",                        "type": "passenger_group_rule_parameters"                    },                    {                        "id": "IRYO-FARE-1-PASSENGER_GROUP_RULE-2-PARAMETER-2",                        "type": "passenger_group_rule_parameters"                    }                ]            }        }    },    {        "id": "IRYO-FARE-1-PASSENGER_GROUP_RULE-0-PARAMETER-0",        "type": "passenger_group_rule_parameters",        "attributes": {            "name": "passengers_limit",            "value": 9        }    },    {        "id": "IRYO-FARE-1-PASSENGER_GROUP_RULE-1-PARAMETER-0",        "type": "passenger_group_rule_parameters",        "attributes": {            "name": "dependent_passengers_types",            "value": [                "PINT",                "PCIL"            ]        }    },    {        "id": "IRYO-FARE-1-PASSENGER_GROUP_RULE-1-PARAMETER-1",        "type": "passenger_group_rule_parameters",        "attributes": {            "name": "required_passengers_types",            "value": [                "PNOS"            ]        }    },    {        "id": "IRYO-FARE-1-PASSENGER_GROUP_RULE-2-PARAMETER-0",        "type": "passenger_group_rule_parameters",        "attributes": {            "name": "ratio_from_types",            "value": [                "PINT"            ]        }    },    {        "id": "IRYO-FARE-1-PASSENGER_GROUP_RULE-2-PARAMETER-1",        "type": "passenger_group_rule_parameters",        "attributes": {            "name": "ratio_to_types",            "value": [                "PNOS"            ]        }    },    {        "id": "IRYO-FARE-1-PASSENGER_GROUP_RULE-2-PARAMETER-2",        "type": "passenger_group_rule_parameters",        "attributes": {            "name": "ratio",            "value": 1        }    }

Passenger IDs

Every passenger defined in your initial search request is assigned a unique, internal identifier by the API (e.g., pax-25-1, representing the first passenger of age 25). This ID acts as the persistent link between your search criteria and the resulting commercial offers.

Mapping Fares to Travelers

In the API response, the passenger_ids array within an Offer object explicitly defines who that specific fare covers.

Individual Coverage: If the array contains a single ID, that fare applies only to that specific passenger.
Group Coverage: If the array lists multiple IDs (e.g., ["pax-25-1", "pax-11-2"]), the price and conditions apply to those passengers collectively as a group.

Requirement for Booking Flow

These IDs are not merely for display; they are required functional parameters. When proceeding to validation with /reservations/create you must echo these exact IDs back to the API. For a few use cases this is also needed in /connections/vacancy. This ensures the system correctly maps the selected fare to the specific passenger profile (age, loyalty cards) used to generate the price.

API Workflow

1. Let's assume the pax group consists of one person aged 40, two people aged 16, and one person aged 10.

2. Perform the /connections/find request specifying the exact (or max) age of each passenger.

JSON

"passengers": [
        {
            "pax": 1,
            "max_age": 40
        },
        {
            "pax": 2,
            "max_age": 16
        },
        {
            "pax": 1,
            "max_age": 10
        }
    ]

3. Map the ages of passengers to the passenger types supported by the carrier selected by the user. This can be done using the /marketing_carriers/{marketing_carrier_id} endpoint as explained in the ‘Age Range’ section above.

4. For Italo for example, passenger types are PCIL (0–13), PYPO (14–29), PNOS (30–64), and PSOE (65–99). Given 1 pax (40 y/o), 2 pax (16 y/o), and 1 pax (10 y/o), the breakdown is: 1 PCIL, 2 PYPO, 1 PNOS.

5. Perform the /connections/vacancy request using the passenger type codes and unique IDs retrieved from the find response:

JSON

"passengers": [
        {
            "id": "pax-40-1",
            "type": "PNOS",
            "pax": 1
        },
        {
            "id": "pax-16-2",
            "type": "PYPO",
            "pax": 1
        },
        {
            "id": "pax-16-3",
            "type": "PYPO",
            "pax": 1
        },
        {
            "id": "pax-10-4",
            "type": "PCIL",
            "pax": 1
        }
    ]

(Note: Each passenger is now uniquely identified by an id generated in the search step to allow for individual fare and card assignments.)

6. In the /reservations/create request include the passenger details as in the example below. The /reservations/confirm request should be structured in a similar way.

JSON

{
    "offers": [
        {
            "id": "6e79cca8-952c-4639-8a67-b8b68c534212|0"
        }
    ]
    "locale": "en",
    "passengers": [
        {
            "type": "PNOS",
            "id": "pax-40-1"
        },
        {
            "type": "PYPO",
            "id": "pax-16-2"
        },
        {
            "type": "PYPO",
            "id": "pax-16-3"
        },
        {
            "type": "PCIL",
            "id": "pax-10-4"
        }
    ]
}

Sections

Passenger Types

Codes

Age Range

Infant Seats

Free Infant Without Seat

Free/Paid Infant With Seats

Passenger Restrictions

Passenger IDs

Mapping Fares to Travelers

Requirement for Booking Flow

API Workflow

On this page