API docs by Redocly

Connect API for Accommodations (1.11.0)

Download OpenAPI specification:

The connectAPI for accommodations defines a service API that lets users search for, view, book, and cancel accommodations via TripBuilder.

Key Features:

  1. Get List of Accommodations: Retrieves a list of all available accommodations, including basic details like code, room description, and price.
  2. Get Accommodation Details: Provides detailed information about a specific accommodation using its reference.
  3. Check Accommodation Availability: Shows the current availability status of an accommodation along with its description.
  4. Book an Accommodation: Allows users to book an accommodation offer using its reference and user details.
  5. Cancel Booking: Enables users to cancel a booking using its booking reference.

This API is designed to be RESTful, using standard HTTP methods like GET, POST, and DELETE, and it primarily exchanges data in JSON format.

Change History

API Version Docs Version Changes
1.0 31.07.2023 Initial version
1.1 05.06.2024 Extended spec to support Book and Cancel actions
1.2 04.10.2024 Extended spec to split offer between search and details offer.
Added support for available board codes and cancellation policies in search offer model.
Removed deprecated location field from search and details offer
1.3 28.01.2025 Added 'filters' object to AccommodationOffersRequest and AccommodationOfferDetailsRequest
Updated documentation with supplier currently supported by Nezasa
1.4 07.08.2025 Added NBC (Non-Bookable Content) import endpoint for hotel static data synchronization
1.5 05.11.2025 Made 'added' and 'updated' fields optional in NBC Dates schema
1.6 10.01.2026 BREAKING: NBC images field now uses ImageGroup[] with nested ImageResolution[] for multi-resolution image support
1.7 04.02.2026 Added requiredPassengerData and requiredContactData to AccommodationDetailsOffer
1.8 25.02.2026 Added travelAgentEmail, travelAgentFirstName, travelAgentLastName, travelAgencyShortName, travelAgencyEmail to Metadata
1.9 20.04.2026 Made Contract-Id optional, added Login and Password headers as alternative identification method
1.10 08.05.2026 Added maxPriceVariationPercentage to AccommodationBookingRequest to let callers tolerate small price changes at booking time (applied to increases only when the supplier API allows it; symmetric otherwise)
1.11 08.05.2026 BREAKING: NBC import endpoint now accepts a languages: string[] array (replacing the single language: string) and returns NBCHotelData.descriptions as an array of LocalizedDescription (one entry per requested language). The redundant tourOperator request field has been removed (caller is identified via Contract-Id / Login / Password headers).

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

A method for healthcheck purposes

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

Responses

Response samples

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

Offers

Get a list of accommodation offers.

This API uses POST instead of GET for some read operations. This is due to the complexity and size of some queries.

In HTTP/1.1, GET is typically used for data retrieval. It should be safe and idempotent, causing no side effects. However, GET has limitations with complex queries or large data. For instance, some servers or browsers limit the maximum URL length for GET requests.

POST requests carry their data in the body of the request. This allows for larger and more complex data to be sent. This is useful when the data volume or complexity of query parameters exceeds GET limitations.

In this API, POST is used for some read operations to overcome these GET limitations. This allows handling of complex queries and large data effectively, ensuring reliable and efficient API operation.

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)

required
object (Paging management for a request)
required
object (CommonTravelPeriod)

Generic travel period

accommodationCodes
required
Array of strings

Required accommodation codes in one of the formats supported by Nezasa.

required
Array of objects (Pax allocation in an accommodation)

Required room allocation

boardCodes
Array of strings
Default: []

Required Nezasa board codes. For possible values, see AccommodationRoom in AccommodationOffer. No filtering will be applied if left empty.

onRequest
boolean
Default: false

Whether to return on request offers in the response

nonRefundable
boolean
Default: false

Whether to return non-refundable offers in the response

market
string

Market country or point-of-sale. 2 letters code of the country (ISO 3166-1 alpha-2)

purchaseChannel
string

Channel (in supplier-specific format) via which the content is offered

object (Supplier filter)

Defines filtering options for accommodation offers based on suppliers. This object allows for specifying which suppliers should be included or excluded from the search results, providing more control over the source of accommodation offers.

object (Metadata)

Responses

Request samples

Content type
application/json
{
  • "period": {
    },
  • "metadata": {
    },
  • "accommodationCodes": [
    ],
  • "onRequest": false,
  • "paging": {
    },
  • "boardCodes": [
    ],
  • "filters": {
    },
  • "nonRefundable": false,
  • "market": "DE",
  • "roomAllocation": [
    ],
  • "currency": "EUR",
  • "lang": "de",
  • "purchaseChannel": "K"
}

Response samples

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

OfferDetails

Get the details of an accommodation 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
accommodationCode
string

Required accommodation code in one of the formats supported by Nezasa.

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)

required
object (CommonTravelPeriod)

Generic travel period

required
Array of objects (Pax allocation in an accommodation)

Required room allocation

boardCodes
Array of strings
Default: []

Required Nezasa board codes. For possible values, see AccommodationRoom in AccommodationOffer. No filtering will be applied if left empty.

onRequest
boolean
Default: false

Whether to return on request offers

nonRefundable
boolean
Default: false

Whether to return non-refundable offers

market
string

Market country or point-of-sale. 2 letters code of the country (ISO 3166-1 alpha-2)

purchaseChannel
string

Channel (in supplier-specific format) via which the content is offered

object (Supplier filter)

Defines filtering options for accommodation offers based on suppliers. This object allows for specifying which suppliers should be included or excluded from the search results, providing more control over the source of accommodation offers.

object (Metadata)

Responses

Request samples

Content type
application/json
{
  • "market": "DE",
  • "accommodationCode": "123456",
  • "period": {
    },
  • "metadata": {
    },
  • "onRequest": false,
  • "roomAllocation": [
    ],
  • "currency": "EUR",
  • "boardCodes": [
    ],
  • "filters": {
    },
  • "lang": "de",
  • "nonRefundable": false,
  • "purchaseChannel": "K"
}

Response samples

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

Availability

Check availability of accommodation offer before booking.

When the users selects an offer, or before Tripbuilder books an offer, we check availability. This ensures that the offer is still available at the same price with the same amenities and room types. The offer reference provided by the integration partner must contain all the information needed to uniquely identify the offer and subsequent 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
reference
string

The offer reference returned from the accommodations details call.

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)

market
string (Market country or point-of-sale.)

2 letters code of the country (ISO 3166-1 alpha-2)

object (Metadata)

Responses

Request samples

Content type
application/json
{
  • "reference": "reference",
  • "market": "DE",
  • "metadata": {
    },
  • "currency": "EUR",
  • "lang": "de"
}

Response samples

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

Cancel

Cancels a reservation

Cancels a reservation for a given booking reference. The booking reference is returned by the book response. The integration partner must use this reference to uniquely identify and cancel the booking. If the booking consists of more that one room, the integration partner must cancel each room individually.

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
string

The reference of the booking to be canceled.

object (Metadata)

Responses

Request samples

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

Response samples

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

Book

Book an offer in the supplier system

Books an offer in the supplier system. If the offer includes more than one room and the supplier system does not support multi-room bookings, TripBuilder expects the integration partner to book multiple rooms. This means the integration partner must manage errors themselves.

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
string

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

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 (Expected room allocation)

The room reference refers to the room allocationReference returned by the availability response and assigns paxes to individual rooms.

required
object (Basic representation of the contact)
onRequestWebhookUrl
string

URL of the webhook endpoint to be used to confirm 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.

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

Caller-defined tolerance for a price change between the offer that was previously quoted (via AccommodationAvailabilityRequest / AccommodationOfferDetailsRequest) and the price returned by the supplier at booking time.

Expected behaviour

Preferred (asymmetric) — when the supplier API exposes a price-tolerance parameter that distinguishes increases from decreases, or when the integration partner can evaluate the comparison itself, the delta MUST be applied upward only:

  • 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) — when the supplier API only exposes a single tolerance parameter that it applies to deviations in either direction, the same delta MAY be forwarded as-is and 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. This is acceptable, but the asymmetric behaviour above is preferred whenever it can be implemented.

Unsupported — when the supplier API exposes no price-tolerance mechanism and the integration partner cannot evaluate the comparison itself, the field may be ignored and 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.

object (Metadata)

Responses

Request samples

Content type
application/json
{
  • "reference": "reference",
  • "metadata": {
    },
  • "roomAllocation": [
    ],
  • "contact": {
    },
  • "lang": "de",
  • "onRequestWebhookUrl": "onRequestWebhookUrl",
  • "maxPriceVariationPercentage": 25
}

Response samples

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

Non-bookable content

Import NBC content

Import hotel non-bookable content from supplier system.

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
languages
required
Array of strings (Requested response languages) non-empty unique [ items^[a-z]{2}$ ]

List of languages in which property content should be returned. Each entry MUST be a valid two-letter language code conforming to ISO 639-1 (e.g. "en", "de", "fr", "es", "it"). The request MUST include at least one language.

Expected behaviour

Strictly opt-in. For every property in the response, NBCHotelData.descriptions contains entries only for languages listed here; any language available at the source but not listed is ignored.

Per property:

  • A requested language with source content produces one entry.
  • A requested language with no source content is silently omitted — the request does not fail, and unaffected languages and properties still return normally.
  • When no requested language intersects with the source, the property is still returned with descriptions: [] (never omitted, never null).

Example

With languages: ["en", "de", "fr"]:

  • Property A — source has English, German, and Italian content. Returned descriptions contains two entries ("en", "de"). Italian is ignored (not requested); French is omitted (no source content for this property).
  • Property B — source has only Italian and Spanish content. Returned descriptions is [] — no requested language intersects with the source, but the property itself is still returned.
countryCode
string^[A-Z]{2}$

Search for properties only in the desired country. Must be a valid two-letter country code conforming to ISO 3166-1 alpha-2 standards (e.g., "FR", "DE", "ES", "IT", "PT").

updatedStart
string

Search for properties added on or after the requested UTC date, in ISO 8601 format (YYYY-MM-DD)

updatedEnd
string

Search for properties added on or before the requested UTC date, in ISO 8601 format (YYYY-MM-DD)

propertyId
string

The ID of the property you want to search for

batchToken
string

The token of the next batch provided in the last response.

Responses

Request samples

Content type
application/json
{
  • "updatedStart": "updatedStart",
  • "updatedEnd": "updatedEnd",
  • "languages": [
    ],
  • "countryCode": "FR",
  • "batchToken": "import_20250128_120000_abc123",
  • "propertyId": "12345"
}

Response samples

Content type
application/json
{}