> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gojinko.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Required traveler attributes

> What required_attributes on a trip item means and when a missing passport blocks checkout

A trip item can carry `required_attributes`: the traveler details that must be collected before the item can be booked, such as passport fields on a flight whose carrier requires travel documents.

## Where it appears

`required_attributes` is set once the trip is priced. It appears on the trip items returned by `get_trip`, `checkout` and the ancillaries response (`GET /v1/trip/{trip_id}/ancillaries`). The items returned by the `trip` action itself (`POST /v1/trip`) do not carry it, so read the trip again after a `trip` action.

## Shape

| Member | What it holds |
| - | - |
| `source` | Where the requirement comes from: `provider` or `derived`, described below. New values can appear; checkout enforces only `provider`. |
| `per_passenger` | Attribute names to collect for every passenger. |
| `booking` | Attribute names to collect once for the booking. |
| `per_passenger_conditional` | Attribute names that may be required for each passenger, depending on carrier, route or passenger details. Informational: collect them when in doubt. |
| `booking_conditional` | The booking-level counterpart of `per_passenger_conditional`. Informational. |

A list with no names is omitted.

## `source: "provider"`

The carrier states that these fields are needed to create the booking, and checkout enforces them. When `per_passenger` names a passport attribute or `Nationality` and a traveler lacks the matching field, checkout refuses with 422 `MISSING_CUSTOMER_DETAILS` before any payment object is issued: no `checkout_url` and no `agent_spt_params`. Nothing is charged.

The three passport attributes are satisfied together. If `per_passenger` names any of them, every traveler needs all three of `passport_number`, `passport_expiry` and `passport_country`, because the booking sends a passport only when it is complete.

## `source: "derived"`

The platform inferred the requirement from the itinerary. This happens on itineraries priced through a source that reports no document requirements, when the segments touch two or more countries. A low-cost-carrier source that reports nothing produces no `required_attributes` at all, not a `derived` one. Countries are compared by ISO country code, so a territory counts separately from its sovereign country, and a domestic route such as New York (JFK) to San Juan (SJU) produces this advisory. An airport the platform cannot place in a country never produces it on its own.

A `derived` requirement is advisory only. It is not a compliance statement, and checkout never enforces it.

## Attribute names and traveler fields

Checkout enforces these four names when a `provider` requirement lists them in `per_passenger`. Each is satisfied by a traveler field you send with `upsert_travelers`:

| Attribute | Traveler field | Format |
| - | - | - |
| `PassportNumber` | `passport_number` | Letters and digits only; a value with spaces or punctuation inside it counts as not collected. |
| `PassportExpiryDate` | `passport_expiry` | A date, `YYYY-MM-DD`. |
| `PassportCountryOfIssue` | `passport_country` | ISO 3166-1 alpha-2 country code, for example `FR`. |
| `Nationality` | `nationality` | ISO 3166-1 alpha-2 country code. |

Attribute names are an open set in the carrier's own vocabulary, so other names, such as `DateOfBirth` (satisfied by `date_of_birth`), can appear. Checkout does not refuse on them.

## What is left out

Five names are removed from `per_passenger` and `per_passenger_conditional` once every traveler on the trip satisfies them: `DateOfBirth`, the three passport names and `Nationality`. Other names stay listed whatever the travelers carry, and `booking` and `booking_conditional` are returned as stated. When the trip has no travelers, nothing is removed. When no names are left, the object is omitted.

An absent `required_attributes` means no outstanding requirement is known. It is not a statement that no travel document is needed.

## Examples

A flight whose carrier requires passports:

```json theme={null}
{
  "item_id": "itm_4b91c2",
  "kind": "flight",
  "required_attributes": {
    "source": "provider",
    "per_passenger": ["PassportNumber", "PassportExpiryDate", "PassportCountryOfIssue", "Nationality"]
  }
}
```

An international itinerary priced through a source that reports no document requirements:

```json theme={null}
{
  "item_id": "itm_7d20e5",
  "kind": "flight",
  "required_attributes": {
    "source": "derived",
    "per_passenger": ["PassportNumber", "PassportExpiryDate", "PassportCountryOfIssue", "Nationality"]
  }
}
```

## When checkout refuses

Checking out the first trip above before the travelers carry passport details returns:

```json theme={null}
{
  "error": {
    "code": "MISSING_CUSTOMER_DETAILS",
    "message": "the provider requires details this booking has not collected — flight: passport_number, passport_expiry, passport_country, nationality",
    "doc_url": "https://docs.gojinko.com/concepts/errors"
  },
  "missing_fields": ["nationality", "passport_country", "passport_expiry", "passport_number"],
  "missing_by_domain": {
    "flight": ["passport_number", "passport_expiry", "passport_country", "nationality"]
  }
}
```

`missing_fields` lists the traveler fields to collect, and `missing_by_domain` groups them by item kind. Send `upsert_travelers` with those fields for every traveler, then check out again. See [Errors & troubleshooting](/concepts/errors.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.