Page Comparison

Info

_{You will need an}_{API key}_{for authorizing your requests. You can request an API key from our Customer Care team.}
_{The API key must be passed in an HTTP header named}_X-CA-AUTH_{when requesting any of the API endpoints.}

^{The default endpoint is}^{https://api.customer-alliance.com}^{, if not stated differently.}

...

Expand

title	GET /reviews/v2/ca.json

GET /reviews/v2/ca.json

Info
The new version of the Review API is available here

API allows access to the data that was collected via Customer Alliance review questionnaires. This may include information such as:

Review content;
Average rating;
Information about the guest leaving the review.

Parameters

All parameters are optional.

Name	Default value	Description
`page`	1	Integer greater than or equal to 1. The number of reviews per request is limited to the value of limit, this parameter is responsible for pagination.
`start`	180 days before the end date	Date in the YYYY-MM-DD format. Use this to select the earliest review you wish to see.
`end`	today	Date in the YYYY-MM-DD format. Must not be earlier than the value of start. Use this to select the latest review you wish to see.
`category`	'average'	A valid review rating category, also known as a 'criteria'. A list of categories can be seen in the response of this endpoint without supplying the parameters. Use this to filter reviews by subcategory, e.g, ‘price’, ‘breakfast’, etc.
`fromRating`	0	Integer between 0 and 100. The lowest review score you wish included in the result set.
`toRating`	100	Integer between 0 and 100. The highest review score you wish included in the result set.
`commentStatus`	no value	Must be one of: `commented` `not_commented` `drafted` Filters reviews as to whether they have been commented, not commented or have had a comment drafted.
`categoryRatings`	0	Either 1 or 0.
`published`	0	Either 1 or 0. If the published parameter is added with value 1. The results will only contain reviews that have been published (public reviews).
`limit`	20	The number of reviews shown per page.

Examples

Shell

Code Block

language	bash

curl --header "X-CA-AUTH: <YOUR_API_KEY_HERE>" https://api.customer-alliance.com/reviews/v2/ca.json?page=1&start=2021-01-01&end=2021-01-13&fromRating=0&toRating=100&categoryRatings=1&published=0&limit=20

Response

Code Block

language	json

{
    "totalCount": 1,
    "reviews": [
        {
            "hotel_name": "Restaurant The Eagle",
            "review_id": "careview52326183",
            "review_source": "customeralliance",
            "average_rating_normalized": "90.0000",
            "average_rating": "4.5000",
            "reviewer_type": null,
            "language": "en",
            "published": false,
            "reviewer_comment": "It was a nice experience, definitely worth coming again",
            "reviewer_comment_positive": "",
            "reviewer_comment_negative": "",
            "arrival_date": "2021-01-09",
            "departure_date": "2021-01-09",
            "review_date": "2021-01-12 09:07:46",
            "author": "Customer Alliance u.",
            "category_ratings": {
                "price": {
                    "rating": 80,
                    "label": "Price",
                    "comment": null
                },
                "service": {
                    "rating": 100,
                    "label": "Service",
                    "comment": null
                },
                "FoodQuality": {
                    "rating": 100,
                    "label": "Quality of Food",
                    "comment": null
                },
                "Atmosphere": {
                    "rating": 80,
                    "label": "Atmosphere",
                    "comment": null
                }
            },
            "nps": 9,
            "brand_nps": null,
            "age": 30,
            "hotelier_comment": null
        }
    ]
}

Expand

title	GET /reviews/v2/all.json

GET /reviews/v2/all.json

Review data collected via Customer Alliance questionnaires and reviews from external portals, such as Google, Facebook, or Tripadvisor.

Parameters

All parameters are optional.

Name	Default value	Description
`page`	1	Integer greater than or equal to 1. The number of reviews per request is limited to the value of limit, this parameter is responsible for pagination.
`start`	180 days before the end date	Date in the YYYY-MM-DD format. Use this to select the earliest review you wish to see.
`end`	today	Date in the YYYY-MM-DD format. Must not be earlier than the value of start. Use this to select the latest review you wish to see.
`fromRating`	0	Integer between 0 and 100. The lowest review score you wish included in the result set.
`toRating`	100	Integer between 0 and 100. The highest review score you wish included in the result set.
`commentStatus`	no value	Must be one of: `commented` `not_commented` `drafted` Filters reviews as to whether they have been commented, not commented or have had a comment drafted.
`published`	0	Either 1 or 0. If the published parameter is added with value 1. The results will only contain reviews that have been published (public reviews).
`limit`	20	The number of reviews shown per page.

Examples

Shell

Code Block

language	bash

curl --header "X-CA-AUTH: <YOUR_API_KEY_HERE>" https://api.customer-alliance.com/reviews/v2/all.json?page=1&start=2021-01-01&end=2021-01-12&fromRating=80&toRating=100

Response

Code Block

{
    "totalCount": 3,
    "reviews": [
        {
            "hotel_name": "Some hotel",
            "review_id": "careview52326100",
            "review_source": "customeralliance",
            "average_rating_normalized": "90.0000",
            "average_rating": "4.5000",
            "reviewer_type": null,
            "language": "en",
            "published": false,
            "reviewer_comment": "It was a nice experience, definitely worth coming again",
            "reviewer_comment_positive": "",
            "reviewer_comment_negative": "",
            "arrival_date": "2021-01-09",
            "departure_date": "2021-01-09",
            "review_date": "2021-01-12 09:07:46",
            "author": "Customer Alliance u.",
            "nps": 9,
            "brand_nps": null,
            "hotelier_comment": null
        },
        {
            "hotel_name": "Some hotel",
            "review_id": "google339501_37010a286cbf5e50ddcc89a69f206eeb7020020",
            "review_source": "google",
            "average_rating_normalized": "80.0000",
            "average_rating": "4.0000",
            "review_date": "2021-01-06 21:57:24",
            "author": "Anthony B.",
            "hotelier_comment": null
        },
        {
            "hotel_name": "Some hotel ",
            "review_id": "google339501_06ce0d554b82b1084d464cd5d1038b0078c0001",
            "review_source": "google",
            "average_rating_normalized": "100.0000",
            "average_rating": "5.0000",
            "language": "en",
            "review_date": "2021-01-02 12:49:18",
            "author": "Marie O.",
            "hotelier_comment": null
        }
    ]
}

...

Expand

title	GET /statistics/v1/categories.json

GET /statistics/v1/categories.json

Shows the rating categories currently used for aggregation on your API key.
The data refreshes every 2 hours.

Parameters

All parameters are optional.

Name	Default value	Description
`review_subject`	First created review subject	It refers to Review Config's hash value. By default access key has access to 100 review subjects, by using "review_subject" parameter you can specify for which subject you would like to retrieve data. Must be a value from 'hash' field, looks like: e3600bf31c28b60e

Examples

Shell

Code Block

language	bash

curl --header "X-CA-AUTH: YOUR_API_KEY" https://api.customer-alliance.com/statistics/v1/categories.json

Response

Note
The result here will vary depending on the categories configured for your business and the questions marked as 'Show in Statistics' or 'Public' in your questionnaire.

Code Block

language	json

[
    "Amenities",
    "Apartment",
    "Entertainment",
    "Hospitality",
    "Reception",
    "bar",
    "beach",
    "break",
    "childcare",
    "clean",
    "comfort",
    "conference",
    "food",
    "location",
    "pool",
    "price",
    "private_beach",
    "restaurant",
    "room",
    "service",
    "sport",
    "value_for_money",
    "vibe",
    "wellness",
    "wifi"
]

Expand

title	GET /statistics/v2/general/recent.json

GET /statistics/v2/general/recent.json

Shows statistics for rating categories, including the overall category, for all reviews authored in the past 6 months.

Parameters

All parameters are optional.

Name

Default value

Description

_locale

en

Changes the language used to show the category labels.

Must be a valid ISO 3166-1 alpha-2 language code. For example: 'en' for English, 'fr' for French.

review_subject

First created review subject

It refers to Review Config's hash value. By default access key has access to 100 review subjects, by using "review_subject" parameter you can specify for which subject you would like to retrieve data.
Must be a value from 'hash' field, looks like: e3600bf31c28b60e

published

no value

Possible values: either 0 or 1.

If set to 1 will return only data about published reviews (public reviews).

Examples

Shell

Code Block

language	bash

curl --header "X-CA-AUTH: YOUR_API_KEY" https://api.customer-alliance.com/statistics/v2/general/recent.json

Response

Code Block

{
    "start_date": "2020-08-17",
    "end_date": "2021-02-17",
    "comment_rate": 30.798478707224334,
    "category_statistics": {
        "overall": {
            "label": "Overall",
            "average_rating": 90.51546391746737,
            "review_count": 582,
            "positive_review_count": 528,
            "neutral_review_count": 49,
            "negative_review_count": 5
        },
        "clean": {
            "label": "Cleanliness",
            "average_rating": 96.0,
            "review_count": 5,
            "positive_review_count": 5,
            "neutral_review_count": 0,
            "negative_review_count": 0
        },
        "comfort": {
            "label": "Comfort",
            "average_rating": 86.66666666666667,
            "review_count": 3,
            "positive_review_count": 3,
            "neutral_review_count": 0,
            "negative_review_count": 0
        },
        "food": {
            "label": "Food",
            "average_rating": 0.0,
            "review_count": 0,
            "positive_review_count": 0,
            "neutral_review_count": 0,
            "negative_review_count": 0
        },
        "location": {
            "label": "Location",
            "average_rating": 100.0,
            "review_count": 3,
            "positive_review_count": 3,
            "neutral_review_count": 0,
            "negative_review_count": 0
        },
        "price": {
            "label": "Price",
            "average_rating": 100.0,
            "review_count": 4,
            "positive_review_count": 4,
            "neutral_review_count": 0,
            "negative_review_count": 0
        },
        "restaurant": {
            "label": "Restaurant",
            "average_rating": 0.0,
            "review_count": 0,
            "positive_review_count": 0,
            "neutral_review_count": 0,
            "negative_review_count": 0
        },
        "room": {
            "label": "Room",
            "average_rating": 88.0,
            "review_count": 5,
            "positive_review_count": 4,
            "neutral_review_count": 1,
            "negative_review_count": 0
        },
        "service": {
            "label": "Service",
            "average_rating": 88.0,
            "review_count": 5,
            "positive_review_count": 4,
            "neutral_review_count": 1,
            "negative_review_count": 0
        }
    }
}

Expand

title	GET /statistics/v2/general/total.json

GET /statistics/v2/general/total.json

Shows statistics for rating categories, including the overall category, for all known reviews.

If the parameter 'review_subject' is not set, the statistics will be shown for the first created review subject of the api-key.

Parameters

All parameters are optional.

Name

Default value

Description

_locale

en

Changes the language used to show the category labels.

Must be a valid ISO 3166-1 alpha-2 language code. For example: 'en' for English, 'fr' for French.

review_subject

first created review subject

It refers to Review Config's hash value. By default access key has access to 100 review subjects, by using "review_subject" parameter you can specify for which subject you would like to retrieve data.
Must be a value from 'hash' field, looks like: e3600bf31c28b60e

published

no value

Possible values: either 0 or 1.

If set to 1 will return only data about published reviews (public reviews).

Examples

Shell

Code Block

language	bash

curl --header "X-CA-AUTH: YOUR_API_KEY" https://api.customer-alliance.com/statistics/v2/general/total.json

Response

Code Block

{
    "start_date": null,
    "end_date": null,
    "comment_rate": 11.12612972972973,
    "category_statistics": {
        "overall": {
            "label": "Overall",
            "average_rating": 88.03647184495651,
            "review_count": 6553,
            "positive_review_count": 6495,
            "neutral_review_count": 839,
            "negative_review_count": 64
        },
        "clean": {
            "label": "Cleanliness",
            "average_rating": 89.97303634044549,
            "review_count": 5118,
            "positive_review_count": 66,
            "neutral_review_count": 3,
            "negative_review_count": 0
        },
        "food": {
            "label": "Food",
            "average_rating": 0.0,
            "review_count": 0,
            "positive_review_count": 0,
            "neutral_review_count": 0,
            "negative_review_count": 0
        },
        "location": {
            "label": "Location",
            "average_rating": 83.19193706981318,
            "review_count": 5085,
            "positive_review_count": 46,
            "neutral_review_count": 13,
            "negative_review_count": 0
        },
        "price": {
            "label": "Price",
            "average_rating": 89.97183098591549,
            "review_count": 4828,
            "positive_review_count": 54,
            "neutral_review_count": 3,
            "negative_review_count": 0
        },
        "restaurant": {
            "label": "Restaurant",
            "average_rating": 90.0,
            "review_count": 2,
            "positive_review_count": 0,
            "neutral_review_count": 0,
            "negative_review_count": 0
        },
        "service": {
            "label": "Service",
            "average_rating": 89.07062144180792,
            "review_count": 354,
            "positive_review_count": 92,
            "neutral_review_count": 11,
            "negative_review_count": 3
        }
    }
}

Expand

title	GET /statistics/v2/portal-overview.json

GET /statistics/v2/portal-overview.json

Statistics for all known reviews. Aggregated for overall and broken down by review portal (e.g. Booking.com, Google, Facebook, ...).

Parameters

All parameters are optional.

Name	Default value	Description
`start`	180 days before the end date	To select the earliest review you wish to see. A date of format yyyy-mm-dd, must be before the end date.
`end`	today	To select the latest review you wish to see. A date of format yyyy-mm-dd, must be after the start date.
`category`	average	To filter reviews by subcategory, e.g. price, service, etc. Must be an available category (to get all the available categories check out the api '`/statistics/v1/categories.json`').
`review_subject`	first created review subject	It refers to Review Config's hash value. By default access key has access to 100 review subjects, by using "review_subject" parameter you can specify for which subject you would like to retrieve data. Must be a value from 'hash' field, looks like: e3600bf31c28b60e
`published`	no value	Possible values: either 0 or 1. If set to 1 will return only data about published reviews (public reviews).

Examples

Shell

Code Block

language	bash

curl --header "X-CA-AUTH: YOUR_API_KEY" https://api.customer-alliance.com/statistics/v2/portal-overview.json

Response

Code Block

{
    "reviewCount": 491,
    "averageRating": 90.32993890011609,
    "commentRate": 29.14798206278027,
    "reviewCountPositive": 441,
    "reviewCountNeutral": 44,
    "reviewCountNegative": 6,
    "portalStats": {
        "customeralliance": {
            "reviewCount": 2,
            "reviewCountPositive": 2,
            "reviewCountNeutral": 0,
            "reviewCountNegative": 0,
            "averageRating": 80,
            "commentRate": null
        },
        "booking": {
            "reviewCount": 414,
            "reviewCountPositive": 373,
            "reviewCountNeutral": 37,
            "reviewCountNegative": 4,
            "averageRating": 90.56038647332849,
            "commentRate": 32.432432432432435
        },        
        "google": {
            "reviewCount": 61,
            "reviewCountPositive": 55,
            "reviewCountNeutral": 4,
            "reviewCountNegative": 2,
            "averageRating": 90.49180327867212,
            "commentRate": 11.475409836065573
        },
        "hotelscom": {
            "reviewCount": 3,
            "reviewCountPositive": 3,
            "reviewCountNeutral": 0,
            "reviewCountNegative": 0,
            "averageRating": 80,
            "commentRate": 100
        },
        "hrs": {
            "reviewCount": 0,
            "reviewCountPositive": 0,
            "reviewCountNeutral": 0,
            "reviewCountNegative": 0,
            "averageRating": 0,
            "commentRate": null
        },
        "tripadvisor": {
            "reviewCount": 11,
            "reviewCountPositive": 8,
            "reviewCountNeutral": 3,
            "reviewCountNegative": 0,
            "averageRating": 85.45454545454545,
            "commentRate": 63.63636363636363
        },
        "tui": {
            "reviewCount": 0,
            "reviewCountPositive": 0,
            "reviewCountNeutral": 0,
            "reviewCountNegative": 0,
            "averageRating": 0,
            "commentRate": null
        }
    }
}

Expand

title	GET /statistics/v1/reviews-over-time.json

GET /statistics/v1/reviews-over-time.json

Statistics for all known reviews. Aggregated weekly.

Parameters

All parameters are optional.

Name	Default value	Description
`start`	180 days before the end date	To select the earliest review you wish to see. A date of format yyyy-mm-dd, must be before the end date.
`end`	today	To select the latest review you wish to see. A date of format yyyy-mm-dd, must be after the start date.
`category`	average	To filter reviews by subcategory, e.g. price, service, etc. Must be an available category (to get all the available categories check out the api '`/statistics/v1/categories.json`').
`review_subject`	first created review subject	It refers to Review Config's hash value. By default access key has access to 100 review subjects, by using "review_subject" parameter you can specify for which subject you would like to retrieve data. Must be a value from 'hash' field, looks like: e3600bf31c28b60e
`forced_interval`	depending on time range	Possible value: `months`. To force the statistics to be grouped by months. If parameter is not given, then certain rules are applied depending on the time range (see table below).

The time intervals used for grouping are determined by these rules:

Δ = difference in days between start & end	Interval	Description
31 days < Δ <= 182 days	weekly	If parameter `forced_interval=months` is not given, then values by default will be grouped weekly.
182 days < Δ <= 720 days	monthly	Values will be always grouped monthly.
Δ <= 31 days	daily	If parameter `forced_interval=months` is not given, then values by default will be grouped daily.
Δ > 720 days	yearly	If parameter `forced_interval=months` is not given, then values by default will be grouped yearly.

Examples

Shell

Code Block

language	bash

curl --header "X-CA-AUTH: YOUR_API_KEY" https://api.customer-alliance.com/statistics/v1/reviews-over-time.json

Response

Code Block

{
    "Hotel XYZ": {
        "8 / 2020": {
            "review_count": 54,
            "positive_reviews": 49,
            "neutral_reviews": 5,
            "negative_reviews": 0
        },
        "9 / 2020": {
            "review_count": 144,
            "positive_reviews": 129,
            "neutral_reviews": 13,
            "negative_reviews": 2
        },
        "10 / 2020": {
            "review_count": 88,
            "positive_reviews": 83,
            "neutral_reviews": 4,
            "negative_reviews": 1
        },
        "11 / 2020": {
            "review_count": 77,
            "positive_reviews": 70,
            "neutral_reviews": 7,
            "negative_reviews": 0
        },
        "12 / 2020": {
            "review_count": 69,
            "positive_reviews": 63,
            "neutral_reviews": 5,
            "negative_reviews": 1
        },
        "1 / 2021": {
            "review_count": 64,
            "positive_reviews": 52,
            "neutral_reviews": 12,
            "negative_reviews": 0
        },
        "2 / 2021": {
            "review_count": 55,
            "positive_reviews": 51,
            "neutral_reviews": 3,
            "negative_reviews": 1
        }
    }
}

...

Expand

title	GET /feedback/v2/questionnaires.json

GET /feedback/v2/questionnaires.json

Allows access feedback questionnaires (receive list of feedback questionnaires).

Parameters

This endpoint has no parameters.

Examples

Shell

Code Block

language	bash

$ curl --header "X-CA-AUTH: <YOUR_API_KEY_HERE>" https://api.customer-alliance.com/feedback/v2/questionnaires.json

Response

Code Block
[ { "id": 699083, "name": "Breakfast Survey" }, { "id": 699093, "name": "During Stay Feedback" } ]

Expand

title	GET /feedback/v2/stream.json

GET /feedback/v2/stream.json

Allows access to all of the feedbacks that were gathered.

Parameters

Name	Default value	Description
`questionnaireIds`	no value	A required parameter with Interger value. Note: this parameter may be included multiple times, e.g. questionnaireIds=1000&questionnaireIds=1001
`page`	1	Integer greater than or equal to 1. The number of feedback items per request is limited to the value of limit, this parameter is responsible for pagination.
`start`	180 days before the end date	Date in the YYYY-MM-DD format. Use this to select the earliest feedback you wish to see.
`end`	today	Date in the YYYY-MM-DD format. Must not be earlier than the start date. Use this to select the latest feedback you wish to see.
`limit`	20	Integer between 1 and 50. Used to limit the number of results per page.
`commentStatus`	no value	Must be one of: `commented` `not_commented` `drafted` Filters feedbacks as to whether they have been commented, not commented or have had a comment drafted.
`language`	no value	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
`_locale`	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.

Examples

Shell

Code Block

language	bash

$ curl --header "X-CA-AUTH: <YOUR_API_KEY_HERE>" https://api.customer-alliance.com/feedback/v2/stream.json?questionnaireIds=699083

Response

Code Block

{
    "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",
                "age": null
            },
            "meta": {
                "traveller_type": null,
                "room_number": null,
                "arrival_date": "2021-02-01",
                "departure_date": "2021-02-28"
            },
            "questionnaire": {
                "id": 699083,
                "name": "Breakfast Survey"
            },
            "question_answers": [
                {
                    "question": {
                        "id": 11918603,
                        "type": "rating",
                        "label": "Service"
                    },
                    "answer": {
                        "rating": 5,
                        "text": null
                    },
                    "sub_question_answers": []
                },
                {
                    "question": {
                        "id": 11918613,
                        "type": "rating",
                        "label": "Buffet / Menu selection"
                    },
                    "answer": {
                        "rating": 4,
                        "text": null
                    },
                    "sub_question_answers": []
                },
                {
                    "question": {
                        "id": 11918623,
                        "type": "rating",
                        "label": "Quality of food"
                    },
                    "answer": {
                        "rating": 5,
                        "text": null
                    },
                    "sub_question_answers": []
                },
                {
                    "question": {
                        "id": 11918633,
                        "type": "rating",
                        "label": "Selection of beverages"
                    },
                    "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": []
                }
            ],
            "comment": null,
            "rating_scale": {
                "min": 1,
                "max": 5
            }
        }
    ]
}

...

Expand

title	POST /account/{googlePlaceId}

POST /account/{googlePlaceId}

This API is to be used by a partner to create a monitoring account for one of its customers. A monitoring account is a Customer Alliance account created for the purpose of monitoring a customer's online reviews on the public review portals.

When a monitoring account is created via this API the partner can retrieve an API Key to get access to the customer data of the created monitoring account. Access to the customer data is granted via one of our APIs (JSON or iFrame APIs).

There is a limit on creating monitoring accounts using this API: 50 per day per partner. Reaching the mentioned limit returns a 429 HTTP error in the API request.

Parameters

Name

Default value

Description

{googlePlaceId}

no value

Google place id.

This is the link to the Google Places API documentation, where Google Places ID can be retrieved: https://developers.google.com/maps/documentation/javascript/examples/places-placeid-finder

Examples

Shell

Code Block

language	bash

curl --location --request POST 'https://api.customer-alliance.com/account/{googlePlaceId}' \
--header 'X-CA-AUTH: <YOUR_API_KEY_HERE>'

Below is the JSON structure you can expect from the POST endpoint:
https://api.customer-alliance.com/account/{googlePlaceId}
Response

Code Block

{
  'result': 'ok',
  'account': {
    'id': 1,
    'name': 'TEST HOTEL BERLIN',
    'address': '118 Ullsteinstr, 10719 Berlin, DE',
    'website': 'http://www.test-hotel.de/',
    'type': 'Hotel',
    'api_key': '9891229a2ef309a123456de0e846ce8c30f8'
  }
}

...

Expand

title	POST /api/{AccessKey}/{ReviewSubject}

POST /api/{AccessKey}/{ReviewSubject}

With this API you can seamlessly add guest/customer data to the Customer Alliance product back-end.

Info
To access the API, you will need: AccessKey and ReviewSubject (hash value of the Review Config) - both should be requested from Customer Support team. URL endpoint is: https://interfaces.customer-alliance.com/api/{AccessKey}/{ReviewSubject}

Our service requires SSL transport encryption. We only support TLS 1.2+. TLS 1.0, 1.1 and SSL v2, v3 are no longer supported due to massive security vulnerabilities.

Testing

For testing purposes, you can request test access credentials that are connected to a test hotel. The added guests are NOT treated as real guests, and therefore will NOT be sent emails requesting a review.

Other than that the API behaves and responds normally.

Specification for POST

The guest data can be sent to our server using a POST request with JSON data within the request body. The following content type should be set on the request:

'Content-Type: application/json; charset=utf-8'

Expected structure

The request body has to match the following structure:

Code Block

language	json

[
  {
    "id": "1",
    "reservation_id": "0123ABC",
    "name": "Mustermann",
    "gender": "m",
    "email": "max@mustermann.de",
    "language": "de",
    "arrival_date": "2021-07-01",
    "departure_date": "2021-07-08",
    "phone_number": "+4915777777777"
  },
  {
    "id": "2",
    "name": "M\u00fcller",
    "gender": "f",
    "email": "lieschen@mueller.de",
    "language": "de",
    "departure_date": "2021-07-08"
  },
  {
    "id": "3",
    "reservation_id": "0123ABCEF",
    "name": "Mustermann",
    "gender": "m",
    "email": "otto@mustermann.de",
    "language": "de",
    "departure_date": "2021-07-08",
    "cancelled": true
  }
]

The request body consists of a JSON array that can contain multiple guests and so it is possible to send multiple guests within one request.

Note
Our servers expect any unicode non-ASCII characters in the json payload to be escaped. So for example the name "Müller" has to be provided as "M\u00fcller"

Note
The limit for the number of guests inside one request is 1000. A 400 “Bad Request” error might be returned if this limit is exceeded.

Note

The API is subject to rate-limiting and allows

2 10 requests per second
10 60 requests per minute
200 250 requests per hour

Attributes

Name	Required	Description
`id`	yes	Unique ID of the guest in context of the current request. This could be the same as the reservation ID. This ID is used to distinguish the guests in the event of an error during transfer. More about this within the "Errors" table below. Also, it is stored with relation to the review and is displayed in the external review API CA & Ext. Review Data (JSON), API Documentation.
`name`	yes	The last name of the guest
`email`	yes	Email address to which the invitation is to be sent.
`gender`	yes	Gender is required for the guest salutation Valid values are: m (male), f (female), fam (family). na (unknown/neutral)
`language`	yes	Language of the guest in ISO 639-1 format de, en, fr, es, it, nl, cs, pt, ru, hu, da, pl, etc.
`arrival_date`	no	Arrival date of the guest, must be provided in YYYY-MM-DD format. The arrival date of the guest can be given optionally.
`departure_date`	yes	Departure date of the guest Must be provided in YYYY-MM-DD format At most 180 days in the past or future, no more
`phone_number`	no	The phone number of the guest can be given optionally. The phone number has to follow the E.164 recommendation. https://en.wikipedia.org/wiki/E.164.
`cancelled`	yes	Guest cancellation status as boolean field. If a true value is given, then the guest is marked as cancelled and any further communication with the guest is stopped. It's recommended to update the guest cancellation status at least once a day to ensure a fluid guest communication flow.
`reservation_id`	yes	Unique ID of the reservation/booking by the guest in a given hotel. This field is mandatory if the arrival_date given is in the future.
`guest_profile_id`	no	Unique ID of the guest within a given hotel. This usually corresponds to the guest profile ID within a given hotel. This field can be a string.
`room_number`	no	The room number where the guest stayed. This field can be a string.
`room_category`	no	The category of the room where the guest stayed, e.g. suite, single, double-room. This field can be a string.

Server Responses

The result of the request is shown in the response of our server.

Status codes for responses

Status Code	Description
`200 OK`	Request has been accepted successfully. Body of the response gives further information
`403 Forbidden`	Not authenticated, combination of Review Subject and Access Key invalid [no guests imported]
`400 Bad Request`	Invalid format of the request (e.g. missing parameter or invalid JSON) [no guests imported]
`503 Service Unavailable`	Most likely we are doing maintenance work (updates, etc.) and the system will be back up in a couple of minutes [no guests imported]
`Other (404, 500...)`	Other error [no guest imported]

In the case of status code 200, there is further JSON encoded data in the body of the response:

All guests successfully added:

{ “success“ : true }

In case of error, there is a list of errors for the individual guests.

Note
In case of error, we use the guest ID given in the request to identify the guests with errors. All guests that do not appear in the error list have been added successfully.

Expected JSON response for error

Code Block

language	json

{
  "success": false,
  "errors": [
    {
      "guest_id": "0",
      "error_details": [
        {
          "error_code": "0",
          "error_message": "..."
        }
      ]
    }
  ]
}

Potential Errors

Attribute	error_code	error_message	Further information
name	`1`	`Validation failed for name`
departure date	`2`	`Validation failed for date`
email	`3`	`Validation failed for email`
gender	`4`	`Validation failed for gender`
language	`5`	`Validation failed for language`
phone_number	`6`	`Validation failed for phone number`
reservation_id	`7`	`Validation failed for reservation id`	The "reservation_id" field is mandatory if the "arrival_date" of a guest is in the future.
other error	`0`	`Unexpected error inserting guest to database`

Examples

Shell

Code Block

language	bash

$ curl --location --request POST 'https://interfaces.customer-alliance.com/api/{ApiKey}/{ReviewSubject}' \
--header 'charset: utf-8' \
--header 'Content-Type: application/json' \
--data-raw '[
 {
    "id": "1",
    "reservation_id": "0123A3B4C5679",
    "name": "M\u00fcller",
    "gender": "f",
    "email": "lieschen@mueller.de",
    "language": "de",
    "arrival_date": "2021-07-01",
    "departure_date": "2021-07-02",
    "phone_number": "+491578777769978",
    "billing_address": "adress billing",
    "revenue_logis": "2000",
    "age": "33",
    "room_number":"24",
    "room_category": "premium"
  }
]'

Response

Code Block
{ "success": true, "added_guest_count": 1, "cancelled_guest_count": 0, "blacklisted_guest_count": 0, "already_invited_guest_count": 0 }

...

Page Comparison

Versions Compared

Old Version 9

New Version Current

Key

GET /reviews/v2/ca.json

Parameters

Name

Default value

Description

Examples

Shell

Response

GET /reviews/v2/all.json

Parameters

Name

Default value

Description

Examples

Shell

Response

GET /statistics/v1/categories.json

Parameters

Name

Default value

Description

Examples

Shell

Response

GET /statistics/v2/general/recent.json

Parameters

Name

Default value

Description

Examples

Shell

Response

GET /statistics/v2/general/total.json

Parameters

Name

Default value

Description

Examples

Shell

Response

GET /statistics/v2/portal-overview.json

Parameters

Name

Default value

Description

Examples

Shell

Response

GET /statistics/v1/reviews-over-time.json

Parameters

Name

Default value

Description

Δ = difference in days between start & end

Interval

Description

Examples

Shell

Response

GET /feedback/v2/questionnaires.json

Parameters

Examples

Shell

Response

GET /feedback/v2/stream.json

Parameters

Name

Default value

Description

Examples

Shell

Response

POST /account/{googlePlaceId}

Parameters

Name