Quick Links:
- You can use the reservation id to retrieve the guest details and then check the legal compliance status:
GET https://a.chekin.io/api/v3/reservations/2ac418ffe33541509dab456994c6f692/ Response: { "id":"2ac418ffe33541509dab456994c6f692", "housing":{ "id":"b1b1cfa4c8d448ca9903a258f99e8cb0", "url":"https://a.chekin.io/api/v3/housings/b1b1...", "type":"HOU", "name":"My Rental House", "picture":null, "police_account":{ "id":"6dc7a80af6f14e9896d648eb4f040541", "url":"https://a.chekin.io/api/v3/police-accounts/6dc7...", "type":"POL", "username":"H124569223", ... "local_send_time":"23:00:00", "delay":"THIS_DAY" }, ... }, "check_in_date":"2019-10-31T00:00:00Z", "check_out_date":"2019-11-10T00:00:00Z", "nights_of_stay":10, ... "guest_group":{ "id":"9ba8bfd146194b75a285d7e441774a29", "url":"https://a.chekin.io/api/v3/guest-groups/9ba8bfd1-4619-4b75-a285-d7e441774a29/", "number_of_guests":3, "leader_id":"befec70762ef42409b963df73f8eda89", "type":"G", "members":[ { "id":"befec70762ef42409b963df73f8eda89", "phone":"", "full_name":"Pedro Perez", "name":"Pedro", "surname":"Perez", "second_surname":"", "gender":"N", "birth_date":"1974-03-20", "birth_place":null, "residence":null, "language":"eng", "nationality":{ ... }, "names":{ ... }, "documents":[ ... ], "document":{ ... }, ... // Check legal compliance status, and other useful information "statuses":{ // Several statuses can be returned depending on the legal requirements of the country. "police":{ // Police registration status "in":{ // In Spain you need to register the check-in only. "code":"ERROR", "label":"Police registration has failed", "details":"Police website is temporarily unavailable" }, "out":{ // Check-out registration is required in some countries like Dubai. "code":"NOT_USED", "label":"Not used for police registration", "details":"Not started yet" } }, "statistics":{ // Statistics registration status "in":{ // Check-in registration is required in countries like Italy "code":"NEW", "label":"New", "details":"Not started yet" }, "out":{ // Check-out registration is required in countries like Italy "code":"NEW", "label":"New", "details":"Not started yet" } }, "arrival":{ // status information about guest arrival "code":"EXPECTED", "label":"Expected guest" }, "data":{ // status information about data completion "code":"INCOMPLETE", // Some guest data is missing, then it can't be sent to the legal authorities until is complete. "label":"Not enough info about this guest" } } } ... ] }, "signup_form_link":"https://a.chekin.io/L/wB2...", "aggregated_status":"ERROR" // An aggregated status at reservation level. … // Other status fields here are deprecated, but kept for backward compatibility // Please use the statuses at guest level or aggregated_status at reservation level }
To check the legal compliance status of each guest, take a look at guest_group > members > guest object > statuses.Every country has their own legal requirements. Some of them require the guests data to be sent to the Police only, while others also requires the data to be sent to a statistics center. Some authorities require to send data when the guests have checked in, and others also require to register the check-out.
Also, the time window to register guests varies from one country to other and sometimes by sub-region inside the same country.
Then you will find all the statuses info organized by authority and by check-in / out:
"statuses":{ "police":{ // Police registration status "in":{ // In Spain you need to register the check-in only. "code":"ERROR", "label":"Police verification failed", "details":"Document number is not valid" }, "out":{ // Check-out registration is required in some countries like Dubai. "code":"NOT_USED", "label":"Not used for police registration", "details":"" } }, "statistics":{ // Statistics registration status "in":{ // Check-in registration is required in countries like Italy "code":"NEW", "label":"New" }, "out":{ // Check-out registration is required in countries like Italy "code":"NEW", "label":"New" } }, }The possible status codes are:
Status Code Status Meaning NEW The guest data was saved, but it wasn’t sent to the legal authorities yet. Data will be sent in time, according to the legal requirements of the country and region. This can take 24 hs usually, but in some countries can take up to 48 or 72 hs, and in some cases is sent at the beginning of the next month. When in doubt, contact support. SCHEDULED A transaction was scheduled to send the data to the authorities, and it’ll be sent soon. PROGRESS The registration transaction is being executed, and the data is being sent to the legal authorities at the moment. Once the process finishes, the status will change to one of the following: COMPLETE, ERROR, NOT_ENOUGH_DATA, NO_LOGIN_CRED. COMPLETE The data was sent to the authorities successfully. The legal compliance have been achieved for this authority. ERROR An error occurred while sending the data to legal authorities. More details about the error can be found in field “details”. You can fix data errors and restart a failed transaction. NOT_ENOUGH_DATA Some guest data is missing and needs to be completed before sending it to authorities. More details about the error can be found in field “details”. NOT_USED It’s not required to send data to this authority in this particular case. For example, in spain is not required to register the guest check-out, only check-in is needed. NO_LOGIN_CRED Username and/or Password for this authority were not provided, and then the data can’t be sent to this authority. You need to provide the username and password used to login into the authority’s website (police website, statistics website,..) . Credentials can be set through API, using parameters police_account and stat_account, or using the Dashboard though the UI. You will need to restart any pending transactions after that. RESTART After completing or fixing guest data, or after adding missing credentials, the transaction can be restarted. Then the status will be RESTART instead of NEW. MANUAL The data will be sent to the legal authorities manually, by a member of our operations team. Once done, the status will be changed to COMPLETE. This is an uncommon case. Find more details about the possible guest statuses here
Also, you can check the aggregated_status at reservation level.
The aggregated_status is calculated based on an aggregation matrix, and basically it will be COMPLETE only when all guests have COMPLETE status and It’ll be ERROR if any guest has ERROR status.
The possible status codes are:
Status Code Status Meaning NEW The reservation has been created. No guest data was sent to the legal authorities yet. IN_PROGRESS At least the data of one guest is still being set to the legal authorities at the moment. You can check the status again later. COMPLETE All the guests were registered within all the required authorities successfully. ERROR At least one guest registration failed, within one or more legal authorities. You can check guest statuses to get more details, fix the problem, and restart the registration. - You can also get notified when legal compliance is complete or when it fails for a guest, using webhooks:
- Subscribe to webhooks to be notified every time a guest is registered correctly:
POST https://a.chekin.io/api/v3/webhooks/ { "target": "https://your.domain.con/target-endpoint/", "event": "PoliceRegistration.complete" }Every time a guest is successfully registered within the legal authorities, we will do a POST request to your endpoint sending the following data:
{ "hook": { "id": "fa52ddb28ca94ef29f3f2413e4157e7b", "event": "PoliceRegistration.complete", "target": "http://example.org/target-url/" }, "data": { "reservation_id": "936b7ba24f904efc90786d7a2ee0fa9d", "reservation_url": "https://a.chekin.io/api/v3/reservations/936b7ba24f904efc90786d7a2ee0fa9d/" } } - Subscribe to webhooks to be notified every time an error occurs, while registering a guest in the police:
POST https://a.chekin.io/api/v3/webhooks/ { "target": "https://your.domain.con/target-endpoint/", "event": "PoliceRegistration.error" }Every time a guest registration fails, we will do a POST request to your endpoint sending the following data:
{ "hook": { "id": "fa52ddb28ca94ef29f3f2413e4157e7b", "event": "PoliceRegistration.error", "target": "http://example.org/target-url/" }, "data": { "reservation_id": "936b7ba24f904efc90786d7a2ee0fa9d", "reservation_url": "https://a.chekin.io/api/v3/reservations/936b7ba24f904efc90786d7a2ee0fa9d/" } }
- Subscribe to webhooks to be notified every time a guest is registered correctly: