Loopon Public API

Loopon uses the industry standard OAuth 2 for authorization of API requests. In the naming convention of OAuth 2, the Loopon API acts as both a Resource Server and Authorization Server. For authentication we currently only support the Client Credentials Grant Type.

The relevant endpoints you need to be aware of are:

The possible scopes your API client might have access to are:

An example how to receive an access token would be:

$ curl -X POST -d "grant_type=client_credentials" -d "client_id=<CLIENT_ID>" --data-urlencode "client_secret=<SHARED_SECRET>" -d "scope=basic" "https://api.loopon.com/oauth2/token"

Which should return something like:

{"token_type":"Bearer","expires_in":3600,"access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6ImEzMGQ0ZGM4OGY4MDIxY2Q5YWQ1OWE2MTVjZTk5MzM4MWViYmJmMWI3YjUzMjhiMjdhN2E1MTUzM2Y0NTQwOThkOWVkOGNhNjQzYjBkMzQzIn0.eyJhdWQiOiJsb29wb24tZGVtbyIsImp0aSI6ImEzMGQ0ZGM4OGY4MDIxY2Q5YWQ1OWE2MTVjZTk5MzM4MWViYmJmMWI3YjUzMjhiMjdhN2E1MTUzM2Y0NTQwOThkOWVkOGNhNjQzYjBkMzQzIiwiaWF0IjoxNTExMDEzODg2LCJuYmYiOjE1MTEwMTM4ODYsImV4cCI6MTUxMTAxNzQ4Niwic3ViIjoiIiwic2NvcGVzIjpbImJhc2ljIl19.kE9brbD3CQFYBzgGzicMNm3W0O5B61Ku7o1P35_LjyCdM_etGlkBdrXwsbqO7qYAeh4fYXcwp1Am9aqxTCSvLV8HU597BtPYxLneYdK3j33s8HGQjpny66JbEcb9rN0evr9_tSR_T9gBPqfZ1Fmb4a3IleOPv1X2nI1btlwgQEU"}

In order to use this access token, include a HTTP Header in the format Authorization: Bearer ACCESS_TOKEN. For example:

curl -X GET -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6ImEzMGQ0ZGM4OGY4MDIxY2Q5YWQ1OWE2MTVjZTk5MzM4MWViYmJmMWI3YjUzMjhiMjdhN2E1MTUzM2Y0NTQwOThkOWVkOGNhNjQzYjBkMzQzIn0.eyJhdWQiOiJsb29wb24tZGVtbyIsImp0aSI6ImEzMGQ0ZGM4OGY4MDIxY2Q5YWQ1OWE2MTVjZTk5MzM4MWViYmJmMWI3YjUzMjhiMjdhN2E1MTUzM2Y0NTQwOThkOWVkOGNhNjQzYjBkMzQzIiwiaWF0IjoxNTExMDEzODg2LCJuYmYiOjE1MTEwMTM4ODYsImV4cCI6MTUxMTAxNzQ4Niwic3ViIjoiIiwic2NvcGVzIjpbImJhc2ljIl19.kE9brbD3CQFYBzgGzicMNm3W0O5B61Ku7o1P35_LjyCdM_etGlkBdrXwsbqO7qYAeh4fYXcwp1Am9aqxTCSvLV8HU597BtPYxLneYdK3j33s8HGQjpny66JbEcb9rN0evr9_tSR_T9gBPqfZ1Fmb4a3IleOPv1X2nI1btlwgQEU" "https://api.loopon.com/public/units" 

Which would return all units you are authorized to access:

[{"unitId":1203,"propertyCode":"","name":"Sea Hotels"},{"unitId":1282,"propertyCode":null,"name":"Sea Hotel Gulf of Bothnia"},{"unitId":1204,"propertyCode":"","name":"Sea Hotel Kattegat"},{"unitId":1601,"propertyCode":"","name":"Kattegat Gourmet Restaurant"},{"unitId":1281,"propertyCode":null,"name":"Sea Hotel Skagerrak"}]

Please contact us at support@loopon.com to receive your client id & client secret.

At its core, Loopon considers all types of feedback - irregardless of source (e-mail survey, QR-code feedback, 3rd party review site, …) as the same type of data; and this API refers to all these types of guest feedback.

When a guest provides feedback, the entire set of answers are saved in something called an AnswerDocument. Each individual answer to a specific question is exposed through the API as an Answer object.

In order to know what question an answer relates to, there’s the Question object. If the question is of a multiple choice type (radio or checkbox), it will also contain a list of QuestionOption.

So far everything is hopefully completely clear. One detail that complicates the above situation a little however, is that surveys are no static objects - you as a customer might often be asking us to do a change, or introduce changes yourself. You might add questions, remove questions, reformulate questions, etc.

In relation to the above an additional complication is that the AnswerDocument will also contain meta-data provided by your PMS; such as room number, rate plan, checkout date and other details. What this means in practice is that answers to a single AnswerDocument might be provided at different times - meta-data will be provided when we receive data from your PMS, the guest’s actual answers will be provided when the guest answers the survey. Finally, in certain circumstances, a guest’s answers might be modified afterwards if there has been some misunderstanding or the guest changes their mind after you have sorted out an issue the guest might have complained about.

In order to cope with all the above requirements, Loopon keeps track of something called a QuestionSet. This is a container that keeps track of which Questions were included in the survey at a given point in time.

Simply speaking, every time you make a modification to your survey - even if you just change a single question, a completely new QuestionSet is created which defines the complete contents of the survey at that point in time. When you are retreiving Answer objects they will specify which Question they relate to, which in turn is contained by a given QuestionSet. However, since (as explained above) a single AnswerDocument might contain answers provided at different points in time - also a single AnswerDocument can refer to multiple QuestionSets. While this is uncommon, it’s something your implementation must take into consideration.

Finally, how you retrieve your feedback. Within Loopon a single property (a hotel, cruise ship, restaurant, …) is called a Unit. Each Unit might have one or more Evaluations which is the container of the QuestionSets and AnswerDocuments.

There is a single straight-forward way to receive new answers from Loopon, which is to call the Get Answer Objects endpoint. This will automatically expand all relevant information you need (all included QuestionSets, Questions, QuestionOptions, AnswerDocument and Answers).

Note that for all API endpoints documented below as /units/{unitId}/evaluations/{evaluationId}/ you can also use the short-hand version /units/{unitId}/evaluation/ if you only want to operate on the default evaluation rather than explicitly stating which one you want to access. For the majority of Loopon API use cases, this is probably the version you want to use to avoid having to care about the evaluation ids.

In order to use the Loopon Chat API, we expect that you maintain your own backend for your own guest application and most likely your own frontend which is the guest application itself.

The picture below gives a quick overview of the different parts involved when using the Chat API:

A typical flow to setup a chat session, after which the guest writes a message to which the hotel responds, would look like this:

Note that for authorisation of the guest app itself, the unique identifier of the chat session is included in the WSS URL and is used as the authentication of the client. You do not need to pass any separate access token or other authentication info from the guest app.

When you want to deliver a chat message from the guest to the hotel, this is done by writing a LooponEvent in JSON format on the WebSocket to which your guest app is connected.

Note that if you provide any of the read only fields in your message, they will be ignored.

After you have sent a LooponEvent on the WebSocket, if it was correctly received and processed in the backend it will be sent back to you on the same WebSocket but this time with the appropriate read only fields filled in (such as created and id in case of for example a ChatMessage).

Example:

{
    "type":"chatMessage",
    "chatMessage":{
        "localId":"FB634A49-074E-4A8F-A840-EF66B1D38A3C",'
        "contentType":"text\/plain",
        "content":"Please be careful when parking my brand new Tesla Roadster!"
    }
}