Review API v3
KK (Unlicensed)
David Maicher
Björn Östberg
You will need an API key for authorizing your requests. You can request an API key from our Customer Support team.
The API key must be passed in an HTTP header named X-CA-AUTH when requesting any of the API endpoints.
API endpoints
Getting the review information is a 3-step process, with two optional endpoints (review-subjects in the case when the account has multiple review configs linked to one API Key).
[Optional] Get Review Subjects- to be used in case of multi-location account. Depending on the API key, an account can have multiple review subjects. The API returns a unique identifier for a location.
[Optional] Get Survey questionnaires- to be used in case of multiple questionnaires for a single review subject. The API returns a unique identifier for the questionnaire and relates a particular questionnaire to the review subject.
Reviews- The API returns the review information generated by the CA surveys.
Get Review Subjects
GET /review-subjects
Share the list of review subjects linked to the API Key
Parameters
Name | Default value | Description |
|---|
Name | Default value | Description |
|---|---|---|
| 1 | Integer greater than or equal to 1. |
| 20 | The number of items shown per page. Maximum value allowed is 50. |
Examples
Shell
$ curl --header "X-CA-AUTH: <YOUR_API_KEY_HERE>" https://api.customer-alliance.com/review-subjectsResponse
{
"pagination": {
"current_page": 1,
"total_pages": 1,
"total_items": 2
},
"items": [
{
"name": "Hotel John",
"hash": "ASDFasd4334rsadvvasd232d23d2"
},
{
"name": "Hotel Wick",
"hash": "YBJFFasd4334rsadvvasd232d23d"
}
]
}Get Survey questionnaires
GET /questionnaires
Allows access to survey questionnaires (receive a list of feedback questionnaires).
Parameters
Name | Default value | Description |
|---|
Name | Default value | Description |
|---|---|---|
| 1 | Integer greater than or equal to 1. |
| 20 | The number of items shown per page. Maximum value allowed is 50. |
| -- | Can pass multiple review_subject.hash in case multiple review subjects are linked to the API key |
Examples
Shell
$ curl --header "X-CA-AUTH: <YOUR_API_KEY_HERE>" https://api.customer-alliance.com/questionnairesResponse
[
{
"pagination":{
"current_page":1,
"total_pages":1,
"total_items":2
},
{
"id":699083,
"name":"Breakfast Survey",
"enabled":true,
"review_subject":
{
"hash":"asdlfh345345ASDF23svcsdvsd",
"name":"Hotel John"
}
},
{
"id":699093,
"name":"During Stay Feedback",
"enabled":false,
"review_subject":
{
"hash":"YBJFFasd4334rsadvvasd232d23d",
"name":"Hotel Wick"
}
}
]Reviews
GET /reviews/v3
API allows access to the data collected via Customer Alliance review questionnaires. This may include information such as:
Review content
Average rating
Individual rating
Text responses including the sub-questions and conditional questions
Information about the guest leaving the review
Parameters
All parameters are optional.
Name | Default value | Description |
|---|
Name | Default value | Description |
|---|---|---|
| -- | A required parameter with Interger value. Note: this parameter may be included multiple times, e.g. |
| 1 | Integer greater than or equal to 1. |
| -- | Date in the YYYY-MM-DD format. |
| -- | Date in the YYYY-MM-DD format. |
| -- | Integer between 0 and 100. |
| -- | Integer between 0 and 100. |
| 0 | Either 1 or 0. 0 means that the |
| 0 | Either 1 or 0. 0 means that the |
| -- | Either 1 or 0. |
| 20 | The number of reviews shown per page. Maximum value allowed is 50. |
| -- | To show the feedbacks submitted for the selected language. Values can be one of these language codes: de, en, es, fr, nl, cs, da, hu, it, pl, pt, ru, sr, sv, ar, zh, ja, fi, no |
| en | Changes the language used to show the question labels. Must be a valid ISO 3166-1 alpha-2 language code. For example: 'en' for English, 'fr' for French. |
| -- | Can pass multiple review_subject.hash in case multiple review subjects are linked to the API key |
Examples
Shell
curl --header "X-CA-AUTH: <YOUR_API_KEY_HERE>" https://api.customer-alliance.com/reviews/v3?page=1&start=2021-01-01&end=2021-01-13&fromRating=0&toRating=100&categoryRatings=1&published=0&limit=20Response
{
"pagination": {
"current_page": 1,
"total_pages": 1,
"total_items": 1
},
"items": [
{
"id": 52749453,
"language": "en",
"created_date": "2021-02-18 12:25:52",
"author": {
"name": "John",
"email": "john@email.com"
},
"meta": {
"traveller_type": null,
"age": null,
"arrival_date": "2021-02-01",
"departure_date": "2021-02-28",
"attributes": {
"room_number": "666",
"pms_reservation_id": "1234",
"some_custom_attribute": "some_value"
}
},
"questionnaire": {
"id": 699083,
"name": "Breakfast Survey"
},
"review_subject": {
"hash": "asdlfh345345ASDF23svcsdvsd",
"name": "Hotel John"
},
"overall_rating": {
"scaled": 5,
"rating_scale": {
"min": 1,
"max": 5
},
"normalized": 100
},
"overall_comment": "some nice text comment",
"reply": "thank you for the review!",
"category_ratings": [
{
"rating_category": "service",
"rating": {
"scaled": 5,
"rating_scale": {
"min": 1,
"max": 5
},
"normalized": 100
}
},
{
"rating_category": "food_and_beverages",
"rating": {
"scaled": 3.5,
"rating_scale": {
"min": 1,
"max": 5
},
"normalized": 70
}
}
],
"question_answers": [
{
"question": {
"id": 11918603,
"type": "csat",
"label": "Service",
"rating_category": "service",
"rating_scale": {
"min": 1,
"max": 5
}
},
"answer": {
"rating": 5,
"text": null
},
"sub_question_answers": []
},
{
"question": {
"id": 11918603,
"type": "ces",
"label": "We made it easy for you to check-in",
"rating_category": "ces_checkin",
"rating_scale": {
"min": 1,
"max": 7
}
},
"answer": {
"rating": 5,
"text": null
},
"sub_question_answers": []
},
{
"question": {
"id": 11918613,
"type": "csat",
"label": "Buffet / Menu selection",
"rating_category": "food_and_beverages",
"rating_scale": {
"min": 1,
"max": 5
}
},
"answer": {
"rating": 4,
"text": null
},
"sub_question_answers": []
},
{
"question": {
"id": 11918623,
"type": "csat",
"label": "Quality of food",
"rating_category": "quality_of_food",
"rating_scale": {
"min": 1,
"max": 5
}
},
"answer": {
"rating": 5,
"text": null
},
"sub_question_answers": []
},
{
"question": {
"id": 11918633,
"type": "csat",
"label": "Selection of beverages",
"rating_category": "food_and_beverages",
"rating_scale": {
"min": 1,
"max": 5
}
},
"answer": {
"rating": 3,
"text": null
},
"sub_question_answers": []
},
{
"question": {
"id": 11918643,
"type": "text",
"label": "How would you describe your overall experience?"
},
"answer": {
"text": "All in all it was almost perfect, except there were no apple juice."
},
"sub_question_answers": []
},
{
"question": {
"id": 11918653,
"type": "choice",
"label": "Are you a guest of the hotel?"
},
"answer": {
"choices": [
{
"label": "Yes"
}
]
},
"sub_question_answers": [
{
"question": {
"id": 11918663,
"type": "text",
"label": "Your room number"
},
"answer": {
"text": "119"
},
"sub_question_answers": []
}
]
},
{
"question": {
"id": 11918673,
"type": "text",
"label": "Your email address"
},
"answer": {
"text": "john@email.com"
},
"sub_question_answers": []
},
{
"question": {
"id": 26,
"type": "nps",
"label": "How likely are you to recommend us to a friend or colleague?",
"rating_scale": {
"min": 0,
"max": 10
}
},
"answer": {
"rating": 6
},
"sub_question_answers": []
}
]
}
]
}