API docs by Redocly

Connect API for Transports (1.14.0)

Download OpenAPI specification:

ConnectAPI is a family of APIs that standardize integration between provider and user of the services. It is designed to be RESTful, using standard HTTP methods like GET, POST, and DELETE, and it primarily exchanges data in JSON format. ConnectAPI for transport focuses specifically on the transport services, including primarily flights, but also trains and buses.

The API definition below is designed to handle the whole lifecycle of the transport booking process, from searching for available transports to booking and cancelling them. The key functionalities of the Connect API for transport are:

  1. Searching for Transports: This endpoint lists all available transports based on the input criteria. Each transport comes with basic information like departure and arrival dates and times, prices, carrier name, etc.

  2. Retrieving Transport details: This endpoint provides a detailed description of a specific transport. It requires the ID of the transport offer as input.

  3. Checking Transport Availability: This endpoint extends the functionality above. In addition to providing transport details, it also verifies the the current status of the transport's availability. This call returns a quote ID. The quote ID is used to book the transport.

  4. Booking a Transport: This endpoint enables booking a specific transport. It requires the ID of the transport quote and customer details for a successful booking. This call returns a booking ID.

  5. Canceling a Transport booking: This endpoint cancels a specific Transport booking. It requires the booking ID to perform the cancellation.

Change History

API Version Docs Version Changes
1.0 01.07.2024 Initial version
1.1 22.01.2026 Added streamed offers endpoint, baggage offers, transport distance, fare types, price breakdown, price per pax, passenger required fields, branded fares, seats, and ticketing limit fields
1.2 16.03.2026 Added AncillaryOffer, Amenity and SeatOffer schemas. Added ancillaryOffers, includedAmenities and seatOffers to TransportConnectionOfferSegment. Extended TransportBookRequest with optional ancillaries and seats selection fields
1.3 25.03.2026 Added AncillarySelection and SeatSelection schemas. Restructured TransportBookRequest selections into nested connections[].segments[] with per-segment ancillarySelections and seatSelections
1.4 13.04.2026 Added optional frequentFlyerInfo to CommonPax for frequent flyer number pass-through on booking requests
1.5 20.04.2026 Made Contract-Id optional, added Login and Password headers as alternative identification method
1.6 03.06.2026 Added required type field (AncillaryType enum: MEAL, SPEEDY_BOARDING, PRIORITY, LOUNGE_ACCESS, CHECKIN, OTHER) to AncillaryOffer
1.7 11.06.2026 Added optional requiredPassengerData and requiredContactData to TransportConnectionOffer using the shared Connect API objects; deprecated passengerRequiredFields
1.8 17.06.2026 Added BAGGAGE to the AncillaryType enum
1.9 03.07.2026 Made bookingClassCode optional in TransportConnectionOfferSegment
1.10 14.07.2026 Added optional maxPriceVariationPercentage to TransportBookRequest
1.11 16.07.2026 Added optional language to TransportOffersRequest
1.12 29.07.2026 Added optional paymentMethod to TransportBookRequest; accepted values are agreed per integration
1.13 04.08.2026 Added optional contact to TransportBookRequest, aligning it with the other Connect APIs
1.14 04.08.2026 Added the FareOffer schema and optional fareOffers to TransportOffer (branded fare tiers, availability check only), and optional selectedFareId to TransportAvailabilityRequest and TransportBookRequest. Removed the undefined fareFamily from TransportConnectionOfferSegment.required

Authentication

All API requests must be made over HTTPS.

Identification can be provided via either:

  • A Contract-Id header identifying the contract configuration
  • Login and Password headers for login-based authentication

The identification method should be agreed with Nezasa before integration development starts. Both methods may be provided simultaneously if required by the integration.

Heartbeat

Healthcheck endpoint

This endpoint, often known as a "health check" endpoint, is used for monitoring and assessing the status of the service. Its main function is to signal the health of the service, aiding in identifying any potential issues or service breakdowns.

TripBuilder will periodically call this endpoint to check the service's status. The response from this health check endpoint is used to assess the current condition of the service. If the service is operating correctly, the endpoint will return a positive acknowledgment, i.e. a HTTP 200 status code and a message indicating the service's health.

On the other hand, if the service is not functioning as expected, the endpoint will return an error status code and potentially additional data about the issue's nature.

This proactive health check allows for prompt detection and resolution of issues, ensuring the service's reliability and smooth functioning.

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "details": [
    ],
  • "message": "message"
}

Search

Get a list of transport offers

Obtain a list of transport offers (flights, trains, buses, ferries, etc.) for a set of connections. The connections are defined by a departure and arrival location and periods and can be further filtered by a set of filters. It can be configured by Nezasa whether synchronous (this) or streaming endpoint will be used to search for transport offers.

Authorizations:
ApiKeyAuth
header Parameters
Contract-Id
string
Example: nicetours, 123456

An identifier of the contract to differentiate configuration, options or settings. This is one of two supported identification methods. Either provide a Contract-Id header, or provide Login and Password headers. Both may be provided simultaneously if required by the integration. The identification method should be agreed with Nezasa before development starts.

Login
string

Login identifier for supplier authentication. An alternative to the Contract-Id header. When using login-based authentication, both Login and Password headers should be provided. The identification method should be agreed with Nezasa before development starts.

Password
string <password>

Password for supplier authentication. Used together with the Login header as an alternative to the Contract-Id header. The identification method should be agreed with Nezasa before development starts.

Request Body schema: application/json
required
Array of objects (RequestTransportConnection)

A list of transport connections.

Array of objects (PaxAge)

The ages of the passengers.

object (Filters)
language
string (Supported languages)
Default: "en"
Enum: "de" "en" "fr" "it" "nl" "es" "fi" "pt" "sv" "no" "da" "pl"

2-letter code (ISO 639-1)

object (Metadata)

Responses

Request samples

Content type
application/json
{
  • "paxAges": [
    ],
  • "metadata": {
    },
  • "language": "en",
  • "filters": {
    },
  • "connections": [
    ]
}

Response samples

Content type
application/json
{
  • "offers": [
    ],
  • "rawRequests": [
    ],
  • "rawResponses": [
    ]
}

Stream transport offers

Obtain a stream of transport offers (flights, trains, buses, ferries, etc.) for a set of connections. The connections are defined by a departure and arrival location and periods and can be further filtered by a set of filters. The response is streamed as server-sent events with partial results. It can be configured by Nezasa whether synchronous or streaming (this) endpoint will be used to search for transport offers.

Authorizations:
ApiKeyAuth
header Parameters
Contract-Id
string
Example: nicetours, 123456

An identifier of the contract to differentiate configuration, options or settings. This is one of two supported identification methods. Either provide a Contract-Id header, or provide Login and Password headers. Both may be provided simultaneously if required by the integration. The identification method should be agreed with Nezasa before development starts.

Login
string

Login identifier for supplier authentication. An alternative to the Contract-Id header. When using login-based authentication, both Login and Password headers should be provided. The identification method should be agreed with Nezasa before development starts.

Password
string <password>

Password for supplier authentication. Used together with the Login header as an alternative to the Contract-Id header. The identification method should be agreed with Nezasa before development starts.

Request Body schema: application/json
required
Array of objects (RequestTransportConnection)

A list of transport connections.

Array of objects (PaxAge)

The ages of the passengers.

object (Filters)
language
string (Supported languages)
Default: "en"
Enum: "de" "en" "fr" "it" "nl" "es" "fi" "pt" "sv" "no" "da" "pl"

2-letter code (ISO 639-1)

object (Metadata)

Responses

Request samples

Content type
application/json
{
  • "paxAges": [
    ],
  • "metadata": {
    },
  • "language": "en",
  • "filters": {
    },
  • "connections": [
    ]
}

Response samples

Content type
application/problem+json
{
  • "message": "Customer phone number must start with a country code prefix, e.g +41.",
  • "code": "invalid_argument",
  • "rawRequests": [
    ],
  • "rawResponses": [
    ]
}

Fetches fare rules

Fetches a breakdown of price components for the given offer. Returns text.

Authorizations:
ApiKeyAuth
header Parameters
Contract-Id
string
Example: nicetours, 123456

An identifier of the contract to differentiate configuration, options or settings. This is one of two supported identification methods. Either provide a Contract-Id header, or provide Login and Password headers. Both may be provided simultaneously if required by the integration. The identification method should be agreed with Nezasa before development starts.

Login
string

Login identifier for supplier authentication. An alternative to the Contract-Id header. When using login-based authentication, both Login and Password headers should be provided. The identification method should be agreed with Nezasa before development starts.

Password
string <password>

Password for supplier authentication. Used together with the Login header as an alternative to the Contract-Id header. The identification method should be agreed with Nezasa before development starts.

Request Body schema: application/json
required
quoteId
string

The offerId of the quote returned from the availability check which rules to retrieve.

object (Metadata)

Responses

Request samples

Content type
application/json
{
  • "metadata": {
    },
  • "quoteId": "quoteId"
}

Response samples

Content type
application/json
{
  • "rawRequests": [
    ],
  • "text": "text",
  • "rawResponses": [
    ]
}

Book

Confirm or re-quote a transport offer

Confirm or re-quote one of the received offers. The offer can change due to the fact that original offer search may have employed caches. It is a necessary step before booking.

Authorizations:
ApiKeyAuth
header Parameters
Contract-Id
string
Example: nicetours, 123456

An identifier of the contract to differentiate configuration, options or settings. This is one of two supported identification methods. Either provide a Contract-Id header, or provide Login and Password headers. Both may be provided simultaneously if required by the integration. The identification method should be agreed with Nezasa before development starts.

Login
string

Login identifier for supplier authentication. An alternative to the Contract-Id header. When using login-based authentication, both Login and Password headers should be provided. The identification method should be agreed with Nezasa before development starts.

Password
string <password>

Password for supplier authentication. Used together with the Login header as an alternative to the Contract-Id header. The identification method should be agreed with Nezasa before development starts.

Request Body schema: application/json
required
offerId
string

The offerId identifying the offer from the search results.

Array of objects (PaxAge)

The ages of the passengers.

selectedFareId
string (Branded fare tier to quote)

The id of the FareOffer to price, taken from the fareOffers of an earlier availability response for this same offer. When omitted, the offer is quoted at its default fare, exactly as it was before branded fares existed.

Authority

offerId is authoritative for which offer is quoted. selectedFareId is authoritative only for which fare tier of that offer is priced. It never redirects the request to a different itinerary, not even when the integration partner encodes its own offer reference inside the token: the offer identity always comes from offerId.

Expected behaviour

  • Recognised and valid for this offerId → return the offer priced at that tier. The returned salesPrice is the tier's price, and the returned quote must book that tier.
  • Unknown, malformed, or minted for a different offer than offerId → reject the availability check with an error.
  • Recognised, but the tier is no longer available or no longer purchasable → reject the availability check with an error.

Warning: Never fall back to the default fare. A base-priced quote returned in response to a selectedFareId that could not be honoured is indistinguishable from success to the caller, and would silently sell a different fare than the one the traveller chose. An error lets TripBuilder ask the agent to select again.

object (Metadata)

Responses

Request samples

Content type
application/json
{
  • "paxAges": [
    ],
  • "metadata": {
    },
  • "offerId": "offerId",
  • "selectedFareId": "F:INCLUSIVE_PLUS"
}

Response samples

Content type
application/json
{
  • "quote": {
    },
  • "persistedStorage": "persistedStorage",
  • "rawRequests": [
    ],
  • "rawResponses": [
    ]
}

Book a transport offer

Book one of the received offers.

Authorizations:
ApiKeyAuth
header Parameters
Contract-Id
string
Example: nicetours, 123456

An identifier of the contract to differentiate configuration, options or settings. This is one of two supported identification methods. Either provide a Contract-Id header, or provide Login and Password headers. Both may be provided simultaneously if required by the integration. The identification method should be agreed with Nezasa before development starts.

Login
string

Login identifier for supplier authentication. An alternative to the Contract-Id header. When using login-based authentication, both Login and Password headers should be provided. The identification method should be agreed with Nezasa before development starts.

Password
string <password>

Password for supplier authentication. Used together with the Login header as an alternative to the Contract-Id header. The identification method should be agreed with Nezasa before development starts.

Request Body schema: application/json
required
quoteId
string

The offerId of the quote returned from the availability check to be booked.

Array of objects (Basic representation of a pax)

A list of passenger information.

object (BillingInformation)
object (BookOptions)
persistedStorage
string

This field, sourced from the TransportAvailabilityResponse, serves as a repository for any pertinent data that need to pass across subsequent interactions. It remains unaltered by TripBuilder and is solely stored and returned in its original form.

selectedFareId
string (Branded fare tier being booked)

The id of the FareOffer that was selected. It applies to the whole offer, unlike the per-segment ancillary and seat selections. Set it to the value that was passed as TransportAvailabilityRequest.selectedFareId when the quote being booked was produced, and omit it when no tier was selected.

Authority

quoteId is authoritative. The quote returned by the availability check already carries the tier it was priced at, so this field selects nothing — it states which tier TripBuilder believes it is buying, so that the two sides can be compared before the booking is committed.

Expected behaviour

  • Matches the tier the quote was priced at → book the quote.
  • Disagrees with it → reject the booking. Do not re-price and do not switch tier: the quote's price and inclusions are what the traveller agreed to, so a mismatch means the two sides disagree about what is being sold.
  • Omitted → book the quote as it stands, whichever tier it holds.
Array of objects (TransportBookRequest_connections_inner)

Optional list of connections with per-segment ancillary and seat selections. The connectionId and segmentId reference the connection and segment from the offer returned in the Availability Check.

maxPriceVariationPercentage
integer <int32> (Maximum tolerated price variation (percentage delta)) [ 0 .. 100 ]

Caller-defined tolerance for a price change between the quote that was previously returned by the availability check (TransportAvailabilityRequest) and the final price returned by the supplier at booking time.

Expected behaviour

The delta is meant to be applied upward only (asymmetric): price decreases are never a reason to reject a booking.

Preferred (asymmetric) — applied whenever the upward-only comparison can be made, either by the supplier or by the integration partner:

  • When the supplier API exposes a price-tolerance parameter that distinguishes increases from decreases, the delta MUST be forwarded so that it applies upward only.
  • When the supplier API does not expose such a parameter, but the booking flow exposes the final price before the booking is committed, the integration partner MUST perform this final price validation itself and cut off the booking if the price increase exceeds the delta.

In both cases:

  • Final price higher than the quoted price by more than this delta → reject the booking.
  • Final price higher by less than or equal to this delta → accept the booking and return the new price in the response.
  • Final price lower than the quoted price → always accept, regardless of magnitude, and return the new price in the response. Decreases are never a reason to reject.

Fallback (symmetric) — ONLY when the upward-only behaviour above cannot be implemented (the supplier API exposes a single tolerance parameter that it applies to deviations in either direction, and the booking flow does not allow the integration partner to validate the final price before the booking is executed) MAY the same delta be forwarded as-is, and it is therefore applied both upward and downward around the quoted price. Increases and decreases that exceed the delta both cause the supplier to reject the booking.

Unsupported — ONLY when the supplier API exposes no price-tolerance mechanism and the booking flow does not allow the integration partner to validate the final price before the booking is executed may the field be ignored, in which case the integration partner's existing default behaviour applies (typically: reject any price change). In this case the tolerance is not enforced end-to-end, so callers should not assume the supplied delta has any effect for that supplier.

Example

With a delta of 25 and a previously quoted price of 100:

  • Asymmetric mode: any final price up to and including 125 is accepted (delta applied upward); 125.01 or above is rejected; any price below 100 is accepted.
  • Symmetric mode (fallback): final prices in the range [75, 125] are accepted (delta applied both ways); anything outside that range is rejected by the supplier.

Omitted / zero

When the field is omitted, the integration partner SHOULD apply its existing default behaviour (typically: reject any price change). A delta of 0 explicitly forbids any variation.

paymentMethod
string (Payment method to be used towards the supplier)

Selects the payment method to be used to pay the supplier for this booking.

This is a free-form string and deliberately not an enumeration: the supported payment methods differ from integration to integration, and within a single integration different customers may be entitled to different methods. The accepted values are therefore agreed bilaterally per integration and are not part of this specification.

Expected behaviour

  • A recognised value must be honoured. If the requested method is a valid value for the integration but cannot be applied to this particular booking (not supported by the supplier for the selected offer, or not enabled for the caller), the booking must be rejected.
  • An unrecognised value must lead to the booking being rejected.
  • When the field is omitted, the payment method configured by default for the caller applies.

Warning: Never fall back to another payment method. Whenever the requested payment method cannot be used, the booking must be rejected.

object (Basic representation of the contact)

Contact details of the person booking the service. This is the contact the supplier uses to reach the passenger about the booking, and is not necessarily one of the passengers listed in the request.

Suppliers differ in how much of this they need. When an offer carries requiredContactData, each flag set to true there marks a value that must be provided here.

object (Metadata)

Responses

Request samples

Content type
application/json
{
  • "passengers": [
    ],
  • "metadata": {
    },
  • "contact": {
    },
  • "options": {
    },
  • "persistedStorage": "persistedStorage",
  • "selectedFareId": "F:INCLUSIVE_PLUS",
  • "paymentMethod": "invoice",
  • "maxPriceVariationPercentage": 25,
  • "quoteId": "quoteId",
  • "connections": [
    ],
  • "billing": {
    }
}

Response samples

Content type
application/json
{
  • "pnrLocator": "pnrLocator",
  • "bookStatus": "BOOKED",
  • "salesPrice": {
    },
  • "rawRequests": [
    ],
  • "ticketInformation": [
    ],
  • "pnrStatus": "OPEN",
  • "bookingId": "bookingId",
  • "rawResponses": [
    ]
}

Cancel the transport booking

If a successful booking was made before, it can be cancelled using this endpoint.

Authorizations:
ApiKeyAuth
header Parameters
Contract-Id
string
Example: nicetours, 123456

An identifier of the contract to differentiate configuration, options or settings. This is one of two supported identification methods. Either provide a Contract-Id header, or provide Login and Password headers. Both may be provided simultaneously if required by the integration. The identification method should be agreed with Nezasa before development starts.

Login
string

Login identifier for supplier authentication. An alternative to the Contract-Id header. When using login-based authentication, both Login and Password headers should be provided. The identification method should be agreed with Nezasa before development starts.

Password
string <password>

Password for supplier authentication. Used together with the Login header as an alternative to the Contract-Id header. The identification method should be agreed with Nezasa before development starts.

Request Body schema: application/json
required
bookingId
string

The bookingId of the booking to be canceled.

object (CancelOptions)
object (Metadata)

Responses

Request samples

Content type
application/json
{
  • "metadata": {
    },
  • "options": {
    },
  • "bookingId": "BOOKING-123456"
}

Response samples

Content type
application/json
{
  • "cancelStatus": "CANCELLED",
  • "rawRequests": [
    ],
  • "ticketInformation": [
    ],
  • "rawResponses": [
    ]
}

Post Booking

Fetch booking details

If a successful booking was made before, it can be retrieved using this endpoint.

Authorizations:
ApiKeyAuth
header Parameters
Contract-Id
string
Example: nicetours, 123456

An identifier of the contract to differentiate configuration, options or settings. This is one of two supported identification methods. Either provide a Contract-Id header, or provide Login and Password headers. Both may be provided simultaneously if required by the integration. The identification method should be agreed with Nezasa before development starts.

Login
string

Login identifier for supplier authentication. An alternative to the Contract-Id header. When using login-based authentication, both Login and Password headers should be provided. The identification method should be agreed with Nezasa before development starts.

Password
string <password>

Password for supplier authentication. Used together with the Login header as an alternative to the Contract-Id header. The identification method should be agreed with Nezasa before development starts.

Request Body schema: application/json
required
bookingId
string

The bookingId of the booking to be retrieved.

object (Metadata)

Responses

Request samples

Content type
application/json
{
  • "metadata": {
    },
  • "bookingId": "BOOKING-123456"
}

Response samples

Content type
application/json
{
  • "pnrLocator": "pnrLocator",
  • "rawRequests": [
    ],
  • "ancillaryList": [
    ],
  • "details": {
    },
  • "ticketInformation": [
    ],
  • "pnrStatus": "OPEN",
  • "rawResponses": [
    ]
}