Skip to content
/Reviews

Musement API (3.5.0)

For merchant or affiliate partners wishing to use the Musement API.

Find out more about Musement API

Authentication

See the Authentication section for details on how to authenticate with the API.

Release notes

2024-06-18

Endpoints

  • GET /activities/{activityUuid}/dates/{date}
    • Changed default min_buy value from -1 to 1

2024-02-21

Endpoints

  • Added GET /orders/{orderUuid}/refunds
    • Returns an array of paid refunds for an order

2024-02-20

Endpoints

  • GET /activities/{activityUuid}/dates/{date}
    • Added availability, max_buy and min_buy properties to timeslots. For more info, check out our guide
Download OpenAPI description
openapi.json
openapi.yaml
Overview
API distribution team
api-distribution@tui.com
License
Apache 2.0
Terms of Service
Languages
Servers
Mock server
https://partner-api.musement.com/_mock/reference/openapi
Sandbox server
https://sandbox.musement.com/api/v3
Production server
https://api.musement.com/api/v3

Searching activities

A collection of endpoints which can be used to search the catalog for relevant activities.

Operations

Activity info

A collection of endpoints which can be used to provide information to customers about a specific activity.

Operations

Pickups

Some activities require selecting a pickup location as part of the booking flow.

Operations

Dates

A collection of endpoints for selecting available dates and products.

Operations

Carts

A collection of endpoints for managing a customer's cart during the booking flow.

Operations

Customer info

When making a reservation, different steps must be taken to provide information about the customers. This collection includes endpoints for submitting info about the lead booker, extra customer data and participant info.

Operations

Orders

A collection of endpoints for managing orders as part of the booking flow.

Operations

Payments

A collection of endpoints regarding payment during the booking flow. Partners have multiple payment options at their disposal, depending on agreements with the Strategic partnerships team.

Operations

Cancellations

It is possible to cancel reservations, provided that the activity in question is refundable.

Operations

Activities

Activities can be any tour, attraction or experience that customers can reserve via the Musement API.

Operations

Categories

Categories group activities based on similar characteristics.

Operations

Cities

Cities are different types of destinations: islands, natural landmarks, beaches, actual cities and more.

Operations

Countries

A collection of endpoints related to countries in the Musement catalog.

Operations

Lists

Lists are collections of Musement activities and third-party destinations grouped together based on editorial themes.

Operations

Venues

Venues are popular attractions or landmarks.

Operations

Additional searches

A collection of additional endpoints which can be used to search parts of the catalog.

Operations

Carts

A collection of cart endpoints which are not strictly necessary for the booking flow.

Operations

Metadata

Metadata is used for configuring several activity properties.

Operations

Reviews

Customers may leave reviews about their experience with an activity. Reviews consist of a numeric rating and optional written comment.

Operations

Search reviews for activity

Request

Returns an array of reviews for an activity.

Path
activityUuidstring(uuid)required

The UUID of the activity.

Query
localestring(Language code)

Filter results by the locale property.

Example: locale=en-US
limitinteger[ 1 .. 500 ]

Limit the maximum number of reviews to include in the response.

Default 6
pageinteger>= 1

Get the page number of reviews, based on the limit parameter.

Default 1
rating[between][]Array of strings

Filter the reviews by their rating_value property. Parameter accepts multiple ranges. The response contains reviews with a rating_value between at least one of the provided ranges. Each parameter requires two integer values, a minimum and maximum, separated by ...

Example: rating[between][]=1..7
sort_bystring

Sort reviews by one of the following choices:

  • HIGHEST-RATED: From highest rating_value to lowest.
  • LOWEST-RATED: From lowest rating_value to highest.
  • NEWEST: From most recent date to least recent.
  • PREFERRED-LANGUAGE: Reviews written in the same language as the Accept-Language header appear first.
Default "NEWEST"
Enum"HIGHEST-RATED""LOWEST-RATED""NEWEST""PREFERRED-LANGUAGE"
traveler_type_in[]Array of strings(TravelerType)

Filter reviews to those which match any of the specified traveler types:

  • ALONE: The customer was traveling alone.
  • AS-A-COUPLE: The customer was traveling as a couple.
  • WITH-FAMILY: The customer was traveling with their family.
  • WITH-FRIENDS: The customer was traveling with friends.

Using this parameter filters out reviews where customers did not specify their traveler type.

Items Enum"ALONE""AS-A-COUPLE""WITH-FAMILY""WITH-FRIENDS"
Headers
Accept-Languagestring(Language code)

The value of this parameter might affect the language of the content in the response, provided a translation in the requested language is available.

Default en-US
X-Musement-Applicationstring(Application value)

A partner's application value, used for analyzing API usage and to identify areas of improvement.

For more info, check out our guide.
X-Musement-Versionstring^[0-9]+?.[0-9]+?.[0-9]+?$

The API version to use for the request.

When absent, the latest version is used by default, however the latest version may not be stable. Partners are encouraged to use the latest stable version: 3.4.0.

Example: 3.4.0
For more info, check out our guide.
curl -i -X GET \
  'https://partner-api.musement.com/_mock/reference/openapi/activities/{activityUuid}/reviews?locale=en-US&limit=6&page=1&rating%5Bbetween%5D%5B%5D=1..7&sort_by=HIGHEST-RATED&traveler_type_in%5B%5D=ALONE' \
  -H 'Accept-Language: en-US' \
  -H 'X-Musement-Application: string' \
  -H 'X-Musement-Version: 3.4.0'

Responses

Reviews for activity

Headers
X-Number-Of-Elementsinteger>= 0

The number of items in the response.

X-Total-Countinteger>= 0

The total number of items available based on the request parameters.

X-Total-Pagesinteger>= 0

The total number of pages available based on the request parameters, the X-Total-Count response header value and the limit query parameter value.

Bodyapplication/jsonArray [
commentstring

The customer's review for the activity. This is always in the language the customer used and is not affected by the Accept-Language header value.

Example: "Just perfect!"
customer_countrystring

The customer's country, translated based on the Accept-Language header value.

Example: "Germany"
datestring(date)required

The date the review was submitted.

Example: "2020-04-13"
rating_valuenumber(float)[ 0 .. 10 ]required

The customer's rating for the activity on a scale of zero (poor) to ten (amazing).

Example: 9.9
uuidstring(uuid)required

The review's UUID.

Example: "d3edd1ff-91d5-4d56-ba93-47b49b921dcd"
]
Response
application/json
[
  {
    "comment": "Just perfect!",
    "customer_country": "Germany",
    "date": "2020-04-13",
    "rating_value": 9.9,
    "uuid": "d3edd1ff-91d5-4d56-ba93-47b49b921dcd"
  }
]

Add review to activity

Request

Add a review to an activity.

Security
Partner
Path
activityUuidstring(uuid)required

The UUID of the activity.

Bodyapplication/jsonrequired
ageinteger

The customer's age.

Example: 27
commentstring

The customer's written review of their experience.

Example: "Awesome experience."
is_publicboolean

Can we publish this review? If true, the review might be included in reviews for the activity, pending an internal evaluation. When false, the review will never be part of reviews for the activity, but its rating will be added to the activity's review statistics.

Default false
Example: true
localestring^[a-z]{1,8}(?:-[a-zA-Z0-9]{1,8})?

The language of the customer's written review, following RFC 3066.

Example: "en-GB"
order_item_uuidstring(uuid)required

The Musement order item UUID that the review is for.

Example: "d83d4e0a-e62b-4c81-b403-4206914cd697"
providerstringrequired

The name of the service providing the review data.

Example: "QUALTRICS"
provider_idstringrequired

The identifier for the review from the service providing the review data.

Example: "R_wXE9FFQ1qhK2J0w"
public_usernamestring

The customer's name as it should be displayed with the review.

Example: "John Doe"
rating_valueintegerrequired

The customer's rating of their experience, based on the rating_scale.

Example: 4
rating_scalestring(RatingScale)^\d{1,3}\.{2}\d{1,3}$required

The rating scale used for the review, from the lowest to the highest value: {lowest}..{highest}

Example: "1..5"
traveler_typestring(TravelerType)

The customer's traveler type.

Enum"ALONE""AS-A-COUPLE""WITH-FAMILY""WITH-FRIENDS"
Example: "WITH-FAMILY"
datestring(date-time)required

The date and time the review was written.

Example: "2021-11-18T15:13:13"
rating_categoriesArray of objects(Rating category breakdown)

A breakdown of the rating by category.

Example: [{"category_code":"SERVICE","category_rating":4,"rating_scale":"1..5"}]
curl -i -X POST \
  'https://partner-api.musement.com/_mock/reference/openapi/activities/{activityUuid}/reviews' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "age": 27,
    "comment": "Awesome experience.",
    "date": "2021-11-18T15:13:13",
    "is_public": true,
    "locale": "en-GB",
    "order_item_uuid": "d83d4e0a-e62b-4c81-b403-4206914cd697",
    "provider": "QUALTRICS",
    "provider_id": "R_wXE9FFQ1qhK2J0w",
    "public_username": "John Doe",
    "rating_categories": [
      {
        "category_code": "SERVICE",
        "category_rating": 4,
        "rating_scale": "1..5"
      }
    ],
    "rating_scale": "1..5",
    "rating_value": 4,
    "traveler_type": "WITH-FAMILY"
  }'

Responses

Created: review successfully submitted

Response
No content

Get review statistics for activity

Request

Returns statistics about the activity's reviews.

Path
activityUuidstring(uuid)required

The UUID of the activity.

Headers
Accept-Languagestring(Language code)

The value of this parameter might affect the language of the content in the response, provided a translation in the requested language is available.

Default en-US
X-Musement-Applicationstring(Application value)

A partner's application value, used for analyzing API usage and to identify areas of improvement.

For more info, check out our guide.
X-Musement-Versionstring^[0-9]+?.[0-9]+?.[0-9]+?$

The API version to use for the request.

When absent, the latest version is used by default, however the latest version may not be stable. Partners are encouraged to use the latest stable version: 3.4.0.

Example: 3.4.0
For more info, check out our guide.
curl -i -X GET \
  'https://partner-api.musement.com/_mock/reference/openapi/activities/{activityUuid}/reviews/statistics' \
  -H 'Accept-Language: en-US' \
  -H 'X-Musement-Application: string' \
  -H 'X-Musement-Version: 3.4.0'

Responses

Review statistics for activity

Bodyapplication/json
overall_ratingnumber(float)required

The overall rating of the reviews on a scale of zero (poor) to ten (amazing).

Example: 7.65
rating_categoriesArray of objectsrequired

A breakdown of each rating by category.

Example: [{"category_code":"SERVICE","category_name":"Service","category_rating":7.5}]
rating_categories[].​category_codestring(ReviewCategoryCode)

The code for the review category.

Enum"SAFETY""SERVICE""STAFF""VALUE-FOR-MONEY"
Example: "SERVICE"
rating_categories[].​category_namestring

The name of the category, translated based on the Accept-Language header value.

Example: "Service"
rating_categories[].​category_ratingnumber(float)

The overall rating for the category on a scale of zero (poor) to ten (amazing).

Example: 7.85
reviews_numberintegerrequired

The total number of reviews for the activity.

Example: 700
reviews_per_ratingArray of objectsrequired

A breakdown of the number of reviews per rating on the scale.

Example: [{"rating":1,"reviews_count":0},{"rating":2,"reviews_count":100},{"rating":3,"reviews_count":0},{"rating":4,"reviews_count":200},{"rating":5,"reviews_count":0},{"rating":6,"reviews_count":250},{"rating":7,"reviews_count":0},{"rating":8,"reviews_count":0},{"rating":9,"reviews_count":75},{"rating":10,"reviews_count":175}]
reviews_per_rating[].​ratingnumber(integer)

The rating value on a scale of zero (poor) to ten (amazing).

Example: 1
reviews_per_rating[].​reviews_countnumber(integer)

The number of reviews which use the rating.

Example: 5
Response
application/json
{
  "reviews_number": 700,
  "overall_rating": 7.65,
  "reviews_per_rating": [
    { … },
    { … },
    { … },
    { … },
    { … },
    { … },
    { … },
    { … },
    { … },
    { … }
  ],
  "rating_categories": [
    { … }
  ]
}

Vouchers

A collection of endpoints to use at the end of the booking flow to retrieve reserved tickets and vouchers.

Operations

Webhooks

A collection of webhook requests that Musement's API can make to a partner's service.

Webhooks

Activities

A collection of deprecated endpoints for activities.

Operations

Carts

A collection of deprecated endpoints for carts.

Operations

Cities

A collection of deprecated endpoints for cities.

Operations

Verticals

Verticals are a type of macro category which group various parts of the catalog together based on similar characteristics.

They are considered deprecated.

Operations

Cities

A collection of endpoints for cities that were removed from the API.

Operations

Countries

A collection of endpoints for countries that were removed from the API.

Operations

Events

A collection of endpoints for events, an older term for activities, that were removed from the API.

Operations

Misc

A collection of various endpoints that were removed from the API.

Operations

Venues

A collection of endpoints for venues that were removed from the API.

Operations
Copyright © TUI Musement. All rights reserved.