Required traveler attributes

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:

{
  "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:

{
  "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:

{
  "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.

Getting started

Guides

Marketing claim

Authentication

Connect

Developer Platform

Concepts

Required traveler attributes

Where it appears

Shape

`source: "provider"`

`source: "derived"`

Attribute names and traveler fields

What is left out

Examples

When checkout refuses

​Where it appears

​Shape

​source: "provider"

​source: "derived"

​Attribute names and traveler fields

​What is left out

​Examples

​When checkout refuses

Where it appears

Shape

`source: "provider"`

`source: "derived"`

Attribute names and traveler fields

What is left out

Examples

When checkout refuses