Reviews

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

Search reviews for activity

Request
path Parameters
activityUuid
required
string <uuid>

The UUID of the activity.

query Parameters
limit
integer [ 1 .. 500 ]
Default: 6

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

page
integer >= 1
Default: 1

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

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_by
string
Default: NEWEST

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.
Enum: HIGHEST-RATED LOWEST-RATED NEWEST PREFERRED-LANGUAGE
traveler_type_in[]
Array of strings (Traveler type)

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
header Parameters
Accept-Language
string (Language code)
Default: en-US

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

X-Musement-Application
string (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-Version
string^[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.
Responses
200

Reviews for activity

403

Forbidden: activity is not accessible to partners

404

Not found: activity with UUID does not exist

default

Error

get/activities/{activityUuid}/reviews
Request samples
curl -i -X GET \
  'https://sandbox.musement.com/api/v3/activities/{activityUuid}/reviews?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'
Response samples
application/json
[
  • {
    }
]

Add review to activity

Request
path Parameters
activityUuid
required
string <uuid>

The UUID of the activity.

Request Body schema: application/json
age
integer

The customer's age.

comment
string

The customer's written review of their experience.

is_public
boolean
Default: false

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.

locale
string^[a-z]{1,8}(?:-[a-zA-Z0-9]{1,8})?

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

order_item_uuid
required
string <uuid>

The Musement order item UUID that the review is for.

provider
required
string

The name of the service providing the review data.

provider_id
required
string

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

public_username
string

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

rating_value
required
integer

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

rating_scale
required
string (Rating scale) ^\d{1,3}\.{2}\d{1,3}$

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

traveler_type
string (Traveler type)

The customer's traveler type.

Enum: ALONE AS-A-COUPLE WITH-FAMILY WITH-FRIENDS
date
required
string <date-time>

The date and time the review was written.

Array of objects (Rating category breakdown)

A breakdown of the rating by category.

Responses
201

Created: review successfully submitted

400

Bad request: there are errors in the request

401

Unauthorized: token is not valid

403

Forbidden: activity is not accessible to partners

404

Not found: activity with UUID does not exist

409

Conflict: review already exists for the activity's order item

503

Service unavailable

post/activities/{activityUuid}/reviews
Request samples
application/json
{
  • "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": [
    ],
  • "rating_scale": "1..5",
  • "rating_value": 4,
  • "traveler_type": "WITH-FAMILY"
}
Response samples
application/json
{
  • "code": "0",
  • "message": "Parameter \"page\" of value \"-1\" violated a constraint \"Parameter 'page' value, does not match requirements '\\\\d+'\""
}

Get review statistics for activity

Request
path Parameters
activityUuid
required
string <uuid>

The UUID of the activity.

header Parameters
Accept-Language
string (Language code)
Default: en-US

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

X-Musement-Application
string (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-Version
string^[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.
Responses
200

Review statistics for activity

401

Unauthorized: token is not valid

403

Forbidden: activity is not accessible to partners

404

Not found: activity with UUID does not exist

503

Service unavailable

get/activities/{activityUuid}/reviews/statistics
Request samples
curl -i -X GET \
  'https://sandbox.musement.com/api/v3/activities/{activityUuid}/reviews/statistics' \
  -H 'Accept-Language: en-US' \
  -H 'X-Musement-Application: string' \
  -H 'X-Musement-Version: 3.4.0'
Response samples
application/json
{
  • "reviews_number": 700,
  • "overall_rating": 7.65,
  • "reviews_per_rating": [
    ],
  • "rating_categories": [
    ]
}
➔ Next to Vouchers