API docs by Redocly

Connect API for Activities (2.9.0)

Download OpenAPI specification:

The Activity Service API is a web service that provides access to a range of single day activities and multi day tours for users. It's primarily designed to allow users to search, view, book, and cancel activities in an efficient and user-friendly manner.

Here are the key functionalities of the API:

  1. Get List of Activities: This endpoint returns a list of all available activities. Each activity comes with basic information like name and description.
  2. Get Activity Description: This endpoint provides a detailed description of a specific activity. It requires the ID of the activity as input.
  3. Check Activity Availability: This feature is integrated within the activity description endpoint. Along with the description, it also shows the current availability status of the activity.
  4. Book an Activity: This endpoint allows users to book a specific activity. It requires the ID of the activity and user details for successful booking.
  5. Cancel Booking: This endpoint allows users to cancel their booking for a specific activity. It requires the ID of the booking to perform the cancellation.

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.05.2023 Initial version
2.0 01.03.2025 Updated to support multi-day tours
2.1 28.08.2025 Added metadata field to all request schemas
2.2 10.09.2025 Added optional request body with metadata field to cancellation endpoint
2.3 29.10.2025 Added room allocation support for multi-day tours
2.4 12.11.2025 Added optional supplier field to ActivityOffer schema for offer source identification
2.5 24.11.2025 Added forAllPax field to ActivityQuestion and paxRefId field to ActivityBookingActivityAnswer for per-pax questions support
2.6 27.11.2025 Added subName2 through subName5 fields to ActivityServiceCategory for multi-level hierarchy support
2.7 18.02.2026 Added requiredPassengerData and requiredContactData to ActivityOffer for dynamic supplier required data support
2.8 25.02.2026 Added travelAgentEmail, travelAgentFirstName, travelAgentLastName, travelAgencyShortName, travelAgencyEmail to Metadata
2.9 20.04.2026 Made Contract-Id optional, added Login and Password headers as alternative identification method

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"
}

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.

Get a list of offers.

This endpoint allows users to search for bookable activities in the specified period. We expect a single offer for each activity, preferably a basic category offer for an adult. A separate call to a different endpoint will fetch the details, including all offers, of the activity.

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

A 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)
required
object (Activity criteria related to time and duration)
required
object (Representation of an area)

At the moment it supports only search in a circle.

object (Representation of an area)

At the moment it supports only search in a circle.

required
Array of objects (Basic representation of a pax)

Passengers participating in the activity

object (RoomAllocationRequest)

Requested room allocation for multi-day tours. Specifies how passengers should be distributed across rooms for pricing purposes.

object (Metadata)

Responses

Request samples

Content type
application/json
{
  • "currency": "string",
  • "lang": "de",
  • "paging": {
    },
  • "timeCriteria": {
    },
  • "startLocation": {
    },
  • "endLocation": {
    },
  • "paxes": [
    ],
  • "roomAllocation": {
    },
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "activities": [
    ],
  • "paging": {
    }
}

[Deprecated] Get the detail of an activity offer

The reference of the offer. This value is returned by ActivityOffer message.

Authorizations:
ApiKeyAuth
path Parameters
reference
required
string

The reference of the offer. This value is returned by ActivityOffer message.

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

Desired currency (3-letter 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 (Paging management for a request)
required
object (CommonTravelPeriod)

Generic travel period

required
Array of objects (Basic representation of a pax)

Passengers participating in the activity

pickupId
string

If selected, an ID of one of the pick-up options proposed in activity offer.

dropoffId
string

If selected, an ID of one of the drop-off options proposed in activity offer.

Responses

Request samples

Content type
application/json
{
  • "currency": "string",
  • "lang": "de",
  • "paging": {
    },
  • "period": {
    },
  • "paxes": [
    ],
  • "pickupId": "string",
  • "dropoffId": "string"
}

Response samples

Content type
application/json
{
  • "activity": {
    },
  • "questions": [
    ]
}

Get the detail of an activity offer

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

The reference of the offer. This value is returned by ActivityOffer message.

currency
required
string

Desired currency (3-letter 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 (Paging management for a request)
required
object (CommonTravelPeriod)

Generic travel period

required
Array of objects (Basic representation of a pax)

Passengers participating in the activity

pickupId
string

If selected, an ID of one of the pick-up options proposed in activity offer.

dropoffId
string

If selected, an ID of one of the drop-off options proposed in activity offer.

object (RoomAllocationRequest)

Requested room allocation for multi-day tours. Specifies how passengers should be distributed across rooms for pricing purposes.

object (Metadata)

Responses

Request samples

Content type
application/json
{
  • "reference": "string",
  • "currency": "string",
  • "lang": "de",
  • "paging": {
    },
  • "period": {
    },
  • "paxes": [
    ],
  • "pickupId": "string",
  • "dropoffId": "string",
  • "roomAllocation": {
    },
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "activity": {
    },
  • "questions": [
    ]
}

[Deprecated] Check availability of an activity offer

This endpoint allows a user to verify whether the activity with selected options is still available. If available the endpoint returns a response with activity details again. In case of an error, the error response is returned.

Authorizations:
ApiKeyAuth
path Parameters
reference
required
string

The reference of the offer. This value is returned by ActivityOffer message.

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

The reference of the offer

serviceCategoryReferences
required
Array of strings

The reference(s) of the service category (could represent many tickets for the same activity)

selectedExtrasReferences
Array of strings (References of extras (tour extras and section extras) selected from the activity offer)
currency
required
string

Desired currency (3 letter code)

required
Array of objects (Basic representation of a pax)

Passengers participating in the activity

Array of objects (An answer to an ActivityQuestion)

Answers to activity questions

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

pickUpId
string

If selected, an ID of one of the pick-up options proposed in activity offer.

dropOffId
string

If selected, an ID of one of the drop-off options proposed in activity offer.

object (Basic representation of the contact)
activityLanguage
string

Selected language of the activity

onRequestWebhookUrl
string

Webhook URL for the supplier to update the status of an "On Request" booking.

object (Metadata)

Responses

Request samples

Content type
application/json
{
  • "period": {
    },
  • "metadata": {
    },
  • "dropOffId": "dropOffId",
  • "answers": [
    ],
  • "onRequestWebhookUrl": "onRequestWebhookUrl",
  • "paxes": [
    ],
  • "selectedExtrasReferences": [
    ],
  • "reference": "reference",
  • "serviceCategoryReferences": [
    ],
  • "contact": {
    },
  • "currency": "currency",
  • "pickUpId": "pickUpId",
  • "lang": "de",
  • "activityLanguage": "activityLanguage"
}

Response samples

Content type
application/json
{
  • "offer": {
    },
  • "questions": [
    ]
}

Check availability of an activity offer

This endpoint allows a user to verify whether the activity with selected options is still available. If available the endpoint returns a response with activity details again. In case of an error, the error response is returned.

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

The reference of the offer

serviceCategoryReferences
required
Array of strings

The reference(s) of the service category (could represent many tickets for the same activity)

selectedExtrasReferences
Array of strings (References of extras (tour extras and section extras) selected from the activity offer)
currency
required
string

Desired currency (3 letter code)

required
Array of objects (Basic representation of a pax)

Passengers participating in the activity

Array of objects (An answer to an ActivityQuestion)

Answers to activity questions

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

pickUpId
string

If selected, an ID of one of the pick-up options proposed in activity offer.

dropOffId
string

If selected, an ID of one of the drop-off options proposed in activity offer.

object (Basic representation of the contact)
activityLanguage
string

Selected language of the activity

onRequestWebhookUrl
string

Webhook URL for the supplier to update the status of an "On Request" booking.

object (Metadata)

Responses

Request samples

Content type
application/json
{
  • "period": {
    },
  • "metadata": {
    },
  • "dropOffId": "dropOffId",
  • "answers": [
    ],
  • "onRequestWebhookUrl": "onRequestWebhookUrl",
  • "paxes": [
    ],
  • "selectedExtrasReferences": [
    ],
  • "reference": "reference",
  • "serviceCategoryReferences": [
    ],
  • "contact": {
    },
  • "currency": "currency",
  • "pickUpId": "pickUpId",
  • "lang": "de",
  • "activityLanguage": "activityLanguage"
}

Response samples

Content type
application/json
{
  • "offer": {
    },
  • "questions": [
    ]
}

Bookings

Cancel a previously booked activity

Authorizations:
ApiKeyAuth
query Parameters
bookingId
required
string

The booking identifier

reference
string

The offer reference

itemsIds
Array of strings

Optional. the sub-items of the booking so that the cancellation can be done

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
optional
object (Metadata)

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "cancellationFee": {
    },
  • "bookingId": "bookingId"
}

Book an activity

This endpoint allows a user to book an activity using various parameters. Upon successful booking, the endpoint returns a response with booking details. In case of an error, the error response is returned.

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

The reference of the offer

serviceCategoryReferences
required
Array of strings

The reference(s) of the service category (could represent many tickets for the same activity)

selectedExtrasReferences
Array of strings (References of extras (tour extras and section extras) selected from the activity offer)
currency
required
string

Desired currency (3 letter code)

required
Array of objects (Basic representation of a pax)

Passengers participating in the activity

Array of objects (An answer to an ActivityQuestion)

Answers to activity questions

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

pickUpId
string

If selected, an ID of one of the pick-up options proposed in activity offer.

dropOffId
string

If selected, an ID of one of the drop-off options proposed in activity offer.

object (Basic representation of the contact)
activityLanguage
string

Selected language of the activity

onRequestWebhookUrl
string

Webhook URL for the supplier to update the status of an "On Request" booking.

object (Metadata)

Responses

Request samples

Content type
application/json
{
  • "period": {
    },
  • "metadata": {
    },
  • "dropOffId": "dropOffId",
  • "answers": [
    ],
  • "onRequestWebhookUrl": "onRequestWebhookUrl",
  • "paxes": [
    ],
  • "selectedExtrasReferences": [
    ],
  • "reference": "reference",
  • "serviceCategoryReferences": [
    ],
  • "contact": {
    },
  • "currency": "currency",
  • "pickUpId": "pickUpId",
  • "lang": "de",
  • "activityLanguage": "activityLanguage"
}

Response samples

Content type
application/json
{
  • "vouchersUrls": [
    ],
  • "bookStatus": "Confirmed",
  • "itemsIds": [
    ],
  • "supplier": "supplier",
  • "bookingId": "bookingId"
}

[Yet to be revised] Fetch a list of already booked activities

Fetch a list of already booked activities for the given booking that can be pulled from the provider.

Authorizations:
ApiKeyAuth
query Parameters
bookingId
required
string

Generic ID of the booking in system. A single booking may contain more than one activity/tickets booked.

lang
string

The desired language in the response (2 letter code)

currency
string

The desired currency in the response (3 letter code)

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.

Responses

Response samples

Content type
application/json
{
  • "activities": [
    ]
}

[Yet to be revised] Fetch booking details.

Fetch details of an already booked activities from the provider.

Authorizations:
ApiKeyAuth
query Parameters
bookingId
required
string

Generic ID of the booking in system. A single booking may contain more than one activity/tickets booked.

lang
required
string

The desired language in the response (2 letter code)

currency
string

The desired currency in the response (3 letter code)

activityIds
required
Array of strings

Specific IDs of the activities in the booking. It is expected that exactly one activity will match every ID.

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.

Responses

Response samples

Content type
application/json
{
  • "details": [
    ]
}