API docs by Redocly

Connect API for Ground Transports (1.9.1)

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. Connect API for Ground Transports focuses specifically on the ground transports services, including primarily shuttles and taxis, ferries, trains and buses.

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

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

  2. Checking Ground Transports Availability: This endpoint extends the functionality above. In addition to providing ground transports details, it also verifies the the current status of the ground transports' availability. This call returns a quote ID. The quote ID is used to book the ground transports.

  3. Booking a Ground Transports: This endpoint enables booking a specific ground transports. It requires the ID of the ground transports quote and customer details for a successful booking. This call returns a booking ID.

  4. Canceling a Ground Transports booking: This endpoint cancels a specific ground transports booking. It requires the booking ID to perform the cancellation.

Change History

API Version Docs Version Changes
1.0 08.07.2025 Initial version
1.1 29.07.2025 Added voucherUrls field to GroundTransportBooking response
1.2 21.01.2026 Added optional timeInterval and maxOffers parameters to search request
1.3 26.01.2026 Added GroundTransportSegmentCategory schema, startTime and segments to GroundTransportServiceCategory, id to GroundTransportSegmentOffer. Deprecated departureDatetime, arrivalDatetime, durationInMinutes in GroundTransportSegmentOffer
1.4 29.01.2026 Renamed maxOffers to maxServiceCategories in search request. Renamed startTime to departureTime in GroundTransportServiceCategory. Updated timeInterval, maxServiceCategories and departureTime descriptions. Made departureDatetime and arrivalDatetime non-required in GroundTransportSegmentOffer
1.5 03.02.2026 Added a new endpoint to get details of a specific offer. Extend segments to with carrierLogo and lineDetails. Extend GroundTransportRequestLocation with stationCode, cityCode, cityName, countryCode
1.6 06.02.2026 Extend availability request and booking request with more attributes (departureDateTime, arrivalDateTime, fareClass, carrier, etc). Extended GroundTransportResponseLocation with stationCode.
1.7 25.02.2026 Added travelAgentEmail, travelAgentFirstName, travelAgentLastName, travelAgencyShortName, travelAgencyEmail to Metadata
1.8 09.03.2026 Added includedAmenities each segment of the offer offer, added externalReference` on the service category
1.9 20.04.2026 Made Contract-Id optional, added Login and Password headers as alternative identification method
1.9.1 29.04.2026 Made connectionId required on the requests

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.

Authorizations:
ApiKeyAuth

Responses

Response samples

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

Search and Book

Check availability of a ground transport offer

Verifies the current availability status of a specific ground transport offer and prepares the offer for booking. After the availability has been confirmed, it is expected the offer booking is ensured for limited time, e.g. 30 minutes.

Authorizations:
ApiKeyAuth
header Parameters
traceparent
string
Example: 00-666b4b3800000000089918a4bf7e8d29-40eeac6740412d3f-01

For tracking and debugging, we will include a tracing header with every request. This trace ID follows the W3C Trace Context standard. Users can see this same header in the Trip Builder API responses and match it with data in the Supplier system if needed.

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
reference
required
string

The offer reference returned from the ground transport search call.

serviceCategoryReference
required
string

Selected service category reference. Successful response indicates this particular service category is still available. Provide quote only for this single category.

currency
required
string

Preferred currency. 3-letter code (ISO 4217).

Array of objects (Basic representation of a pax)

Passengers using the transport

object (GroundTransportRequestLocation)

Description of the location. At least one of areaCoordinate + areaRadius, coordinate or iataCode is provided, but more than one can be supplied. The locations should be prioritised in the order of:

  • iataCode
  • locode
  • coordinate
  • area

The response will indicate which location reference was used to align the transport offer to.

object (GroundTransportRequestLocation)

Description of the location. At least one of areaCoordinate + areaRadius, coordinate or iataCode is provided, but more than one can be supplied. The locations should be prioritised in the order of:

  • iataCode
  • locode
  • coordinate
  • area

The response will indicate which location reference was used to align the transport offer to.

departureDateTime
string

Earliest permitted arrival local date and time in ISO8601 format (yyyy-MM-ddTHH:mm:ss.SSS).

arrivalDateTime
string

Earliest permitted arrival local date and time in ISO8601 format (yyyy-MM-ddTHH:mm:ss.SSS).

carrier
string

The carrier code

fareClass
string

The fare class code

lang
required
string (Supported languages)
Default: "de"
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
{
  • "reference": "reference",
  • "carrier": "carrier",
  • "fareClass": "fareClass",
  • "metadata": {
    },
  • "departureLocation": {
    },
  • "departureDateTime": "2024-06-15T10:00:00.000",
  • "currency": "EUR",
  • "arrivalDateTime": "2024-06-15T11:00:00.000",
  • "lang": "de",
  • "paxes": [
    ],
  • "arrivalLocation": {
    },
  • "serviceCategoryReference": "serviceCategoryReference"
}

Response samples

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

Book a ground transport

Books a specific ground transport offer.

Authorizations:
ApiKeyAuth
header Parameters
traceparent
string
Example: 00-666b4b3800000000089918a4bf7e8d29-40eeac6740412d3f-01

For tracking and debugging, we will include a tracing header with every request. This trace ID follows the W3C Trace Context standard. Users can see this same header in the Trip Builder API responses and match it with data in the Supplier system if needed.

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
reference
required
string

The reference of the quote returned from the availability call to be booked.

serviceCategoryReference
string

Selected service category reference.

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

2-letter code (ISO 639-1)

required
Array of objects (Basic representation of a pax)

Passengers using the transport

required
object (Basic representation of the contact)
object (GroundTransportRequestLocation)

Description of the location. At least one of areaCoordinate + areaRadius, coordinate or iataCode is provided, but more than one can be supplied. The locations should be prioritised in the order of:

  • iataCode
  • locode
  • coordinate
  • area

The response will indicate which location reference was used to align the transport offer to.

object (GroundTransportRequestLocation)

Description of the location. At least one of areaCoordinate + areaRadius, coordinate or iataCode is provided, but more than one can be supplied. The locations should be prioritised in the order of:

  • iataCode
  • locode
  • coordinate
  • area

The response will indicate which location reference was used to align the transport offer to.

departureDateTime
string

Earliest permitted arrival local date and time in ISO8601 format (yyyy-MM-ddTHH:mm:ss.SSS).

arrivalDateTime
string

Earliest permitted arrival local date and time in ISO8601 format (yyyy-MM-ddTHH:mm:ss.SSS).

carrier
string

The carrier code

fareClass
string

The fare class code

onRequestWebhookUrl
string

URL of the webhook endpoint to be used to confirm or reject an on-request booking, i.e. booking which returned a status of OnRequest In such cases, the webhook should be used to inform the caller once the on-request booking is confirmed to be either booked or unavailable.

object (Metadata)

Responses

Request samples

Content type
application/json
{
  • "metadata": {
    },
  • "departureLocation": {
    },
  • "onRequestWebhookUrl": "onRequestWebhookUrl",
  • "paxes": [
    ],
  • "arrivalLocation": {
    },
  • "reference": "reference",
  • "carrier": "carrier",
  • "fareClass": "fareClass",
  • "contact": {
    },
  • "departureDateTime": "2024-06-15T10:00:00.000",
  • "arrivalDateTime": "2024-06-15T11:00:00.000",
  • "lang": "de",
  • "serviceCategoryReference": "serviceCategoryReference"
}

Response samples

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

Search details

Get the details of ground transport offer.

Obtain the details of a ground transport offer (taxis, shuttles, trains, buses, ferries, etc.) for a given offer id.

Authorizations:
ApiKeyAuth
header Parameters
traceparent
string
Example: 00-666b4b3800000000089918a4bf7e8d29-40eeac6740412d3f-01

For tracking and debugging, we will include a tracing header with every request. This trace ID follows the W3C Trace Context standard. Users can see this same header in the Trip Builder API responses and match it with data in the Supplier system if needed.

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
currency
required
string

Preferred currency. 3-letter code (ISO 4217).

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

2-letter code (ISO 639-1)

object (Paging management for a request)
offerId
string

ID of the requested offer

required
Array of objects (GroundTransportConnection_1) non-empty

Requested connections. For one way transports, a single element. For return transports, two elements. May contain more complex connection combinations.

required
Array of objects (Basic representation of a pax)

Passengers using the transport

Responses

Request samples

Content type
application/json
{
  • "offerId": "offerId",
  • "currency": "currency",
  • "paging": {
    },
  • "lang": "de",
  • "paxes": [
    ],
  • "connections": [
    ]
}

Response samples

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

Post Booking

Cancel a ground transport booking

Cancels a specific ground transport booking.

Authorizations:
ApiKeyAuth
header Parameters
traceparent
string
Example: 00-666b4b3800000000089918a4bf7e8d29-40eeac6740412d3f-01

For tracking and debugging, we will include a tracing header with every request. This trace ID follows the W3C Trace Context standard. Users can see this same header in the Trip Builder API responses and match it with data in the Supplier system if needed.

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
bookingReference
required
string

The bookingReference of the booking to be canceled.

object (Metadata)

Responses

Request samples

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

Response samples

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