NAV Navbar
shell python

Introduction

Welcome to the documentation for Chekin API.

Chekin is a simple tool for the tourism industry to verify, register, and access guests. Refer to our Integration Portal for more information on the scope of Chekin services and different ways to use our API.

The purpose of this doc is to give you all the API methods we provide along with descriptions of parameters and response examples.

Getting Started

Before you start, make sure to read the Integration Stages and Types of Integration guides of our Integration Portal to decide on the type of integration you would like to build. Or contact our Sales Manager to help you explore all the possibilities.

Next step is getting an account from the support team. This account lets you:

General overview

In the process of working with our API, you will have access to the following core entities:

These entities are the fundamental concepts that provide the basis for other items and link together everything in the system.

API details

Endpoint: https://a.chekin.io/api/v3/{method}

HTTPS: Our API requires HTTPS. We'll respond with an appropriate error if you're not using it.

Request Format: HTTP GET, POST, PATCH, DELETE (Content-Type: application/json)

Response Format: JSON

Basic definitions

Field Data Types

Name Based on Example Description
ID string "45f2f14bc65f43aeb71aaeff80ad3355" UUID hex string without dashes
URL string "https://example.org"
Enum string "DEFAULT" one of the options from predefined list
DateTime string "2019-01-01T12:30:00Z" ISO 8601 formatted string
List [1, 2, "whatever"]
JSON {"foo": "bar", "x": [1, 2, 3] }
string "foobar" regular string, text within quotation marks
integer 234 numeric digital value
boolean true, false

Authentication

Logging in

curl -X POST \
  https://a.chekin.io/api/v3/token/ \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "username@email.host",
    "password": "secret"
}'

import requests

url = "https://a.chekin.io/api/v3/token/"

payload = {
    "email": "username@email.host",
    "password": "secret"
}

headers = {
    'Content-Type': "application/json",
}

response = requests.request("POST", url, data=payload, headers=headers)

The above command returns a JSON structured like this:

{
    "token": "eyJ0eXAiOiJKV1QJ.....some..long..token..value....Fvdx3tvxe4dilwapHRYiQwS8"
}

If the credentials are not valid you will get an error:

{
    "non_field_errors": [
        "Unable to log in with provided credentials."
    ]
}

If you make a request to the API without access token you will get an error:

{
    "code": 4002,
    "message": "Invalid Authorization header. No credentials provided.",
    "status_code": 401,
    "errors": []
}

The Chekin API requires you to use token-authentication to access the API. To get a token, make a POSTrequest to /api/v3/token/ with user credentials(email and password) in payload.

Token refreshing

curl -X POST \
  https://a.chekin.io/api/v3/token/refresh/ \
  -H 'Content-Type: application/json' \
  -d '{
    "token": "..."
}'

import requests

url = "https://a.chekin.io/api/v3/token/"

payload = {
    "token": "...",
}

headers = {
    'Content-Type': "application/json",
}

response = requests.request("POST", url, data=payload, headers=headers)

To get a new token submit the old one in a POST request to /api/v3/token/refresh/. In response, you'll receive a new token.

The token lasts 1 hour. If your token hasn't expired and you make a request to get a new one, you will have two valid tokens until the first one expires. You can always request a new token without the old one, if you deleted it by mistake, there's a 'login' feature for that.

The above command returns a JSON structured like this:

{
    "token": "eyJ0eXAiOiJKV1QJ.....some..long..token..value....Fvdx3tvxe4dilwapHRYiQwS8"
}

Location

Location is a generic concept - it's used across different entities in API. There's a single required field in the location which is country. The other fields can describe the location more precisely and are used depending on the type of entity location is linked to.

Field Type Description
country string required ISO 3166-2 country code
division_level_1 string optional "Community" in Spain, "Region" in Italy and Portugal, "Department" in Colombia
division_level_2 string optional "Province" in Spain and Italy, "Municipality" in Colombia
division_level_3 string optional "Municipality" in Spain, "Comune" in Italy
postal_code string optional
city string optional
address string optional

Retrieving location codes

curl -X GET \
  https://a.chekin.io/api/v3/locations/?country=IT&division_level=2 \
  -H 'Authorization: JWT {{TOKEN}}' \
  -H 'Content-Type: application/json'

The above command returns JSON structured like this:

{
    "count": 103,
    "next": null,
    "previous": null,
    "results": [
        {
            "country": {
                "code": "IT",
                "name": "Italy"
            },
            "division_level_1": {
                "code": "420",
                "name": "Sardegna",
                "type": "region"
            },
            "division_level_2": {
                "code": "420111",
                "name": "provincia del Sud Sardegna",
                "type": "province"
            }
        },
        {
            "country": {
                "code": "IT",
                "name": "Italy"
            },
            "division_level_1": {
                "code": "401",
                "name": "Piemonte",
                "type": "region"
            },
            "division_level_2": {
                "code": "401004",
                "name": "provincia di Cuneo",
                "type": "province"
            }
        },
        {
            "country": {
                "code": "IT",
                "name": "Italy"
            },
            "division_level_1": {
                "code": "401",
                "name": "Piemonte",
                "type": "region"
            },
            "division_level_2": {
                "code": "401096",
                "name": "provincia di Biella",
                "type": "province"
            }
        },
        ...
    ]
}

curl -X GET \
  https://a.chekin.io/api/v3/locations/?country=IT&division_level=3 \
  -H 'Authorization: JWT {{TOKEN}}' \
  -H 'Content-Type: application/json'

The above command returns JSON structured like this:

{
    "count": 7799,
    "next": null,
    "previous": null,
    "results": [
        {
            "country": {
                "code": "IT",
                "name": "Italy"
            },
            "division_level_1": {
                "code": "401",
                "name": "Piemonte",
                "type": "region"
            },
            "division_level_2": {
                "code": "401",
                "name": "città metropolitana di Torino",
                "type": "province"
            },
            "division_level_3": {
                "code": "401001001",
                "name": "Agliè",
                "type": "comune"
            }
        },
        {
            "country": {
                "code": "IT",
                "name": "Italy"
            },
            "division_level_1": {
                "code": "401",
                "name": "Piemonte",
                "type": "region"
            },
            "division_level_2": {
                "code": "401",
                "name": "città metropolitana di Torino",
                "type": "province"
            },
            "division_level_3": {
                "code": "401001002",
                "name": "Airasca",
                "type": "comune"
            }
        },
        {
            "country": {
                "code": "IT",
                "name": "Italy"
            },
            "division_level_1": {
                "code": "401",
                "name": "Piemonte",
                "type": "region"
            },
            "division_level_2": {
                "code": "401",
                "name": "città metropolitana di Torino",
                "type": "province"
            },
            "division_level_3": {
                "code": "401001003",
                "name": "Ala di Stura",
                "type": "comune"
            }
        },
        ...
    ]
}

To get a list of supported locations you can make a GET request to /api/v3/location/ with filters like country and division_level.

E.g. /api/v3/locations/?country=IT&division_level=2 returns a list of locations in Italy with divisions down to provinces, and /api/v3/locations/?country=IT&division_level=3 will also include comunes.

Housings

A housing (same as house, accommodation) – a property of a certain type which contains a specific number of rooms, that can be rented by a guest group.

Create a housing

curl -X POST \
  https://a.chekin.io/api/v3/housings/ \
  -H 'Authorization: JWT {{TOKEN}}' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Amazing Housing",
    "type": "HOU",
    "police_account": {
      "type": "FAKE",
      "username": "someone",
      "password": "secret"
    },
    "stat_account": {
      "type": "FAKE",
      "username": "someone",
      "password": "secret"
    },
    "vatin": "121212",
    "tourism_registration_number": "45454545",
    "rooms": [
        {
            "name": "Room 1",
        },
        {
            "name": "Room 2",
        }
    ]
}'

import requests

url = "https://a.chekin.io/api/v3/housings/"

payload = {
    "name": "Amazing Housing",
    "type": "HOU",
    "police_account": {
      "type": "FAKE",
      "username": "someone",
      "password": "secret"
    },
    "stat_account": {
      "type": "FAKE",
      "username": "someone",
      "password": "secret"
    },
    "vatin": "121212",
    "tourism_registration_number": "45454545",
    "rooms": [
        {
            "name": "Room 1",
        },
        {
            "name": "Room 2",
        }
    ]
}

headers = {
    'Content-Type': "application/json",
    'Authorization': "JWT {{TOKEN}}",
}

response = requests.request("POST", url, data=payload, headers=headers)

There are several ways to create a housing.

First option is to create it separately by making a POST request to the url /api/v3/housings/ with a specified payload, including name and type, where type can take one of the values in the table below.

In response to the POST request, you will receive a json with the data of the created housing, including the housing id. You can use this id later to get the housing information, update or delete it, or to create reservations in this housing.

Second option is to create a housing when creating a reservation. Check out this option in the Reservation section.

It is mandatory to specify the housing type HOU (Vacation Rental) or HOT (Hotel / Hostel / Hostal Campground / B&B) if you are planning to connect a police account to the given property.

Housing types

Code Name Description
UNK Unknown Unknown type
HOU House Tourism Housing / Rural House
HOT Hotel Hotel / Pension
CAM Camping Camping / Hostel
MOT Motel
HOL Holiday resorts
OTH Other accommodation
RUR Rural residences
TOU Tourist hotel residences
VIL Village hotel
C12 CAMPSITES_CARAVAN_1_2 1*-2* Campsites and caravan parks and any other outdoor accommodation
C35 CAMPGROUNDS_CARAVAN_3_5 3*-5* (Campgrounds and caravan sites and any other outdoor accommodation
HR1 HOTEL_RESIDENCE_1 1* (tourist hotels, tourist residences, furnished holiday homes)
HR2 HOTEL_RESIDENCE_2 2* (tourist hotels, tourist residences, furnished holiday homes)
HR3 HOTEL_RESIDENCE_3 3* (Tourist hotels, tourist residences, tourism furnished)
HR4 HOTEL_RESIDENCE_4 4* (Tourist hotels, tourist residences, tourism furnished)
HR5 HOTEL_RESIDENCE_5 5* (Tourist hotels, tourist residences, tourism furnished)
PAL PALACES Palaces
BBF BED_AND_BREAKFAST Bed and breakfast
CAR CARAVAN CARAVAN
CST CAMPSITE CAMPSITES
PHO PROTECTIVE_HOUSE Protective Houses
WAT WATER Water
WCW WITHIN_CITY_WALLS Within city walls
YHO YOUTH_HOSTEL Youth Hostel
GHO GUEST_HOUSE Guest House
GAC Group Accommodation
H12 HOTEL_1_2 Hotel or other 1-2*
H35 HOTEL_3_5 Hotel or other 3-5*
SPA SPA_ACCOMMODATION SPA/ACCOMMODATION

Housing types

Code Name Description
STA1 1 star
STA2 2 star
STA3 3 star
STA5 5 star
STA4 4 star
B&B1 Bed and Breakfast 1 star
B&B2 Bed and Breakfast 2 star
B&B3 Bed and Breakfast 3 star
FARM FARM HOLIDAYS
HIST Historical Properties

The above command returns JSON structured like this:

{
    "id": "8ecaf8888f844a049c60da1d7b0d3f1d",
    "url": "https://a.chekin.io/api/v3/housings/8ecaf888-8f84-4a04-9c60-da1d7b0d3f1d/",
    "type": "HOU",
    "name": "Amazing Housing",
    "picture": null,
    "police_account": {
        "id": "096b0fac4c6a4835b26f3b7f8cb845af",
        "url": "https://a.chekin.io/api/v3/police-accounts/096b0fac-4c6a-4835-b26f-3b7f8cb845af/",
        "type": "FAKE",
        "username": "someone",
        "password": "secret",
        "certificate_password": "",
        "establishment_number": "",
        "external_name": "",
        "external_id": "",
        "local_send_time": "23:00:00",
        "delay": "THIS_DAY"
    },
    "stat_account": {
        "id": "0a5e89c35e5d4bd7be7b7991b4213882",
        "url": "https://a.chekin.io/api/v3/stat-accounts/0a5e89c3-5e5d-4bd7-be7b-7991b4213882/",
        "type": "FAKE",
        "username": "someone",
        "password": "secret",
        "local_send_time": "06:00:00",
        "delay": "ONE_DAY",
        "external_housing_id": "",
        "external_location_id": "",
        "send_mode": "AGGREGATED"
    },
    "vatin": "121212",
    "tourism_registration_number": "45454545",
    "max_capacity": 1,
    "rooms_quantity": 1,
    "is_biometric_match_enabled": false,
    "is_police_registration_enabled": true,
    "is_stat_registration_enabled": false,
    "is_automatic_precheckin_email_enabled": false,
    "is_checkin_complete_email_enabled": false,
    "is_checkin_docs_email_enabled": false,
    "is_auto_tax_calculation_enabled": false,
    "location": null,
    "status": "INCOMPLETE",
    "status_display": "Incomplete",
    "enabled_features": [],
    "is_auto_police_registration_enabled": false,
    "time_zone": "UTC"
}

Here is a list of the fields you can specify for a housing when creating or updating it:

Field Type Description
type Enum<HousingType>
subtype Enum<HousingSubtype> Optional housing subtype, if needed
name string required Name of housing
picture
police_account JSON semi-optional Linked police account, see Create a police account for details
police_account_id ID semi-optional ID of a police account which will be linked to the housing
stat_account JSON semi-optional Linked statistics account, see Create a stat account for details
stat_account_id ID semi-optional ID of a statistics account which will be linked to the housing
vatin string optional Value Added Tax Identification Number
tourism_registration_number string optional e.g. RTA number in Spain
rooms_quantity number optional Total number of rooms in housing
beds_quantity number optional Total number of beds in housing
is_biometric_match_enabled boolean
is_police_registration_enabled boolean optional Flag marks is data for this housing could be send to police registration (can't be activated without police account)
is_auto_police_registration_enabled boolean optional Flag activates auto data sending to police registration at the datetime specified in related police account
is_stat_registration_enabled boolean optional Flag marks is data for this housing will be send to ISTAT (can't be activated without stat account)
is_automatic_precheckin_email_enabled boolean
is_checkin_complete_email_enabled boolean
is_checkin_docs_email_enabled boolean
is_auto_tax_calculation_enabled boolean optional Flag indicates that the tax is calculated automatically for each reservation on this housing.
location Location Instance of Location objects, must contain country code, and optionally administrative division levels or address
time_zone string optional Housing timezone. One of Time zones available

It's possible to create or update related entities setting them as inner fields of the payload, e.g. you can add police and stat accounts when creating a new housing account:

curl -X POST \
  https://a.chekin.io/api/v3/housings/ \
  -H 'Authorization: JWT {{TOKEN}}' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "HOU",
    "max_capacity": 5,
    "name": "Some Housing Name",
    "vatin": "123",
    "tourism_registration_number": "123",
    "rooms_quantity": "3",
    "is_biometric_match_enabled": true,
    "is_police_registration_enabled": true,
    "police_account": {
        "type": "FAKE",
        "username": "username",
        "password": "password",
        "external_housing_id": "1",
        "external_location_id": "iw_ca"
    },
    "is_stat_registration_enabled": true,
    "stat_account": {
        "type": "FAKE",
        "username": "username",
        "password": "password",
        "external_housing_id": "2",
        "external_location_id": "iw_ca"
    }
}'

Time zones available

Field Field Field Field
Africa/Abidjan America/Guatemala Asia/Bahrain Europe/Bucharest
Africa/Accra America/Guayaquil Asia/Baku Europe/Budapest
Africa/Addis_Ababa America/Guyana Asia/Bangkok Europe/Busingen
Africa/Algiers America/Halifax Asia/Barnaul Europe/Chisinau
Africa/Asmara America/Havana Asia/Beirut Europe/Copenhagen
Africa/Bamako America/Hermosillo Asia/Bishkek Europe/Dublin
Africa/Bangui America/Indiana/Indianapolis Asia/Brunei Europe/Gibraltar
Africa/Banjul America/Indiana/Knox Asia/Chita Europe/Guernsey
Africa/Bissau America/Indiana/Marengo Asia/Choibalsan Europe/Helsinki
Africa/Blantyre America/Indiana/Petersburg Asia/Colombo Europe/Isle_of_Man
Africa/Brazzaville America/Indiana/Tell_City Asia/Damascus Europe/Istanbul
Africa/Bujumbura America/Indiana/Vevay Asia/Dhaka Europe/Jersey
Africa/Cairo America/Indiana/Vincennes Asia/Dili Europe/Kaliningrad
Africa/Casablanca America/Indiana/Winamac Asia/Dubai Europe/Kiev
Africa/Ceuta America/Inuvik Asia/Dushanbe Europe/Kirov
Africa/Conakry America/Iqaluit Asia/Famagusta Europe/Lisbon
Africa/Dakar America/Jamaica Asia/Gaza Europe/Ljubljana
Africa/Dar_es_Salaam America/Juneau Asia/Hebron Europe/London
Africa/Djibouti America/Kentucky/Louisville Asia/Ho_Chi_Minh Europe/Luxembourg
Africa/Douala America/Kentucky/Monticello Asia/Hong_Kong Europe/Madrid
Africa/El_Aaiun America/Kralendijk Asia/Hovd Europe/Malta
Africa/Freetown America/La_Paz Asia/Irkutsk Europe/Mariehamn
Africa/Gaborone America/Lima Asia/Jakarta Europe/Minsk
Africa/Harare America/Los_Angeles Asia/Jayapura Europe/Monaco
Africa/Johannesburg America/Lower_Princes Asia/Jerusalem Europe/Moscow
Africa/Juba America/Maceio Asia/Kabul Europe/Oslo
Africa/Kampala America/Managua Asia/Kamchatka Europe/Paris
Africa/Khartoum America/Manaus Asia/Karachi Europe/Podgorica
Africa/Kigali America/Marigot Asia/Kathmandu Europe/Prague
Africa/Kinshasa America/Martinique Asia/Khandyga Europe/Riga
Africa/Lagos America/Matamoros Asia/Kolkata Europe/Rome
Africa/Libreville America/Mazatlan Asia/Krasnoyarsk Europe/Samara
Africa/Lome America/Menominee Asia/Kuala_Lumpur Europe/San_Marino
Africa/Luanda America/Merida Asia/Kuching Europe/Sarajevo
Africa/Lubumbashi America/Metlakatla Asia/Kuwait Europe/Saratov
Africa/Lusaka America/Mexico_City Asia/Macau Europe/Simferopol
Africa/Malabo America/Miquelon Asia/Magadan Europe/Skopje
Africa/Maputo America/Moncton Asia/Makassar Europe/Sofia
Africa/Maseru America/Monterrey Asia/Manila Europe/Stockholm
Africa/Mbabane America/Montevideo Asia/Muscat Europe/Tallinn
Africa/Mogadishu America/Montserrat Asia/Nicosia Europe/Tirane
Africa/Monrovia America/Nassau Asia/Novokuznetsk Europe/Ulyanovsk
Africa/Nairobi America/New_York Asia/Novosibirsk Europe/Uzhgorod
Africa/Ndjamena America/Nipigon Asia/Omsk Europe/Vaduz
Africa/Niamey America/Nome Asia/Oral Europe/Vatican
Africa/Nouakchott America/Noronha Asia/Phnom_Penh Europe/Vienna
Africa/Ouagadougou America/North_Dakota/Beulah Asia/Pontianak Europe/Vilnius
Africa/Porto-Novo America/North_Dakota/Center Asia/Pyongyang Europe/Volgograd
Africa/Sao_Tome America/North_Dakota/New_Salem Asia/Qatar Europe/Warsaw
Africa/Tripoli America/Ojinaga Asia/Qostanay Europe/Zagreb
Africa/Tunis America/Panama Asia/Qyzylorda Europe/Zaporozhye
Africa/Windhoek America/Pangnirtung Asia/Riyadh Europe/Zurich
America/Adak America/Paramaribo Asia/Sakhalin GMT
America/Anchorage America/Phoenix Asia/Samarkand Indian/Antananarivo
America/Anguilla America/Port-au-Prince Asia/Seoul Indian/Chagos
America/Antigua America/Port_of_Spain Asia/Shanghai Indian/Christmas
America/Araguaina America/Porto_Velho Asia/Singapore Indian/Cocos
America/Argentina/Buenos_Aires America/Puerto_Rico Asia/Srednekolymsk Indian/Comoro
America/Argentina/Catamarca America/Punta_Arenas Asia/Taipei Indian/Kerguelen
America/Argentina/Cordoba America/Rainy_River Asia/Tashkent Indian/Mahe
America/Argentina/Jujuy America/Rankin_Inlet Asia/Tbilisi Indian/Maldives
America/Argentina/La_Rioja America/Recife Asia/Tehran Indian/Mauritius
America/Argentina/Mendoza America/Regina Asia/Thimphu Indian/Mayotte
America/Argentina/Rio_Gallegos America/Resolute Asia/Tokyo Indian/Reunion
America/Argentina/Salta America/Rio_Branco Asia/Tomsk Pacific/Apia
America/Argentina/San_Juan America/Santarem Asia/Ulaanbaatar Pacific/Auckland
America/Argentina/San_Luis America/Santiago Asia/Urumqi Pacific/Bougainville
America/Argentina/Tucuman America/Santo_Domingo Asia/Ust-Nera Pacific/Chatham
America/Argentina/Ushuaia America/Sao_Paulo Asia/Vientiane Pacific/Chuuk
America/Aruba America/Scoresbysund Asia/Vladivostok Pacific/Easter
America/Asuncion America/Sitka Asia/Yakutsk Pacific/Efate
America/Atikokan America/St_Barthelemy Asia/Yangon Pacific/Enderbury
America/Bahia America/St_Johns Asia/Yekaterinburg Pacific/Fakaofo
America/Bahia_Banderas America/St_Kitts Asia/Yerevan Pacific/Fiji
America/Barbados America/St_Lucia Atlantic/Azores Pacific/Funafuti
America/Belem America/St_Thomas Atlantic/Bermuda Pacific/Galapagos
America/Belize America/St_Vincent Atlantic/Canary Pacific/Gambier
America/Blanc-Sablon America/Swift_Current Atlantic/Cape_Verde Pacific/Guadalcanal
America/Boa_Vista America/Tegucigalpa Atlantic/Faroe Pacific/Guam
America/Bogota America/Thule Atlantic/Madeira Pacific/Honolulu
America/Boise America/Thunder_Bay Atlantic/Reykjavik Pacific/Kiritimati
America/Cambridge_Bay America/Tijuana Atlantic/South_Georgia Pacific/Kosrae
America/Campo_Grande America/Toronto Atlantic/St_Helena Pacific/Kwajalein
America/Cancun America/Tortola Atlantic/Stanley Pacific/Majuro
America/Caracas America/Vancouver Australia/Adelaide Pacific/Marquesas
America/Cayenne America/Whitehorse Australia/Brisbane Pacific/Midway
America/Cayman America/Winnipeg Australia/Broken_Hill Pacific/Nauru
America/Chicago America/Yakutat Australia/Currie Pacific/Niue
America/Chihuahua America/Yellowknife Australia/Darwin Pacific/Norfolk
America/Costa_Rica Antarctica/Casey Australia/Eucla Pacific/Noumea
America/Creston Antarctica/Davis Australia/Hobart Pacific/Pago_Pago
America/Cuiaba Antarctica/DumontDUrville Australia/Lindeman Pacific/Palau
America/Curacao Antarctica/Macquarie Australia/Lord_Howe Pacific/Pitcairn
America/Danmarkshavn Antarctica/Mawson Australia/Melbourne Pacific/Pohnpei
America/Dawson Antarctica/McMurdo Australia/Perth Pacific/Port_Moresby
America/Dawson_Creek Antarctica/Palmer Australia/Sydney Pacific/Rarotonga
America/Denver Antarctica/Rothera Canada/Atlantic Pacific/Saipan
America/Detroit Antarctica/Syowa Canada/Central Pacific/Tahiti
America/Dominica Antarctica/Troll Canada/Eastern Pacific/Tarawa
America/Edmonton Antarctica/Vostok Canada/Mountain Pacific/Tongatapu
America/Eirunepe Arctic/Longyearbyen Canada/Newfoundland Pacific/Wake
America/El_Salvador Asia/Aden Canada/Pacific Pacific/Wallis
America/Fort_Nelson Asia/Almaty Europe/Amsterdam US/Alaska
America/Fortaleza Asia/Amman Europe/Andorra US/Arizona
America/Glace_Bay Asia/Anadyr Europe/Astrakhan US/Central
America/Godthab Asia/Aqtau Europe/Athens US/Eastern
America/Goose_Bay Asia/Aqtobe Europe/Belgrade US/Hawaii
America/Grand_Turk Asia/Ashgabat Europe/Berlin US/Mountain
America/Grenada Asia/Atyrau Europe/Bratislava US/Pacific
America/Guadeloupe Asia/Baghdad Europe/Brussels UTC

Get a list of housings

curl -X GET \
  https://a.chekin.io/api/v3/housings/ \
  -H 'Authorization: JWT {{TOKEN}}' \
  -H 'Content-Type: application/json'

import requests

url = "https://a.chekin.io/api/v3/housings/"

headers = {
    'Content-Type': "application/json",
    'Authorization': "JWT {{TOKEN}}",
}

response = requests.request("GET", url, headers=headers)

To get a list of housing make a GET request to the /api/v3/housings/ endpoint.

Get a housing

curl -X GET \
  https://a.chekin.io/api/v3/housings/{{HOUSING_ID}}/ \
  -H 'Authorization: JWT {{TOKEN}}' \
  -H 'Content-Type: application/json'

import requests

url = "https://a.chekin.io/api/v3/housings/{{HOUSING_ID}}/"

headers = {
    'Content-Type': "application/json",
    'Authorization': "JWT {{TOKEN}}",
}

response = requests.request("GET", url, headers=headers)

To get detailed info about housing you can make a GET request to /api/v3/housings/{{HOUSING_ID}}/ with specified housing ID.

Update a housing

curl -X PATCH \
  https://a.chekin.io/api/v3/housings/{{HOUSING_ID}}/ \
  -H 'Authorization: JWT {{TOKEN}}' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Amazing housing"
}'

import requests

url = "https://a.chekin.io/api/v3/housings/{{HOUSING_ID}}/"

headers = {
    'Content-Type': "application/json",
    'Authorization': "JWT {{TOKEN}}",
}

payload = {
    "name": "Amazing housing",
}

response = requests.request("PATCH", url, data=payload, headers=headers)

To update housing info you can make a PATCH request to /api/v3/housings/{{HOUSING_ID}}/ with payload containing set of field as described in section Create a housing.

Delete a housing

curl -X DELETE \
  https://a.chekin.io/api/v3/housings/c2fcc7a252e64a23b4cd4111a22874f0/ \
  -H 'Authorization: JWT {{TOKEN}}'

import requests

url = "https://a.chekin.io/api/v3/housings/c2fcc7a252e64a23b4cd4111a22874f0/"

headers = {
    'Authorization': "JWT {{TOKEN}}",
}

response = requests.request("DELETE", url, headers=headers)

To delete a housing from you account make a DELETE request to the /api/v3/housings/{id}/ endpoint.

Rooms

A room (same as space) – a separate room in the hotel to which a reservation can be assigned.

Create a room

curl -X POST \
  https://a.chekin.io/api/v3/rooms/ \
  -H 'Authorization: JWT {{TOKEN}}' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Room name",
    "housing_id": "{{HOUSING_ID}}"
}'

import requests

url = "https://a.chekin.io/api/v3/rooms/"

payload = {
    "name": "Room name",
    "housing_id": "{{HOUSING_ID}}"
}

headers = {
    'Content-Type': "application/json",
    'Authorization': "JWT {{TOKEN}}",
}

response = requests.request("POST", url, data=payload, headers=headers)

There are several ways to create a room.

First option is to create it separately by making a POST request to the url /api/v3/room/ with a specified payload, including name and housing_id.

In response to the POST request, you will receive a json with the data of the created room, including the room id. You can use this id later to get the room information, update or delete it, or to create reservations in this room.

Second option is to create a room during creating a housing. Check out this option in the Create a housing.

Get a list of rooms

curl -X GET \
  https://a.chekin.io/api/v3/rooms/ \
  -H 'Authorization: JWT {{TOKEN}}' \
  -H 'Content-Type: application/json'

import requests

url = "https://a.chekin.io/api/v3/rooms/"

headers = {
    'Content-Type': "application/json",
    'Authorization': "JWT {{TOKEN}}",
}

response = requests.request("GET", url, headers=headers)

To get a list of rooms make a GET request to the /api/v3/rooms/ endpoint.

Get a room

curl -X GET \
  https://a.chekin.io/api/v3/rooms/{{ROOM_ID}}/ \
  -H 'Authorization: JWT {{TOKEN}}' \
  -H 'Content-Type: application/json'

import requests

url = "https://a.chekin.io/api/v3/rooms/{{ROOM_ID}}/"

headers = {
    'Content-Type': "application/json",
    'Authorization': "JWT {{TOKEN}}",
}

response = requests.request("GET", url, headers=headers)

To get detailed info about a room you can make a GET request to /api/v3/rooms/{{ROOM_ID}}/ with specified room ID.

Update a room

curl -X PATCH \
  https://a.chekin.io/api/v3/rooms/{{ROOM_ID}}/ \
  -H 'Authorization: JWT {{TOKEN}}' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "New room name"
}'

import requests

url = "https://a.chekin.io/api/v3/rooms/{{ROOM_ID}}/"

headers = {
    'Content-Type': "application/json",
    'Authorization': "JWT {{TOKEN}}",
}

payload = {
    "name": "New room name",
}

response = requests.request("PATCH", url, data=payload, headers=headers)

To update the room info you can make a PATCH request to /api/v3/rooms/{{ROOM_ID}}/ with payload containing set of field as described in section Create a room.

Delete a room

curl -X DELETE \
  https://a.chekin.io/api/v3/rooms/{{ROOM_ID}}/ \
  -H 'Authorization: JWT {{TOKEN}}'

import requests

url = "https://a.chekin.io/api/v3/rooms/{{ROOM_ID}}/"

headers = {
    'Authorization': "JWT {{TOKEN}}",
}

response = requests.request("DELETE", url, headers=headers)

To delete a room from your account make a DELETE request to the /api/v3/rooms/{id}/ endpoint.

Reservations

A reservation (same as booking) – a record containing info about a guest group coming to a property at a specific date and, therefore, blocking its availability for the stated date.

Reservation payload supports nested structure, so it's possible to create all the necessary entities with a single request. Check the description of the fields payload available following the links in the table below.

If the housing related to this reservation has the field is_auto_tax_calculation_enabled - true, the following fields will be calculated (for now, available only for Italy), by default all are null:

Create a reservation

curl -X POST \
  https://a.chekin.io/api/v3/reservations/ \
  -H 'Authorization: JWT {{TOKEN}}' \
  -H 'Content-Type: application/json' \
  -d '{
    "check_in_date": "2019-06-25",
    "check_out_date": "2019-06-30",
    "housing_id": "{{HOUSING_ID}}",
    "default_invite_email": "some.email@example.org",
    "guest_group": {
      "number_of_guests": 2,
      "members": [
        {
            "name": "John Doe",
            "gender": "M"
        },
        {
            "name": "Jane Doe",
            "gender": "F"
        }
    ]
  }
}'

import requests

url = "https://a.chekin.io/api/v3/reservations/"

payload = {
    "check_in_date": "2019-10-01",
    "check_out_date": "2019-10-05",
    "housing_id": "{{HOUSING_ID}}",
    "default_invite_email": "some.email@example.org",
    "guest_group": {},
}

headers = {
    'Content-Type': "application/json",
    'Authorization': "JWT {{TOKEN}}",
}

response = requests.request("POST", url, data=payload, headers=headers)

The above command returns JSON structured like this:

{
    "id": "c4f529e7ad5c4c96a6dd6c3d61072705",
    "tax": null,
    "fee": "0.00",
    "people_taxable": null,
    "people_exempted": null,
    "nights_taxable": null,
    "nights_exempted": null,
    "total_nights": null,
    "max_nights_taxable": null,
    "housing": "...",
    "check_in_date": "2019-06-25T00:00:00Z",
    "check_out_date": "2019-06-30T00:00:00Z",
    "nights_of_stay": 5,
    "origin": "DEFAULT",
    "created_at": "2019-09-25T13:49:59.196117Z",
    "guest_group": {
        "id": "aacf33cdfd434618b874d709d6dcbc47",
        "url": "https://a.chekin.io/api/v3/guest-groups/c05a7ad6-c243-4f67-bd78-ffb195fe2d9b/",
        "number_of_guests": 2,
        "members": [
            {
                "id": "6e44db8163904f75b05ffb5df2e152bd",
                "phone": "",
                "full_name": "John Doe",
                "name": "John Doe",
                "surname": "",
                "second_surname": "",
                "gender": "M",
                "birth_date": null,
                "birth_place": null,
                "residence": null,
                "language": "eng",
                "nationality": null,
                "names": {
                    "name": "John Doe"
                },
                "documents": [],
                "document": null,
                "signature": null,
                "statuses": {
                    "police": {
                        "in": {
                            "code": "NEW",
                            "label": "New"
                        },
                        "out": {
                            "code": "NEW",
                            "label": "New"
                        }
                    },
                    "statistics": {
                        "in": {
                            "code": "NEW",
                            "label": "New"
                        },
                        "out": {
                            "code": "NEW",
                            "label": "New"
                        }
                    },
                    "arrival": {
                        "code": "EXPECTED",
                        "label": "Expected guest"
                    },
                    "data": {
                        "code": "COMPLETE",
                        "label": "All the necessary data are filled in"
                    }
                }
            },
            {
                "id": "e055eec8d92b4a2790b45caf30593348",
                "phone": "",
                "full_name": "Jane Doe",
                "name": "Jane Doe",
                "surname": "",
                "second_surname": "",
                "gender": "F",
                "birth_date": null,
                "birth_place": null,
                "residence": null,
                "language": "eng",
                "nationality": null,
                "names": {
                    "name": "Jane Doe"
                },
                "documents": [],
                "document": null,
                "signature": null,
                "statuses": {
                    "police": {
                        "in": {
                            "code": "NEW",
                            "label": "New"
                        },
                        "out": {
                            "code": "NEW",
                            "label": "New"
                        }
                    },
                    "statistics": {
                        "in": {
                            "code": "NEW",
                            "label": "New"
                        },
                        "out": {
                            "code": "NEW",
                            "label": "New"
                        }
                    },
                    "arrival": {
                        "code": "EXPECTED",
                        "label": "Expected guest"
                    },
                    "data": {
                        "code": "COMPLETE",
                        "label": "All the necessary data are filled in"
                    }
                }
            }
        ],
        "leader_id": "6e44db8163904f75b05ffb5df2e152bd",
        "type": "G"
    },
    "occupied_rooms_quantity": 1,
    "status_invite_email_sending": null,
    "status_invite_email_sending_display": null,
    "status": "NEW",
    "signup_form_link": "https://a.chekin.io/L/myp04mqGS3uIw6ARCPBIBg",
    "aggregated_status": "NEW"
}

To create a reservation make a POST request to the url /api/v3/reservations/. The following fields are the bare minimum of mandatory fields to create a reservation: - check_in_date - check_out_date - housing object or housing_id of the housing to which the new reservation will be linked to - guest_group object or guest_group_id

Here's the list of all the fields you can specify for a reservation to create or update it:

Field Type Description
check_in_date DateTime mandatory The arrival date
check_out_date DateTime semi-optional The departure date
default_invite_email Email optional A predefined email to invite guests to the reservation
default_leader_full_name string optional The name of the group leader
external_room_id string semi-optional ID of a room in the ISTAT account
guest_group JSON semi-optional guest group object, check Create a guest group for details
guest_group_id ID semi-optional ID of a predefined guest group
housing JSON semi-optional housing object which will be created, see Create a housing for details
housing_id ID semi-optional ID of a housing that will be linked to the reservation
nights_of_stay integer semi-optional The number of nights of the stay
occupied_rooms_quantity integer optional Number of rooms occupied. Has value 1 if not specified during creating
origin Enum optional The field identifying the origin of the reservation in the system. Has value "DEFAULT" if not specified
status Enum<ReservationStatus> optional Has value "NEW" if not specified

Reservation Status values

Code Name Description
NEW New
CHECKED_IN Checked in
CHECKED_OUT Checked out
COMPLETE Complete
DELETED Deleted

Additional response fields

In response you will also get the following read-only fields:

Field Type Description
aggregated_status Enum<AggregatedStatus> General reservation status calculated as a aggregation of police registration status and stat registration status
signup_form_link URL Link to the web form which takes guest info and adds the guest to the reservation
created_at DateTime Entity created timestamp

Aggregated Status values

Code Name Description
NEW Ready to send Guest data will be sent automatically to the authorities on the check-in date
ERROR Error There was an error and the guest is not registered yet
COMPLETE Complete Guest data has been sent successfully to the authorities
CHECK_IN_REG Check-in registered Guest data was registered successfully for the check-in and is ready to be registered for the check-out
IN_PROGRESS In progress Guest data is being sent to the authorities
GUESTS_MISSING Guests missing Number of guests added is less than the number of guests expected
CREDS_MISSING Credentials missing Username and/or Password for this authority were not provided, so the data can’t be sent to this authority

Get a list of reservations

curl -X GET \
  https://a.chekin.io/api/v3/reservations/ \
  -H 'Authorization: JWT {{TOKEN}}' \
  -H 'Content-Type: application/json'

import requests

url = "https://a.chekin.io/api/v3/reservations/"

headers = {
    'Content-Type': "application/json",
    'Authorization': "JWT {{TOKEN}}",
}

response = requests.request("GET", url, headers=headers)

To get a list of reservations make a GET request to the /api/v3/reservations/ endpoint.

Get a reservation

curl -X GET \
  https://a.chekin.io/api/v3/reservations/{{RESERVATION_ID}}/ \
  -H 'Authorization: JWT {{TOKEN}}' \
  -H 'Content-Type: application/json'

import requests

url = "https://a.chekin.io/api/v3/reservations/{{RESERVATION_ID}}/"

headers = {
    'Content-Type': "application/json",
    'Authorization': "JWT {{TOKEN}}",
}

response = requests.request("GET", url, headers=headers)

To get a reservation make a GET request to the /api/v3/reservations/:id/ endpoint with specified reservation ID.

Update a reservation

curl -X PATCH \
  https://a.chekin.io/api/v3/reservations/{{RESERVATION_ID}}/ \
  -H 'Authorization: JWT {{TOKEN}}' \
  -H 'Content-Type: application/json' \
  -d '{
    "check_out_date": "2019-11-01"
}'

import requests

url = "https://a.chekin.io/api/v3/reservations/{{RESERVATION_ID}}/"

headers = {
    'Content-Type': "application/json",
    'Authorization': "JWT {{TOKEN}}",
}

payload = {
    "check_out_date": "2019-11-01",
}

response = requests.request("PATCH", url, data=payload, headers=headers)

To update a reservation make a PATCH request to the /api/v3/reservations/:id/ endpoint with specified reservation ID and payload containing set of field as described in section Create a reservation.

Delete a reservation

curl -X DELETE \
  https://a.chekin.io/api/v3/reservations/c2fcc7a252e64a23b4cd4111a22874f0/ \
  -H 'Authorization: JWT {{TOKEN}}'

import requests

url = "https://a.chekin.io/api/v3/reservations/c2fcc7a252e64a23b4cd4111a22874f0/"

headers = {
    'Authorization': "JWT {{TOKEN}}",
}

response = requests.request("DELETE", url, headers=headers)

To delete a reservation, make a DELETE request to the /api/v3/reservations/{id}/ endpoint.

Examples

Create all the necessary entities with a single request

curl -X POST \
  https://a.chekin.io/api/v3/reservations/ \
  -H 'Authorization: JWT {{TOKEN}}' \
  -H 'Content-Type: application/json' \
  -d '{
  "check_in_date": "2019-06-25",
  "check_out_date": "2019-06-30",
  "housing": {
    "name": "Amazing Housing",
    "type": "HOU",
    "police_account": {
      "type": "FAKE",
      "username": "someone",
      "password": "secret"
    },
    "stat_account": {
      "type": "FAKE",
      "username": "someone",
      "password": "secret"
    }
  },
  "guest_group": {
    "number_of_guests": "1",
    "type": "G",
    "members": [{
      "name": "Jane",
      "surname": "Doe",
      "birth_date": "2000-01-01",
      "gender": "F",
      "nationality": "FR",
      "birth_place": {
        "country": "FR"
      },
      "documents": [{
        "type": "P",
        "number": "123456",
        "issue_date": "2015-01-01",
        "issue_place": {
          "country": "FR"
        }
      }]
    }]
  }
}'

The following request will be create a housing, police and stat accounts, a reservation with a guest and the document for the guest. More fields are supported, please check the related sections of the documentation.

Guest statuses

Every guest in a guest group linked to reservation has a statuses field which contains a set of statuses describing the state of that guest inside the system. The possible statuses are:

Sample statuses payload

{
    "statuses": {
        "police": {
            "in": {
                "code": "COMPLETE",
                "label": "Police registration successfully completed",
                "details": "registration completed"
            },
            "out": {
                "code": "NOT_USED",
                "label": "Not used for police registration",
                "details": ""
            }
        },
        "statistics": {
            "in": {
                "code": "NEW",
                "label": "New"
            },
            "out": {
                "code": "NEW",
                "label": "New"
            }
        },
        "arrival": {
            "code": "EXPECTED",
            "label": "Expected guest"
        },
        "data": {
            "code": "INCOMPLETE",
            "label": "Not enough info about this guest"
        }
    }
}

Some polices and stats require info both for the check-in and check-out events, so the police and statistics have subfields in and out. Every status field has a code and a label attributes containing a constant value and human-readable text description of a status. There can also be a details field with some info in case a recent status change didn't succeed.

Guest police registration statuses

Code Description
NEW New
RESTART Restart
SCHEDULED Scheduled
PROGRESS Police verification in progress
COMPLETE Police registration successfully completed
ERROR Police verification failed
NOT_USED Not used for police registration
MANUAL Police registration must be completed manually
NO_LOGIN_CRED No police login credentials have been provided
NOT_ENOUGH_DATA Not enough data

Guest statistics registration statuses

Code Description
NEW New
RESTART After completing or fixing guest data, or after adding missing credentials, the registration can be restarted. Then the status will be RESTART instead of NEW
PROGRESS Stat registration is in progress
COMPLETE Stat registration successfully completed
ERROR Stat registration failed
NOT_USED Not used for stat registration

Restart or force start registration in stat and police

If police/stat registration fails for such a reason as unfilled guest data or issues with the connection, you can restart the registration.

Restart/force start a police registration

Restarts the registration for all failed guests with status ERROR. Or starts the registration for all guests with status NEW.

curl -X POST \
  https://a.chekin.io/api/v3/reservations/{{RESERVATION_ID}}/resend-reservation-to-police/ \
  -H 'Authorization: JWT {{TOKEN}}' \
  -H 'Content-Type: application/json' \

import requests

url = "https://a.chekin.io/api/v3/reservations/{{RESERVATION_ID}}/resend-reservation-to-police/"

headers = {
    'Content-Type': "application/json",
    'Authorization': "JWT {{TOKEN}}",
}

response = requests.request("POST", url, headers=headers)

Sample response

{
    "status": "Police registration restarted successfully."
}

{
    "code": "1000", 
    "message": "Validation Failed", 
    "status_code": 400, 
    "errors": [{
        "message": "Police registration restart is not available, status is not NEW or ERROR. Current status is PROGRESS"
    }]
}

{
    "code": "1000", 
    "message": "Validation Failed", 
    "status_code": 400, 
    "errors": [{
        "message": "Police registration not available for this reservation, check your police data."
    }]
}

(Re)start police check-out

If the related police type supports check-out action, this endpoint starts or restarts the police check-out.

For UAE Holiday Homes check-out occurs for the entire reservation.

For other police types (re)start occurs for all successfully checked-in guests in a reservation if it's the first time of guest's check-out or if the previous check-out failed.

curl -X POST \
  https://a.chekin.io/api/v3/reservations/{{RESERVATION_ID}}/send-reservation-to-police-check-out/ \
  -H 'Authorization: JWT {{TOKEN}}' \
  -H 'Content-Type: application/json' \

import requests

url = "https://a.chekin.io/api/v3/reservations/{{RESERVATION_ID}}/resend-reservation-to-police/"

headers = {
    'Content-Type': "application/json",
    'Authorization': "JWT {{TOKEN}}",
}

response = requests.request("POST", url, headers=headers)

Sample response

{
    "status": "Reservation check-out started for 2 guest(s)"
}

{
    "code": "1000",
    "message": "Validation Failed",
    "status_code": 400,
    "errors": [
        {
            "message": "Reservation check-out not started. Please check reservation data"
        }
    ]
}

{
    "code": "1000", 
    "message": "Validation Failed", 
    "status_code": 400, 
    "errors": [{
        "message": "Check-out not available. The check-out time has not yet come"
    }]
}

Restart/force start stat registration

Restarts the registration of all guests on a reservation. Statuses of reservations registration and of each guest in reservation should be ERROR.

Also, force starts registration for all guests on the reservation. Statuses of reservations registration and of each guest in reservation should be NEW.

Restart/force start is available for the following stat-types only:

curl -X POST \
  https://a.chekin.io/api/v3/reservations/{{RESERVATION_ID}}/resend-reservation-to-stat/ \
  -H 'Authorization: JWT {{TOKEN}}' \
  -H 'Content-Type: application/json' \

import requests

url = "https://a.chekin.io/api/v3/reservations/{{RESERVATION_ID}}/resend-reservation-to-stat/"

headers = {
    'Content-Type': "application/json",
    'Authorization': "JWT {{TOKEN}}",
}

response = requests.request("POST", url, headers=headers)

Sample response

{
    "status": "Stat registration restarted successfully."
}

{
    "code": "1000", 
    "message": "Validation Failed", 
    "status_code": 400, 
    "errors": [{
        "message": "Registrations cannot be restarted in ITVE. Please contact support."
    }]
}

{
    "code": "1000", 
    "message": "Validation Failed", 
    "status_code": 400, 
    "errors": [{
        "message": "Future reservations cannot be send."
    }]
}

{
    "code": "1000", 
    "message": "Validation Failed", 
    "status_code": 400, 
    "errors": [{
        "message": "Stat re-registration not available for this reservation, some guests were successfully registered."
    }]
}

{
    "code": "1000", 
    "message": "Validation Failed", 
    "status_code": 400, 
    "errors": [{
        "message": "Stat force registration not available for this reservation, some guests were successfully registered."
    }]
}

{
    "code": "1000", 
    "message": "Validation Failed", 
    "status_code": 400, 
    "errors": [{
        "message": "Stat registration restart is not available, status is not NEW or ERROR. Current status is PROGRESS"
    }]
}

Police actions triggers

Prerequisites

Housing, related to a reservation, has a police account and a flag "is_police_registration_enabled" activated.

Check-in

Service starts police registration for the reservation if the reservation changes status from NEW to CHECKED_IN and if one of the conditions is met:

Check-out

If a related police type supports check-out (UAE Holiday Homes, Colombia SIRE), the service starts police check-out for all the successfully registered guests if reservation changes status from CHECKED_IN to CHECKED_OUT and after the check_out_date has arrived.

Country-Specific Reservation Data

There can be different sets of fields required to create a reservation in different countries. This section provides a basic set of fields for most of the countries with explanations on the usage of the fields as well as country-specific sets of fields.

Default Information (r)

Default set of reservation information is the basic data set allowing to create a fully-functioning reservation. It includes some of the optional fields to allow usage of specific features (such as precheck-in).

Field Type Description
check_in_date mandatory the arrival date
check_out_date mandatory the departure date
housing_id optional the ID of a housing that already exists in the system and will be linked to the reservation
guest_group optional guest group object, check Create a guest group for details
default_leader_full_name optional the name of the guest group leader
default_invite_email optional a predefined email to invite guests to the reservation
origin optional the field identifying the origin of the reservation in the system; has value "DEFAULT" if not specified

Austria (r)

Field Description
check_in_date the arrival date
check_out_date the departure date
guest_group guest group object, including guest_group_type, check Create a guest group for details

Italy (r)

Field Description
check_in_date the arrival date
check_out_date the departure date
guest_group guest group object, including guest_group_type, check Create a guest group for details
occupied_rooms_quantity the number of rooms occupied, required if STAT is activated

United Arab Emirates (r)

Field Description
check_in_date the arrival date
check_out_date the departure date
guest_group guest group object, including guest_group_type, check Create a guest group for details

Guests

A guest – a person, a group member who checks in to a reservation.

Create a guest

curl -X POST \
  https://a.chekin.io/api/v3/guests/ \
  -H 'Authorization: JWT {{TOKEN}}' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "John",
    "surname": "Doe",
    "second_surname": "Doe",
    "phone": "+31231111111",
    "email": "username@domain.tld",
    "gender": "M",
    "birth_date": "2000-01-01",
    "birth_place": {
        "country": "IT",
        "province": "420111"
    },
    "residence": {
        "country": "IT",
        "province": "420111"
    },
    "nationality": "ES",
    "document": {
        "type": "P",
        "number": "12312312",
        "issue_date": "2015-01-01"
    },
    "signature": "data:image/png;base64,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"
}'

import requests

url = "https://a.chekin.io/api/v3/guests/"

payload = {
    "name": "John",
    "surname": "Doe",
    "second_surname": "Doe",
    "phone": "+31231111111",
    "email": "username@domain.tld",
    "gender": "M",
    "birth_date": "2000-01-01",
    "birth_place": {
        "country": "IT",
        "region": "401",
        "province": "401",
        "comune": "401001001"
    },
    "residence": {
        "country": "IT",
        "province": "420111"
    },
    "nationality": "ES",
    "document": {
        "type": "P",
        "number": "12312312",
        "issue_date": "2015-01-01"
    },
    "signature": "data:image/png;base64,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"
}

headers = {
    "Content-Type": "application/json",
    "Authorization": "JWT {{TOKEN}}",
}

response = requests.request("POST", url, data=payload, headers=headers)

Check the Country specifics section of this doc to get more info about the required fields.

It's possible to link a guest to the reservation's guest group specifying reservation ID or guest group ID.

Field Type Description
name (first_name) string mandatory Name of a guest
surname (last_name) string mandatory Surname of a guest
second_surname string semi-optional Second surname of a guest (required for spanish people)
middle_name string optional Middle name of a guest
gender (sex) Enum<Gender> required Gender of a guest
phone string optional Phone number in international format
email string optional Email address in "username@domain.tld" format
birth_date string mandatory Birth date in "YYYY-MM-DD" format
birth_place Location optional Place of birth
residence Location optional Place of residence
signature string mandatory Base64-encoded signature image file
language string optional ISO 639-3 language code
nationality string mandatory ISO 3166-2 country code
document <Document> optional Guest document
documents List<Document> optional List of documents
reservation_id ID optional ID of the reservation with a guest group where new person will be added
guest_group_id ID optional ID of the guest group where new person will be added

Guest Gender values

Code Name Description
M Male
F Female
N Not applied Default value if no gender specified for person

Guest Documents

Field Type Description
type Enum<DocumentType> required Type of document
number string mandatory
issue_date Date optional Issue date in "YYYY-MM-DD" format
expiration_date Date optional Expiration date in "YYYY-MM-DD" format
issue_place Location optional place of issue
front_side_scan string optional Base64-encoded scan image file
back_side_scan string optional Base64-encoded scan image file

Guest Documents Types

Code Name Description
P Passport
I Foreign European ID
CO_P Passport (Colombia)
CO_FD Foreign Document (Colombia)
CO_FID Foreigner ID (Colombia)
CO_DIP Diplomatic ID (Colombia)
CZ_ID Identity Card (Czech Republic)
CZ_P Passport (Czech Republic)
CZ_DL Driving Licence (Czech Republic)
ES_D Documento nacional de identidad (Spain)
ES_P Passport (Spain)
ES_C Permiso de conducir (Spain)
ES_I Documento Extranjero (Spain)
ES_N Permiso residencia español (Spain)
ES_X Permiso residencia extranjero (Spain)
GR_ID Identity Card (Greece)
GR_P Passport (Greece)
GR_DL Driving Licence (Greece)
GR_ARMY_ID Army ID (Greece)
GR_WORK_PERMIT Work Permit (Greece)
IT_ACMIL TESS. APP.TO AG.CUSTODIA (Italy)
IT_ACSOT TESS. SOTT.LI AG.CUSTODIA (Italy)
IT_ACUFF TESS. UFF.LI AG.CUSTODIA (Italy)
IT_AMMIL TESS. MILITARE TRUPPA A.M (Italy)
IT_AMSOT TESS. SOTTUFFICIALI A.M. (Italy)
IT_AMUFF TESS. UFFICIALI A.M. (Italy)
IT_CCMIL TESS. APP.TO CARABINIERI (Italy)
IT_CCSOT TESS. SOTTUFFICIALI CC (Italy)
IT_CCUFF TESS. UFFICIALE (Italy)
IT_CERID CERTIFICATO D'IDENTITA' (Italy)
IT_CFMIL TESS. AG. E AG.SC. C.F.S. (Italy)
IT_CFSOT TESS. SOTTUFICIALI C.F.S. (Italy)
IT_CFUFF TESS. UFFICIALI C.F.S. (Italy)
IT_CIDIP CARTA ID. DIPLOMATICA (Italy)
IT_DESIS TESS. S.I.S.D.E. (Italy)
IT_EIMIL TESS. MILITARE E.I. (Italy)
IT_EISOT TESS. SOTTUFFICIALI E.I. (Italy)
IT_EIUFF TESS. UFFICIALI E.I. (Italy)
IT_GFMIL TESS. APP.TO FINANZIERE (Italy)
IT_GFSOT TESS. SOTT.LI G.D.F. (Italy)
IT_GFTRI TESS. POL. TRIB. G.D.F. (Italy)
IT_GFUFF TESS. UFFICIALI G.D.F. (Italy)
IT_IDELE CARTA IDENTITA' ELETTRONICA (Italy)
IT_IDENT CARTA DI IDENTITA' (Italy)
IT_MAGIS TESS. PERS. MAGISTRATI (Italy)
IT_MMMIL TESS. MILIT. M.M. (Italy)
IT_MMSOT TESS. SOTTUFICIALI M.M. (Italy)
IT_MMUFF TESS. UFFICIALI M.M. (Italy)
IT_PARLA TESS. PARLAMENTARI (Italy)
IT_PASDI PASSAPORTO DIPLOMATICO (Italy)
IT_PASOR PASSAPORTO ORDINARIO (Italy)
IT_PASSE PASSAPORTO DI SERVIZIO (Italy)
IT_PATEN PATENTE DI GUIDA (Italy)
IT_PATNA PATENTE NAUTICA (Italy)
IT_PORM1 PORTO FUCILE USO CACCIA (Italy)
IT_PORM2 PORTO FUCILE DIF. PERSON. (Italy)
IT_PORM3 PORTO D'ARMI USO SPORTIVO (Italy)
IT_PORM4 PORTO PISTOLA DIF. PERSON (Italy)
IT_PORM5 PORTO D'ARMI GUARDIE GIUR (Italy)
IT_PPAGE TESS. AGENTI/ASS.TI P.P. (Italy)
IT_PPISP TESS. ISPETTORI P.P. (Italy)
IT_PPSOV TESS. SOVRINTENDENTI P.P. (Italy)
IT_PPUFF TESS. UFFICIALI P.P. (Italy)
IT_PSAPP TESS. AGENTI/ASS.TI P.S. (Italy)
IT_PSFEM TESS. POLIZIA FEMMINILE (Italy)
IT_PSFUN TESS. FUNZIONARI P.S. (Italy)
IT_PSISP TESS. ISPETTORI P.S. (Italy)
IT_PSSOT TESS. SOVRINTENDENTI P.S. (Italy)
IT_PSUFF TESS. UFFICIALI P.S. (Italy)
IT_RIFUG TITOLO VIAGGIO RIF.POLIT. (Italy)
IT_SDMIL TESS. MILIT. TRUPPA SISMI (Italy)
IT_SDSOT TESS. SOTTUFFICIALI SISMI (Italy)
IT_SDUFF TESS. UFFICIALI SISMI (Italy)
IT_TEAMC TESS. ISCR. ALBO MED/CHI. (Italy)
IT_TEAOD TESS. ISCRIZ. ALBO ODONT. (Italy)
IT_TECAM TES. UNICO PER LA CAMERA (Italy)
IT_TECOC TESS. CORTE DEI CONTI (Italy)
IT_TEDOG TES.DOGANALE RIL.MIN.FIN. (Italy)
IT_TEFSE TESS. FERROV. SENATO (Italy)
IT_TEMPI TESS. MIN.PUBB.ISTRUZIONE (Italy)
IT_TENAT TESS. MILITARE NATO (Italy)
IT_TENAV TES. ENTE NAZ. ASSIS.VOLO (Italy)
IT_TEPOL TESS.MIN.POLIT.AGRIC.FOR. (Italy)
IT_TESAE TESS. MIN. AFFARI ESTERI (Italy)
IT_TESAR TESS.ISCR.ALBO ARCHITETTI (Italy)
IT_TESAV TESSERA ISCR. ALBO AVVOC. (Italy)
IT_TESCA TESS. CORTE D'APPELLO (Italy)
IT_TESCS TESS. CONSIGLIO DI STATO (Italy)
IT_TESDI TESSERA RICONOSC. D.I.A. (Italy)
IT_TESEA TESS. MEMBRO EQUIP. AEREO (Italy)
IT_TESIN TESS.ISCR. ALBO INGEGNERI (Italy)
IT_TESLP TESS. MINISTERO LAVORI PU (Italy)
IT_TESMB TESS. MIN.BEN.E ATT.CULT. (Italy)
IT_TESMD TESS. MINISTERO DIFESA (Italy)
IT_TESMF TESS. MINISTERO FINANZE (Italy)
IT_TESMG TESS. MINISTERO GIUSTIZIA (Italy)
IT_TESMI TESS. MINISTERO INTERNO (Italy)
IT_TESMN TESS. MINIST. TRASP/NAVIG (Italy)
IT_TESMS TESS. MINISTERO SANITA' (Italy)
IT_TESMT TESS. MINISTERO TESORO (Italy)
IT_TESNO TESSERA DELL'ORDINE NOTAI (Italy)
IT_TESOG TESS. ORDINE GIORNALISTI (Italy)
IT_TESPC TESS. PRES.ZA CONS. MIN. (Italy)
IT_TESPI TESS. PUBBLICA ISTRUZIONE (Italy)
IT_TESPT TES. POSTE E TELECOMUNIC. (Italy)
IT_TESUN TESSERA U.N.U.C.I. (Italy)
IT_TETEL TESS. IDENTIF.TELECOM IT. (Italy)
IT_TFERD TES. FERROVIARIA DEPUTATI (Italy)
IT_TFEXD TES. FERROV. EX DEPUTATI (Italy)
IT_VIMIL TESS. APP.TO/VIG. URBANO (Italy)
IT_VISOT TESS. SOTT.LI VIG. URBANI (Italy)
IT_VIUFF TESS. UFF.LI VIG.URBANI (Italy)
IT_VVMIL TESS. APP.TO/VIG. VV.FF. (Italy)
IT_VVSOT TESS. SOTTUFF.LI VV.FF. (Italy)
IT_VVUFF TESS. UFFICIALI VV.FF. (Italy)
PT_B Identity Card (Portugal)
PT_P Passport (Portugal)
PT_O Other (Portugal)

Guest's fields related to the reservation:

Field Type Description
next_destination Location optional Next guest's destination
arrived_from Location optional Arrived from destination

To create or update the fields listed above, "reservation_id" or "guest_group_id" is required.

Get a guest

curl -X GET \
  https://a.chekin.io/api/v3/guests/{{GUEST_ID}}/ \
  -H 'Authorization: JWT {{TOKEN}}' \
  -H 'Content-Type: application/json'

import requests

url = "https://a.chekin.io/api/v3/guests/{{GUEST_ID}}/"

headers = {
    "Content-Type": "application/json",
    "Authorization": "JWT {{TOKEN}}",
}

response = requests.request("GET", url, headers=headers)

To get a guest make a GET request to the /api/v3/guests/:id/ endpoint with specified guest ID.

Create a guest group

A guest_group - a group of one or several guests that are coming together within a single reservation.

curl -X POST \
  https://a.chekin.io/api/v3/guest-groups/ \
  -H 'Authorization: JWT {{TOKEN}}' \
  -H 'Content-Type: application/json' \
  -d '{
    "number_of_guests": 2,
    "members": [
        {
            "name": "John Doe",
            "gender": "M"
        },
        {
            "name": "Jane Doe",
            "gender": "F"
        }
    ]
}'

import requests

url = "https://a.chekin.io/api/v3/guest-groups/"

payload = {
    "number_of_guests": 2,
    "members": [
        {
            "name": "John Doe",
            "gender": "M"
        },
        {
            "name": "Jane Doe",
            "gender": "F"
        }
    ]
}

headers = {
    "Content-Type": "application/json",
    "Authorization": "JWT {{TOKEN}}",
}

response = requests.request("POST", url, data=payload, headers=headers)

Guest group fields

Field Type Description
number_of_guests integer optional Expected number of guests, can be greater than added with members list, is 1 by default
members List<Guest> mandatory List of Guest JSON-serialized instances
leader_id ID optional ID of a guest who is a leader of the group. If not not specified the first guest in the list will be marked as a leader
type Enum<GuestGroupType> optional Type of the guest group

Guest group types

Code Name Description
S Single "Group" of one person
G Group Regular group
F Family Family, group of relative

Update a guest

curl -X PATCH \
  https://a.chekin.io/api/v3/guests/{{GUEST_ID}}/ \
  -H 'Authorization: JWT {{TOKEN}}' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "New name",
    "document": {
        "type": "P",
        "number": "123456",
        "issue_date": "2015-01-01"
    }
}'

import requests

url = "https://a.chekin.io/api/v3/guests/{{GUEST_ID}}/"

headers = {
    'Content-Type': "application/json",
    'Authorization': "JWT {{TOKEN}}",
}

payload = {
    "name": "New name",
    "document": {
        "type": "P",
        "number": "123456",
        "issue_date": "2015-01-01"
    }
}

response = requests.request("PATCH", url, data=payload, headers=headers)

To update a guest info you can make a PATCH request to /api/v3/housings/{{GUEST_ID}}/ with payload containing set of field as described in section Create a guest.

Delete a guest

curl -X DELETE \
  https://a.chekin.io/api/v3/guests/c2fcc7a252e64a23b4cd4111a22874f0/ \
  -H 'Authorization: JWT {{TOKEN}}'

import requests

url = "https://a.chekin.io/api/v3/guests/c2fcc7a252e64a23b4cd4111a22874f0/"

headers = {
    'Authorization': "JWT {{TOKEN}}",
}

response = requests.request("DELETE", url, headers=headers)

To unsubscribe make a DELETE request to the /api/v3/guests/{id}/ endpoint.

Country-Specific Guest Data

There can be different sets of fields required to register a guest (or a guest group) in police. Below, you can see the required guest information specific for various countries supported by Chekin.

Austria (g)

Field Required for the group leader Required for the group members
guest.name Yes Yes
guest.surname Yes Yes
guest.gender Yes No
guest.nationality Yes No
guest.birth_date Yes Yes
guest.residence (including country, city, address, postal code) Yes No
document.type Yes No
document.number Yes No
document.date_of_issue Yes No
document.issue_place (including country) Yes No
guest.signature Yes No

Belgium (g)

Field Description
guest.name Name
guest.surname Surname
guest.nationality Nationality
guest.birth_date Birth Date
guest.residence Location instance including country; city and address are optional
document.type Document Type
document.number Document Number
guest.signature Signature

Czech Republic (g)

Field Description
guest.name Name
guest.surname Surname
guest.nationality Nationality
guest.birth_date Birth Date
guest.residence Location instance including country, city, and address
document.type Document Type
document.number Document Number
document.type Field for non-EU citizens; has the value 'V' (for Visa)
document.number Visa number for non-EU citizens
guest.purpose_of_stay The purpose of stay
guest.signature Signature

Colombia (g)

You can register only foreign (not colombian) guests (colombian guests will not be sent in the police)

To register a guest in the police for housing located in Colombia there must be the following info provided:

Field Description
guest.name Name
guest.surname Surname
guest.second_surname Second Surname, optional
guest.nationality Nationality
guest.birth_date Birth Date
guest.arrived_from Location instance (including country; department and municipality are required only if the country the guest arrived from is Colombia)
guest.next_destination Location instance (including country; department and municipality are required only if the country the guest arrived from is Colombia)
document.type Document Type
document.number Document Number
guest.signature Signature, optional

France (g)

Field Description
guest.name Name
guest.surname Surname
guest.nationality Nationality
guest.birth_date Birth Date
guest.birth_place Location instance
guest.residence Location instance including country and address
guest.phone Guest phone number, optional field
guest.email Guest email, optional field
guest.signature Signature

Germany (g)

Field Description
guest.name Name
guest.surname Surname
guest.nationality Nationality
guest.birth_date Birth Date
guest.residence Location instance including country, city, and address. The address is optional here
document.type Document Type
document.number Document Number
guest.signature Signature

Greece (g)

Field Description
guest.name Name
guest.surname Surname
guest.gender Sex
guest.nationality Nationality
guest.birth_date Birth Date
guest.residence Location instance including (including country, city, address, postal code)
guest.phone Guest phone number
guest.email Guest email
document.type Document Type
document.number Document Number
document.date_of_issue Document date of issue
document.issue_place Location instance including country and city
guest.signature Signature

Italy (g)

Field Required for the group leader Required for the group members
guest.name Yes Yes
guest.surname Yes Yes
guest.gender Yes Yes
guest.nationality Yes Yes
guest.residence Yes Yes
guest.birth_date Yes Yes
guest.birth_place Yes Yes
document.type Yes No
document.number Yes No
document.issue_place Yes No

The location object of the guest.residence is expected to be:

Residence country Location object
Italy Country + Italian city
Other country Country

The location object of the document.issue_place is expected to be:

Issue country Location object
Italy Country + Italian city
Other country Country

Netherlands (g)

Field Description
guest.name Name
guest.surname Surname
guest.nationality Nationality
guest.birth_date Birth Date
guest.residence Location instance including country, city, and address
document.type Document Type
document.number Document Number
guest.signature Signature

Portugal (g)

Field Description
guest.name Name
guest.surname Surname
guest.nationality Nationality
guest.birth_date Birth Date
guest.birth_place Location instance including country; optional field
guest.residence Location instance including country
document.type Document Type
document.number Document Number
document.issue_place Location instance including country
guest.signature Signature

Romania (g)

Field Description
guest.name Name
guest.surname Surname
guest.nationality Nationality
guest.birth_date Birth Date
guest.birth_place Location instance including country, and city
guest.residence Location instance including country, city, and address
document.type Document Type
document.number Document Number
guest.purpose_of_stay The purpose of stay (BUSINESS or TOURISM)
guest.signature Signature

Spain (g)

To register a guest in police for housing located in Spain there must be the following info provided:

Field Description
guest.name Name
guest.surname Surname
guest.second_surname Second Surname, required if the nationality is Spanish
guest.gender Sex
guest.nationality Nationality
guest.birth_date Birth Date
document.type Document Type
document.number Document Number
document.date_of_issue Document date of issue
guest.signature Signature

Thailand (g)

Field Description
guest.name Name
guest.surname Surname
guest.gender Sex
guest.nationality Nationality
guest.birth_date Birth Date
document.number Document Number
document.front_side_scan Scan of the front side of the document

United Arab Emirates (g)

Field Description
guest.name Name
guest.surname Surname
guest.nationality Nationality
guest.birth_date Birth Date
document.number Document Number
document.front_side_scan Scan of the front side of the document
document.back_side_scan Scan of the back side of the document
guest.phone Guest phone number; optional field
guest.email Guest email; optional field

United Kingdom (g)

Field Required for the guests from UK Required for the foreign guests
guest.first_name Yes Yes
guest.last_name Yes Yes
guest.nationality Yes Yes
document.type No Yes
document.number No Yes
document.issue_place No Yes
guest.next_destination.country No Yes
guest.next_destination.address No No
guest.signature Yes Yes

Documents

This section contains information about the documents generated by police.

Get a list of police receipts for a housing for a specific year:


GET https://a.chekin.io/api/v3/police-receipts/?housing={HOUSING_ID}&year={YEAR}```

Example of response:

[{"id":"79f637919945433f97ed32eafb6bf602","police_type":"ISP","housing":"9ec6767e-a22d-4d3e-bebc-1ec3de1033c1","owner":"4e46927b-daae-4cbe-997a-08949df2f17e","protocol_number":"201900203589-SA","protocol_date":"2019-10-16","registered_guests_num":4}]

Get a list of police receipts for a housing for a specific police type

GET https//a.chekin.io/api/v3/police-receipts//?housing={HOUSING_ID}&police_type={POLICE_TYPE}```

Check the code of your police account type in the corresponding paragraph.

Get a list of police receipts for a housing for a specific police account

GET https//a.chekin.io/api/v3/police-receipts//?housing={HOUSING_ID}&police_account={POLICE_ACCOUNT_ID}```

RECEIPT_ID is the ID received in response to a GET request to retrieve the list of receipts. E.g. "id":"79f637919945433f97ed32eafb6bf602".

GET https://a.chekin.io/api/v3/italian-police-receipts/{RECEIPT_ID}/```

Example of response:

{"link":"https://police-receipts-prod-ng.s3.amazonaws.com/police_receipts/alloggiati/6fb8f3da53054cb88093a76fbe337e0d/2019/10/201900203589-SA.zip?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AQWERTYIHUC2INBTUP%2F20191223%2Feu-central-1%2Fs3%2Faws4_request&X-Amz-Date=20191223T123119Z&X-Amz-Expires=1800&X-Amz-SignedHeaders=host&X-Amz-Signature=00859934d6cce54362ed0592e0396d4fddce1e5cb6d42321185a5e3fd446f3157"} 

GET https://a.chekin.io/api/v3/italian-police-receipts/download-all/{HOUSING_ID}/{YEAR}/ ```

Example of response:

{"link":"https://police-receipts-prod-ng.s3.amazonaws.com/police_receipts/alloggiati/6fb8f3da53054cb88093a76fbe337e0d/2019/2019-9ec6767ea22d4d3ebebc1ec3de1033c1.zip?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=QWERTYDLIHUC2INBTUP%2F20191223%2Feu-central-1%2Fs3%2Faws4_request&X-Amz-Date=20191223T123222Z&X-Amz-Expires=1800&X-Amz-SignedHeaders=host&X-Amz-Signature=c9d2a8661347ff940e709b2852a426d7cd51de82a987e3ace82a99f0a3c0051e"}

Entry form

Entry form - a form with guest data; a document generated by Chekin that managers must store for a specific time, according to the legislation of the country where the housing is situated.

Download an entry form

To get a link to the entry form for a specific guest, make a GET request to the https://a.chekin.io/api/v3/documents/entry-forms/reservation=id&guest=id endpoint.

In response, you'll receive the data of the guest and a link to the entry form PDF file.

curl -x GET \
  https://a.chekin.io/api/v3/documents/entry-forms/reservation=id&guest=id \
  -H 'Authorization: JWT {{TOKEN}}' \
  -H 'Content-Type: application/json'

Police accounts

A police_account – is an entity which contains data required to login into police site management dashboard. The set of fields is specific for each country and police type.

Create a police account

curl -X POST \
  https://a.chekin.io/api/v3/police-accounts/ \
  -H 'Authorization: JWT {{TOKEN}}' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "FAKE",
    "username": "Fake police account",
    "password": "secret"
}'

import requests

url = "https://a.chekin.io/api/v3/police-accounts/"

payload = {
    "type": "FAKE",
    "username": "Fake police account",
    "password": "secret"
}

headers = {
    'Content-Type': "application/json",
    'Authorization': "JWT {{TOKEN}}",
}

response = requests.request("POST", url, data=payload, headers=headers)

To create a police account record via API you should make a POST request with parameters type, username and password, and some other optional parameters described below.

Field Type Description
type Enum<PoliceAccountType> required
username string required the username used to login to the police website
password string required the password used to login to the police website
certificate_password string optional, used for Italy only the password of the certificate which is usually the same as the user password
establishment_number string optional, used for Portugal only an extra number provided by the police to do login
username_type Enum<UsernameType> optional, used for Colombia only an extra field provided by the police to do login
external_name string optional an extra value provided by the police
external_id string optional an extra ID provided by the police
local_send_time string optional time in housing timezone for auto starting police registration (used only hours, default "23:00:00")
delay Enum<PoliceAccountDelay> delay of auto starting police registration (default "THIS_DAY")

Police account types

The types of police currently supported:

Code Country Description Check-out action
FAKE ES Fake police account (for testing) NO
POL ES National Police Corps of Spain NO
NAT ES Spanish Civil Guard NO
MOS ES Police of the Generalitat of Catalonia (Spain) NO
ERT ES People's Guard (Basque, Spain) NO
ISP IT Italian State Police NO
SEF PT Foreigners and Borders Service (Portugal) NO
UHH AE UAE Holiday Homes YES
COL CO Colombia SIRE YES
CUP CZ Czech Uby Port NO
THAI TH Thailand police NO

Police account delay

Allow to make an offset of sending data to police

Code Description
THIS_DAY Start police registration on the check-in day at the time specified in housing
NEXT_DAY Start police registration on the next day after check-in at the time specified in housing

Police account username types

Code Description
CO_ID Local ID
CO_FID Foreigner ID

Police account validation

Allow to validate police credentials and retrieve list of subhouse names and codes.

Create a validation task

curl -X POST \
  https://a.chekin.io/api/v3/police-account-validation/ \
  -H 'Authorization: JWT {{TOKEN}}' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "FAKE",
    "username": "Fake police account",
    "password": "secret"
}'

import requests

url = "https://a.chekin.io/api/v3/police-account-validation/"

payload = {
    "type": "FAKE",
    "username": "Fake police account",
    "password": "secret"
}

headers = {
    'Content-Type': "application/json",
    'Authorization': "JWT {{TOKEN}}",
}

response = requests.request("POST", url, data=payload, headers=headers)

Get result

curl -X GET \
  https://a.chekin.io/api/v3/police-account-validation/{{TASK_ID}}/ \
  -H 'Authorization: JWT {{TOKEN}}' \
  -H 'Content-Type: application/json'

import requests

url = "https://a.chekin.io/api/v3/police-account-validation/{{TASK_ID}}/"

headers = {
    "Content-Type": "application/json",
    "Authorization": "JWT {{TOKEN}}",
}

response = requests.request("GET", url, headers=headers)

Validation in progress

{
    "id": "69fbf265858246c3b1516ba3ec6d42e6",
    "detail": "Verification in progress, please check again a bit later",
    "status": "IN_PROGRESS"
}

Validation completed successfully

{
    "id": "69fbf265858246c3b1516ba3ec6d42e6",
    "detail": "Verification complete",
    "status": "COMPLETE",
    "is_successful_login": true,
    "has_multiple_houses": true,
    "external_housings_data": [
    {
        "subhouse_code": "code1",
        "subhouse_name": "name1"
    },
    {
        "subhouse_code": "code2",
        "subhouse_name": "name2"
    }]
}

Validation failed

{
    "id": "69fbf265858246c3b1516ba3ec6d42e6",
    "detail": "Verification complete",
    "status": "COMPLETE",
    "is_successful_login": false,
    "has_multiple_houses": false,
    "external_housings_data": []
}

Stat accounts

A stat_account – is an entity which contains data required to login into statics site dashboard. The set of fields is specific for each country and stat type.

If stat_account is specified the app will send statistics data at the datetime related to stat type: - for aggregated type data will be send once a day in correspondence to StatAccountDelay specified - for police-like type data will be send within 6 hours after check-in

Create a stat account

curl -X POST \
  https://a.chekin.io/api/v3/stat-accounts/ \
  -H 'Authorization: JWT {{TOKEN}}' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "FAKE",
    "username": "Fake stat account",
    "password": "secret"
}'

import requests

url = "https://a.chekin.io/api/v3/stat-accounts/"

payload = {
    "type": "FAKE",
    "username": "Fake police account",
    "password": "secret"
}

headers = {
    'Content-Type': "application/json",
    'Authorization': "JWT {{TOKEN}}",
}

response = requests.request("POST", url, data=payload, headers=headers)

To create a stat account record via API you should send the post request with parameters type, username and password, and some other optional parameters described below.

Field Type Description
type Enum<StatAccountType> required
username string required the username used to login to the stat website
password string required the password used to login to the stat website
external_housing_id string optional Housing id in STAT system
external_location_id string semi-optional City code for STATs DEID, ITSA, ITTO, ITT3
delay Enum<StatAccountDelay> delay of sending data to STAT service (default "ONE_DAY"). Used for aggregated STAT types
send_time time in UTC timezone for sending data (used only hours, default "06:00:00")

Additional fields for Statistics in Italy

The following extra fields are mandatory for specific stats. TRUE stands for mandatory, FALSE stands for non-mandatory.

Field Abruzzo Turismo 5 Campania EPT Campano Emilia Romagna Turismo 5 Friuli Venezia Giulia WebTur Lazio RADAR Lombardia Turismo 5 Marche Statistica Turismo Marche Piemonte ROSS 1000 Sardegna SiRED Sicilia OCR Toscana Ricestat Toscana Turismo 5 Trento STU Valtellina Abit Veneto MT Web
housing.stat_account.type TRUE TRUE TRUE N/A TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE
housing.rooms_quantity TRUE FALSE TRUE N/A TRUE TRUE TRUE TRUE TRUE FALSE FALSE TRUE TRUE FALSE FALSE
housing.stat_account.external_location_id FALSE FALSE FALSE N/A FALSE FALSE FALSE FALSE TRUE TRUE TRUE TRUE FALSE FALSE FALSE
housing.stat_account.username TRUE TRUE TRUE N/A TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE
housing.stat_account.password TRUE TRUE TRUE N/A TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE
housing.stat_account.external_housing_id TRUE FALSE TRUE N/A FALSE TRUE TRUE TRUE TRUE FALSE FALSE TRUE TRUE TRUE TRUE
reservation.guest_group_type (Single/Group/Family) TRUE FALSE TRUE N/A FALSE TRUE TRUE TRUE TRUE TRUE FALSE TRUE FALSE FALSE FALSE
reservation.occupied_rooms_quantity TRUE FALSE TRUE N/A TRUE TRUE TRUE TRUE TRUE FALSE FALSE TRUE TRUE FALSE FALSE
reservation.external_room_id FALSE FALSE FALSE N/A FALSE FALSE FALSE FALSE FALSE TRUE TRUE FALSE FALSE FALSE FALSE
guest.residence.country TRUE TRUE TRUE N/A TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE
guest.residence.city TRUE TRUE TRUE N/A TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE
guest.tax_exemption FALSE FALSE FALSE N/A FALSE FALSE FALSE FALSE FALSE FALSE FALSE FALSE FALSE OPTIONAL FALSE

Stat account types

The types of stat currently supported:

Code Name Country Type Description
FAKE FAKE Fake stat account (for testing)
ITAB IT_ABRUZZO IT police-like Abruzzo - Turismo 5
ITCA IT_CAMPANIA IT aggregated Campania - EPT Campano
ITER IT_EMILIA_ROMAGNA IT police-like Emilia Romagna - Turismo 5
ITLO IT_LOMBARDIA IT police-like Lombardia - Turismo 5
ITMA IT_MARCHE IT police-like Marche - Statistica Turismo Marche
ITPI IT_PIEMONTE IT police-like Piemonte - ROSS 1000
ITRA IT_RADAR IT aggregated Lazio - RADAR
ITSA IT_SARDEGNA IT police-like Sardegna - SiRED
ITSI IT_SICILIA IT aggregated Sicilia - OCR
ITTO IT_TOSCANA_RICESTAT IT police-like Toscana - Ricestat
ITT3 IT_TOSCANA_TURISMO5 IT police-like Toscana - Turismo 5
ITTR IT_TRENTINO_STU IT aggregated Trento - STU
ITVA IT_VALTELLINA IT aggregated Valtellina - Abit
ITVE IT_VENETO IT aggregated Veneto - MT Web
DEID DE_IDEV DE aggregated Germany IDEV stat account

Stat account delay

Allow to make an offset of sending data to STAT service

Code Description
ONE_DAY Data will be send on the next day after check-in and after check-out
TWO_DAYS Data will be send on two days after check-in and after check-out
THREE_DAYS Data will be send on three days after check-in and after check-out

External location IDs

Stat Type IT_SARDEGNA

Code Name
iw_ca Cagliari
iw_ci Ministero degli Affari Esteri
iw_nu Nuoro
iw_og Ogliastra
iw_ot Olbia Tempo
iw_or Oristano
iw_vs Regione Autonoma Della Sardegna
iw_ss Sassari

Stat Type IT_TOSCANA_RICESTAT

Code Name
Arezzo Arezzo
Grosseto Grosseto
Livorno Livorno
Lucca Lucca
Massa Carrara Massa Carrara
Pisa Pisa
Siena Siena

Stat Type IT_TOSCANA_TURISMO5

Code Name
Firenze Firenze
Prato Prato
Pistoia Pistoia

Stat Type DE_IDEV

Code Name
bundesamt Bundesamt
baden-württemberg Baden-Württemberg
bayern Bayern
berlin Berlin
brandenburg Brandenburg
bremen Bremen
hamburg Hamburg
hessen Hessen
mecklenburg-vorpommern Mecklenburg-Vorpommern
niedersachsen Niedersachsen
nordrhein-westfalen Nordrhein-Westfalen
rheinland-pfalz Rheinland-Pfalz
saarland Saarland
sachsen Sachsen
sachsen-anhalt Sachsen-Anhalt
schleswig-holstein Schleswig-Holstein
thueringen Thueringen

Stat account validation

Allow to validate stat credentials and retrieve list of subhouse names and codes.

Create a validation task

curl -X POST \
  https://a.chekin.io/api/v3/stat-account-validation/ \
  -H 'Authorization: JWT {{TOKEN}}' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "FAKE",
    "username": "Fake stat account",
    "password": "secret"
}'

import requests

url = "https://a.chekin.io/api/v3/stat-account-validation/"

payload = {
    "type": "FAKE",
    "username": "Fake stat account",
    "password": "secret"
}

headers = {
    'Content-Type': "application/json",
    'Authorization': "JWT {{TOKEN}}",
}

response = requests.request("POST", url, data=payload, headers=headers)

Get result

curl -X GET \
  https://a.chekin.io/api/v3/stat-account-validation/{{TASK_ID}}/ \
  -H 'Authorization: JWT {{TOKEN}}' \
  -H 'Content-Type: application/json'

import requests

url = "https://a.chekin.io/api/v3/stat-account-validation/{{TASK_ID}}/"

headers = {
    "Content-Type": "application/json",
    "Authorization": "JWT {{TOKEN}}",
}

response = requests.request("GET", url, headers=headers)

Validation in progress

{
    "id": "69fbf265858246c3b1516ba3ec6d42e6",
    "detail": "Verification in progress, please check again a bit later",
    "status": "IN_PROGRESS"
}

Validation completed successfully

{
    "id": "69fbf265858246c3b1516ba3ec6d42e6",
    "detail": "Verification complete",
    "status": "COMPLETE",
    "is_successful_login": true,
    "has_multiple_houses": true,
    "external_housings_data": [
    {
        "subhouse_code": "code1",
        "subhouse_name": "name1"
    },
    {
        "subhouse_code": "code2",
        "subhouse_name": "name2"
    }]
}

Validation failed

{
    "id": "69fbf265858246c3b1516ba3ec6d42e6",
    "detail": "Verification complete",
    "status": "COMPLETE",
    "is_successful_login": false,
    "has_multiple_houses": false,
    "external_housings_data": []
}

Tax calculator

To get taxes you have to specify a bunch of fields common for every location and some fields that are required for a specific region or province. Check the sections below to get details. Important: the calculator supports age exemptions only. So you don't need pass people with other exemptions kinds to the calculator.

The common fields are:

In response you'll get two additional fields: tax and currency which will contain amount of tax and currency code (like EUR)

Get taxes for Austria

curl -X POST \
  https://a.chekin.io/api/v3/tax/calculation/ \
  -H 'Authorization: JWT {{TOKEN}}' \
  -H 'Content-Type: application/json' \
  -d '{
    "country_id": "AT",
    "property_type_id": "a4aafe73-2a51-44c9-ad64-a8ad78d9bbe5",  
    "date": "2019-01-01",
    "location_id": "fce69e07-1712-4346-a874-cd5ac4fe79f2",
    "birth_dates": ["1999-04-23", "2007-04-22"],
    "nights_number": 1
}'

The above command returns JSON structured like this:

{
    "country_id": "AT",
    "property_type_id": "a4aafe73-2a51-44c9-ad64-a8ad78d9bbe5",
    "date": "2019-01-01",   
    "location_id": "fce69e07-1712-4346-a874-cd5ac4fe79f2",
    "nights_number": 1,
    "tax": 1.5,
    "currency": "EUR",
    "ages": [
        20,
        12
    ],
    "birth_dates": [
        "1999-04-23",
        "2007-04-22"
    ]
}

The fields you have to specify to get tax calculation for Austria are:

Required only for Wien:

Additional field ages will be added to response if birth_dates are specified.

Get taxes for Belgium

curl -X POST \
  https://a.chekin.io/api/v3/tax/calculation/ \
  -H 'Authorization: JWT {{TOKEN}}' \
  -H 'Content-Type: application/json' \
  -d '{
    "country_id": "BE",
    "nights_number": 3,
    "property_type_id": "2b736048-086f-4f30-a911-aef9a806afe5", 
    "location_id": "bf371245ba1d4c7d81fed49c72b451e4",
    "ages": [22, 22, 22, 11, 14, 17]
}'

The above command returns JSON structured like this:

{
    "property_type_id": "2b736048-086f-4f30-a911-aef9a806afe5",
    "country_id": "BE",
    "location_id": "bf371245-ba1d-4c7d-81fe-d49c72b451e4",
    "nights_number": 3,
    "tax": 2.52,
    "currency": "EUR",
    "ages": [
        22,
        22,
        22,
        11,
        14,
        17
    ]
}

The fields you have to specify to get tax calculation for Belgium are:

Additional field ages will be added to response if birth_dates are specified.

Get taxes for Czech Republic

curl -X POST \
  https://a.chekin.io/api/v3/tax/calculation/ \
  -H 'Authorization: JWT {{TOKEN}}' \
  -H 'Content-Type: application/json' \
  -d '{
    "country_id": "CZ",
    "property_type_id": "cde76767-2f2d-48af-9dce-6ec5d05b0c5e",
    "location_id": "7126fc823c0d4089bf424b528ebc7732",
    "ages": [40, 37, 17],
    "nights_number": 1
}'

The above command returns JSON structured like this:

{
    "property_type_id": "cde76767-2f2d-48af-9dce-6ec5d05b0c5e",
    "country_id": "CZ",
    "location_id": "7126fc82-3c0d-4089-bf42-4b528ebc7732",
    "nights_number": 1,
    "tax": 12.0,
    "currency": "CZK",
    "ages": [
        40,
        37,
        17
    ]
}

The fields you have to specify to get tax calculation for Czech Republic are:

Additional field ages will be added to response if birth_dates are specified.

Get taxes for France

curl -X POST \
  https://a.chekin.io/api/v3/tax/calculation/ \
  -H 'Authorization: JWT {{TOKEN}}' \
  -H 'Content-Type: application/json' \
  -d '{
    "country_id": "FR",
    "nights_number": 3,
    "property_type_id": "71af30c7-ad68-41e7-887b-d4ab68058f37", 
    "location_id": "2a92aa00-1b62-4658-a118-c845223c44b8",
    "ages": [18, 11],
    "cost_per_night": 160,
    "date": "2019-1-1"
}'

The above command returns JSON structured like this:

{
    "property_type_id": "71af30c7-ad68-41e7-887b-d4ab68058f37",
    "date": "2019-01-01",
    "country_id": "FR",
    "location_id": "2a92aa00-1b62-4658-a118-c845223c44b8",
    "nights_number": 3,
    "tax": 5.62,
    "currency": "EUR",
    "ages": [
        18,
        11
    ],
    "cost_per_night": "160.00"
}

The fields you have to specify to get tax calculation for France are:

Get taxes for Germany

Request when enable_total_price is false:

curl -X POST \
  https://a.chekin.io/api/v3/tax/calculation/ \
  -H 'Authorization: JWT {{TOKEN}}' \
  -H 'Content-Type: application/json' \
  -d '{
    "country_id": "DE",
    "property_type_id": "41d5af67-dc8f-419d-92ed-ac60b4552bb8",
    "location_id": "28e9ca90-2417-4133-b7c1-9b165bf32a40",
    "ages": [20, 6],
    "nights_number": 4,
    "date": "2019-10-31"
}'

The above command returns JSON structured like this:

{
    "property_type_id": "c6e12ea3-7d6a-4222-8418-b7a8f95ec19a",
    "date": "2019-12-13",
    "country_id": "DE",
    "location_id": "25d026da-1d4d-4834-8177-25fd5b16040d",
    "nights_number": 3,
    "tax": 2.25,
    "vat": 0.16,
    "total_fee": 2.41,
    "currency": "EUR",
    "ages": [
        20,
        14
    ]
}

Request when enable_total_price is true:

curl -X POST \
  https://a.chekin.io/api/v3/tax/calculation/ \
  -H 'Authorization: JWT {{TOKEN}}' \
  -H 'Content-Type: application/json' \
  -d '{
    "country_id": "DE",
    "property_type_id": "c6e12ea3-7d6a-4222-8418-b7a8f95ec19a",
    "location_id": "99c62e122a8348538997d6ac7039bb12",
    "ages": [19, 10, 35],
    "nights_number": 30,
    "reservation_total_price": 45
}'

The above command returns JSON structured like this:

{
    "property_type_id": "c6e12ea3-7d6a-4222-8418-b7a8f95ec19a",
    "country_id": "DE",
    "location_id": "99c62e12-2a83-4853-8997-d6ac7039bb12",
    "nights_number": 30,
    "tax": 1.58,
    "vat": 0.11,
    "total_fee": 1.69,
    "currency": "EUR",
    "ages": [
        19,
        10,
        35
    ],
    "reservation_total_price": "45.00"
}

The fields you have to specify to get tax calculation for Germany are:

Additional field ages will be added to response if birth_dates are specified.

For locations where the enable_total_price field has the value true, only the following fields are required:

In this case, the tax is calculated using a percentage of the total reservation price

Get taxes for Hungary

Request when enable_total_price is false:

curl -X POST \
  https://a.chekin.io/api/v3/tax/calculation/ \
  -H 'Authorization: JWT {{TOKEN}}' \
  -H 'Content-Type: application/json' \
  -d '{
    "country_id": "HU",
    "property_type_id": "41d5af67-dc8f-419d-92ed-ac60b4552bb8",
    "location_id": "7f6f2faa81784c95b182eddd58c705b0",
    "birth_dates": ["1995-04-23", "2000-04-22"],
    "nights_number": 2
}'

The above command returns JSON structured like this:

{
    "property_type_id": "41d5af67-dc8f-419d-92ed-ac60b4552bb8",
    "country_id": "HU",
    "location_id": "7f6f2faa-8178-4c95-b182-eddd58c705b0",
    "nights_number": 2,
    "tax": 1200.0,
    "currency": "HUF",
    "ages": [
        24,
        19
    ],
    "birth_dates": [
        "1995-04-23",
        "2000-04-22"
    ]
}

Request when enable_total_price is true:

curl -X POST \
  https://a.chekin.io/api/v3/tax/calculation/ \
  -H 'Authorization: JWT {{TOKEN}}' \
  -H 'Content-Type: application/json' \
  -d '{
    "country_id": "HU",
    "property_type_id": "a4aafe73-2a51-44c9-ad64-a8ad78d9bbe5",
    "location_id": "d4d1dbec-8dba-4562-9c74-30abc5574632",
    "nights_number": 1,
    "reservation_total_price": 50000
}'

The above command returns JSON structured like this:

{
    "property_type_id": "a4aafe73-2a51-44c9-ad64-a8ad78d9bbe5",
    "country_id": "HU",
    "location_id": "7577dc1d-4605-4ae0-a9f1-e53090a88aab",
    "nights_number": 1,
    "tax": 2000.0,
    "currency": "HUF",
    "ages": [],
    "reservation_total_price": "50000.00"
}

The fields you have to specify to get tax calculation for Hungary are:

Additional field ages will be added to response if birth_dates are specified.

For locations where the enable_total_price field has the value true, only the following fields are required:

In this case, the tax is calculated using a percentage of the total reservation price

Get taxes for Netherlands

curl -X POST \
  https://a.chekin.io/api/v3/tax/calculation/ \
  -H 'Authorization: JWT {{TOKEN}}' \
  -H 'Content-Type: application/json' \
  -d '{
    "country_id": "NL",
    "nights_number": 5,
    "property_type_id": "67aa9203-99d6-4fdb-8213-ced902e1afa0", 
    "location_id": "46fde85807c04300807b253685229a2d",
    "ages": [17 ,7, 18],
    "cost_per_night": 30
}'

The above command returns JSON structured like this:

{
    "property_type_id": "67aa9203-99d6-4fdb-8213-ced902e1afa0",
    "country_id": "NL",
    "location_id": "46fde858-07c0-4300-807b-253685229a2d",
    "nights_number": 5,
    "tax": 10.5,
    "currency": "EUR",
    "ages": [
        17,
        7,
        18
    ],
     "cost_per_night": "30.00"
}

The fields you have to specify to get tax calculation for Netherlands are:

Get taxes for Italy

curl -X POST \
  https://a.chekin.io/api/v3/tax/calculation/ \
  -H 'Authorization: JWT {{TOKEN}}' \
  -H 'Content-Type: application/json' \
  -d '{
    "country_id": "IT",
    "property_type_id": "97c6973a-069b-49f0-ad68-5dbe3ff4189f",
    "property_subtype_id": "7095e023-98b4-435d-a52f-d9ebaab0fe58",
    "date": "2019-01-01",
    "location_id": "12c39879-bdb1-4f9a-8c92-cdfabb046596",
    "birth_dates": ["2007-04-23", "2007-04-22"],
    "nights_number": 1
}'

The above command returns JSON structured like this:

{
    "country_id": "IT",
    "property_type_id": "97c6973a-069b-49f0-ad68-5dbe3ff4189f",
    "property_subtype_id": "7095e023-98b4-435d-a52f-d9ebaab0fe58",
    "date": "2019-01-01",
    "location_id": "12c39879-bdb1-4f9a-8c92-cdfabb046596",
    "nights_number": 1,
    "ages": [
        12,
        12
    ],
    "birth_dates": [
        "2007-04-23",
        "2007-04-22"
    ],
    "tax": 4,
    "currency": "EUR"
}

The fields you have to specify to get tax calculation for Italy are:

Required only for Sassari and Châtillon:

Additional field ages will be added to response if birth_dates are specified.

Get taxes for Portugal

curl -X POST \
  https://a.chekin.io/api/v3/tax/calculation/ \
  -H 'Authorization: JWT {{TOKEN}}' \
  -H 'Content-Type: application/json' \
  -d '{
    "country_id": "PT",
    "date": "2019-01-01",
    "location_id": "bea00375-a792-48f7-a937-2c73ebab201c",
    "ages": [10, 12, 20],
    "nights_number": 1
}'

The above command returns JSON structured like this:

{
    "date": "2019-01-01",
    "country_id": "PT",
    "location_id": "bea00375-a792-48f7-a937-2c73ebab201c",
    "nights_number": 1,
    "tax": 1.5,
    "currency": "EUR",
    "ages": [
        10,
        20,
        12
    ]
}

The fields you have to specify to get tax calculation for Portugal are:

Additional field ages will be added to response if birth_dates are specified.

Get taxes for Spain

curl -X POST \
  https://a.chekin.io/api/v3/tax/calculation/ \
  -H 'Authorization: JWT {{TOKEN}}' \
  -H 'Content-Type: application/json' \
  -d '{
    "property_type_id": "675c0357-2226-47c5-8e5c-0f0ba0d30523",
    "province_id": "80dd1924-cd74-41c8-b9f2-3b18fe9ecedb",
    "region_id": "f787d9cc-e474-4c38-9388-cb04f08b67f9",
    "date": "2019-06-01",
    "country_id": "ES",
    "nights_number": 5,
    "total_people_number": 10,
    "young_people_number": 0
}'

The above command returns JSON structured like this:

{
    "property_type_id": "675c0357-2226-47c5-8e5c-0f0ba0d30523",
    "date": "2019-06-01",
    "country_id": "ES",
    "region_id": "f787d9cc-e474-4c38-9388-cb04f08b67f9",
    "province_id": "80dd1924-cd74-41c8-b9f2-3b18fe9ecedb",
    "total_people_number": 10,
    "young_people_number": 0,
    "nights_number": 5,
    "tax": 112.5,
    "iva": 11.25,
    "total_fee": 123.75,
    "currency": "EUR"
}

Necessary data

Property Types

Types are available at /api/v3/tax/property-types/ You can filter property types by country, you just need to add country param with ISO 2-alpha country code to your request. For example /api/v3/tax/property-types/?country=CZ

curl -X GET \
  https://a.chekin.io/api/v3/tax/property-types/?country=CZ \
  -H 'Authorization: JWT {{TOKEN}}' \
  -H 'Content-Type: application/json'

The above command returns JSON structured like this:

[
    {
        "id": "cde76767-2f2d-48af-9dce-6ec5d05b0c5e",
        "label": "GENERAL ACCOMMODATION",
        "region_id": null,
        "country_id": "CZ",
        "housing_type": "OTH"
    },
    {
        "id": "639a4e69-27c1-4ab7-a69d-f5684ce0270a",
        "label": "SPA/ACCOMMODATION",
        "region_id": null,
        "country_id": "CZ",
        "housing_type": "SPA"
    }
]

Property Subtypes

Subtypes are available at /api/v3/tax/property-subtypes/ You can filter property subtypes by country, you just need to add country param with ISO 2-alpha country code to your request. For example /api/v3/tax/property-subtypes/?country=IT

curl -X GET \
  https://a.chekin.io/api/v3/tax/property-subtypes/?country=IT \
  -H 'Authorization: JWT {{TOKEN}}' \
  -H 'Content-Type: application/json'

The above command returns JSON structured like this:

[
    {
        "id": "0e93e515-7dd8-4d85-8d5b-e77d7ad25a9d",
        "label": "1 star",
        "country_id": "IT"
    },
    {
        "id": "a8492f91-5dfd-416c-888d-57f529fac57a",
        "label": "2 star",
        "country_id": "IT"
    }
]

Geo Locations

Locations are available at /api/v3/tax/locations/ You can filter locations by country, you just need to add country param with ISO 2-alpha country code to your request. For example /api/v3/tax/locations/?country=IT

Additionally in the response we will have a field called enable_total_price that indicates if it is necessary to indicate the total price of the reservation.

curl -X GET \
  https://a.chekin.io/api/v3/tax/locations/?country=IT \
  -H 'Authorization: JWT {{TOKEN}}' \
  -H 'Content-Type: application/json'

The above command returns JSON structured like this:

[
    {
        "id": "8b644b29-ec8a-4f9e-9fa8-e4d004cb8584",
        "country": "IT",
        "region": "Basilicata",
        "province": null,
        "province_id": null,
        "city": "Matera",
        "enable_total_price": false
    },
    {
        "id": "cefa3dcd-104c-4bf2-ac6d-9e118a9ff09e",
        "country": "IT",
        "region": "Basilicata",
        "province": null,
        "province_id": null,
        "city": "Policoro",
        "enable_total_price": false
    }
]

curl -X GET \
  https://a.chekin.io/api/v3/tax/locations/?country=DE \
  -H 'Authorization: JWT {{TOKEN}}' \
  -H 'Content-Type: application/json'

The above command returns JSON structured like this when country is Germany:

[
    {
        "id": "6e955b93cee64f73b61a8d4082a617b1",
        "country": "DE",
        "region": "Bayern",
        "province": "",
        "province_id": "",
        "city": "Oberstdorf",
        "area": "AR1",
        "subarea": "",
        "district": "",
        "enable_total_price": false,
        "location_name": "Bayern--Oberstdorf-Area I-"
    },
    {
        "id": "10466748cc6e4496b36ee20a83f069ae",
        "country": "DE",
        "region": "Bayern",
        "province": "",
        "province_id": "",
        "city": "Rottach-Egern",
        "area": "AR1",
        "subarea": "",
        "district": "",
        "enable_total_price": false,
        "location_name": "Bayern--Rottach-Egern-Area I-"
    }
]

Regions and Provinces

You may need these entities to make a tax calculation for some location in Spain.

Regions are available at /api/v3/tax/regions/

curl -X GET \
  https://a.chekin.io/api/v3/tax/regions/ \
  -H 'Authorization: JWT {{TOKEN}}' \
  -H 'Content-Type: application/json'

The above command returns JSON structured like this:

[
    {
        "id": "9cd434b9-833c-4978-933d-430a3e279376",
        "name": "Balearic Islands",
        "country_id": "ES"
    },
    {
        "id": "f787d9cc-e474-4c38-9388-cb04f08b67f9",
        "name": "Catalonia",
        "country_id": "ES"
    }
]

And the provinces are available at /api/v3/tax/provinces/

curl -X GET \
  https://a.chekin.io/api/v3/tax/provinces/ \
  -H 'Authorization: JWT {{TOKEN}}' \
  -H 'Content-Type: application/json'

The above command returns JSON structured like this:

[
    {
        "id": "c10a258c-029f-40d4-b3df-cdb7d3334ab0",
        "region_id": "f787d9cc-e474-4c38-9388-cb04f08b67f9",
        "name": "Girona",
        "country_id": "ES"
    },
    {
        "id": "add4f783-821f-423c-8fba-5067270e5991",
        "region_id": "f787d9cc-e474-4c38-9388-cb04f08b67f9",
        "name": "Lleida",
        "country_id": "ES"
    }
]

Webhooks

Support notifications for events related to ISTAT and PoliceRegistration.

Notifications

CheKin will notify the subscribed system making a POST to the target url, sending an event object in JSON.

Retries:

If CheKin receives a response different from 200 (i.e. 500 Internal Error or 400 Bad Request) will retry 3 times as follows before giving up:

Subscription

curl -X POST \
  https://a.chekin.io/api/v3/webhooks/ \
  -H 'Authorization: JWT {{TOKEN}}' \
  -H 'Content-Type: application/json' \
  -d '{
    "target": "http://example.org/target-url/",
    "event": "PoliceRegistration.updated"
}'

import requests

url = "https://a.chekin.io/api/v3/webhooks/"

payload = {
    "target": "http://example.org/target-url/",
    "event": "PoliceRegistration.updated"
}

headers = {
    'Content-Type': "application/json",
    'Authorization': "JWT {{TOKEN}}",
}

response = requests.request("POST", url, data=payload, headers=headers)

To start receiving notifications of events you can make a post request to the url /api/v3/webhooks/ with the following payload with specified target and event, where event can take one of the values described below.

Optionally, you can specify a housing_id to subscribe to events related only to a certain housing.

Event Name
PoliceRegistration.created PoliceRegistration.created
PoliceRegistration.updated PoliceRegistration.updated
PoliceRegistration.deleted PoliceRegistration.deleted
PoliceRegistration.scheduled PoliceRegistration.scheduled
PoliceRegistration.progress PoliceRegistration.progress
PoliceRegistration.complete PoliceRegistration.complete
PoliceRegistration.error PoliceRegistration.error

The above command returns JSON structured like this:

{
    "id": "c2fcc7a252e64a23b4cd4111a22874f0",
    "event": "PoliceRegistration.updated",
    "target": "http://example.org/target-url/"
}
Event Name
StatRegistration.created StatRegistration.created
StatRegistration.updated StatRegistration.updated
StatRegistration.deleted StatRegistration.deleted
StatRegistration.scheduled StatRegistration.scheduled
StatRegistration.progress StatRegistration.progress
StatRegistration.complete StatRegistration.complete
StatRegistration.error StatRegistration.error

Guest.created is event when guest is added to reservation using CheKin Online

Event Name
Reservation.updated Reservation.updated
Guest.created Guest.created

Get a list of subscriptions

curl -X GET \
  https://a.chekin.io/api/v3/webhooks/ \
  -H 'Authorization: JWT {{TOKEN}}'

import requests

url = "https://a.chekin.io/api/v3/webhooks/"

headers = {
    'Authorization': "JWT {{TOKEN}}",
}

response = requests.request("GET", url, headers=headers)

To get a list of reservations make a GET request to the /api/v3/webhooks/ endpoint.

The above command returns JSON structured like this:

[
    {
        "id": "c2fcc7a252e64a23b4cd4111a22874f0",
        "event": "PoliceRegistration.updated",
        "target": "http://example.org/target-url/"
    },
    {
        "id": "4d6e8c1a28e04f269ff1c5f4c0c22e99",
        "event": "PoliceRegistration.updated",
        "target": "http://example.org/target-url/"
    }
]

Unsubscribe

curl -X DELETE \
  https://a.chekin.io/api/v3/webhooks/c2fcc7a252e64a23b4cd4111a22874f0/ \
  -H 'Authorization: JWT {{TOKEN}}'

import requests

url = "https://a.chekin.io/api/v3/webhooks/c2fcc7a252e64a23b4cd4111a22874f0/"

headers = {
    'Authorization': "JWT {{TOKEN}}",
}

response = requests.request("DELETE", url, headers=headers)

To unsubscribe make a DELETE request to the /api/v3/webhooks/{id}/ endpoint.

Sample webhook payloads

Webhook payload includes info about hook and a data related to event

StatRegistration.created

{
    "hook":
    {
        "id": "066a9ad2df864a678a5498464785abdc",
        "event": "StatRegistration.created",
        "target": "http://example.org/target-url/"
    },
    "data":
    {
        "reservation_id": "2e15d974507b4a6c96fdd452c53ccc36",
        "reservation_url": "https://a.chekin.io/api/v3/reservations/2e15d974507b4a6c96fdd452c53ccc36/"
    }
}

StatRegistration.scheduled

{
    "hook":
    {
        "id": "9e9b9051d4c9448db9a4c509293ce742",
        "event": "StatRegistration.scheduled",
        "target": "http://example.org/target-url/"
    },
    "data":
    {
        "reservation_id": "2e15d974507b4a6c96fdd452c53ccc36",
        "reservation_url": "https://a.chekin.io/api/v3/reservations/2e15d974507b4a6c96fdd452c53ccc36/"
    }
}

StatRegistration.complete

{
    "hook":
    {
        "id": "4eb005f25fad4942a5490f0052673da5",
        "event": "StatRegistration.complete",
        "target": "http://example.org/target-url/"
    },
    "data":
    {
        "reservation_id": "2e15d974507b4a6c96fdd452c53ccc36",
        "reservation_url": "https://a.chekin.io/api/v3/reservations/2e15d974507b4a6c96fdd452c53ccc36/"
    }
}

PoliceRegistration.created

{
    "hook":
    {
        "id": "7a615d96cefe4e7b9ad8c3d36fed8165",
        "event": "PoliceRegistration.created",
        "target": "http://example.org/target-url/"
    },
    "data":
    {
        "reservation_id": "936b7ba24f904efc90786d7a2ee0fa9d",
        "reservation_url": "https://a.chekin.io/api/v3/reservations/936b7ba24f904efc90786d7a2ee0fa9d/"
    }
}

PoliceRegistration.updated

{
    "hook":
    {
        "id": "2ee436128c154520abc05858caab3002",
        "event": "PoliceRegistration.updated",
        "target": "http://example.org/target-url/"
    },
    "data":
    {
        "reservation_id": "936b7ba24f904efc90786d7a2ee0fa9d",
        "reservation_url": "https://a.chekin.io/api/v3/reservations/936b7ba24f904efc90786d7a2ee0fa9d/"
    }
}

PoliceRegistration.error

{
    "hook":
    {
        "id": "fa52ddb28ca94ef29f3f2413e4157e7b",
        "event": "StatRegistration.error",
        "target": "http://example.org/target-url/"
    },
    "data":
    {
        "reservation_id": "936b7ba24f904efc90786d7a2ee0fa9d",
        "reservation_url": "https://a.chekin.io/api/v3/reservations/936b7ba24f904efc90786d7a2ee0fa9d/"
    }
}

Reservation.updated

{
    "hook":
    {
        "id": "aa60e0abfefb4d5caf8fb1e13aa0a50e",
        "event": "Reservation.updated",
        "target": "http://example.org/target-url/"
    },
    "data":
    {
        "reservation_id": "0f3a9d59da9c4fd8b6b4bf2906f124b9",
        "reservation_url": "https://a.chekin.io/api/v3/reservations/0f3a9d59da9c4fd8b6b4bf2906f124b9/"
    }
}

Guest.created

{
    "hook":
    {
        "id": "fab8af5dd0074d04a42395d00890c310",
        "event": "Guest.created",
        "target": "http://example.org/target-url/"
    },
    "data":
    {
        "reservation_id": "620186f602de439faffb6caa71b5014e",
        "guest_id": "6e9efa4cce764768a660e59caef36e54",
        "guest_origin": "CH_ONLINE"
    }
}

HMAC signature

curl -X POST \
  https://a.chekin.io/api/v3/webhooks/ \
  -H 'Authorization: JWT {{TOKEN}}' \
  -H 'Content-Type: application/json' \
  -d '{
    "target": "http://example.org/target-url/",
    "event": "PoliceRegistration.updated",
    "signature_secret": "some-secret-phrase"
}'

import requests

url = "https://a.chekin.io/api/v3/webhooks/"

payload = {
    "target": "http://example.org/target-url/",
    "event": "PoliceRegistration.updated",
    "signature_secret": "some-secret-phrase"
}

headers = {
    'Content-Type': "application/json",
    'Authorization': "JWT {{TOKEN}}",
}

response = requests.request("POST", url, data=payload, headers=headers)

Webhook request can be signed with a HMAC algorithm. To enable it you should specify a signature_secret during creating a subscription to the webhook. Add a signature_secret to the payload, and it will be used to calculate signature which will be sent within request headers as x-payload-signature.

Once you got a webhook request and have extracted a payload which can look like the following: {"hook": {"id": "ca44e691b78e4a10825f73d1bad0ef7b", "event": "Guest.created", "target": "https://example.org/hook/"}, "data": {"guest_id": "a98c3bbeb0b94d339ff36268d45be1c9", "reservation_id": "d419b4f4fe6a4b5189abfac7c23bc4eb", "guest_origin": "CH_ONLINE"}}

then you can calc HMAC signature on full payload body using shared secret. We use SHA256 algorithm for hash calculation.

In python it can be something like:

import hashlib
import hmac

payload = '{"hook": {"id": "ca44e691b78e4a10825f73d1bad0ef7b", "event": "Guest.created", "target": "http://example.org/target-url/"}, "data": {"guest_id": "a98c3bbeb0b94d339ff36268d45be1c9", "reservation_id": "d419b4f4fe6a4b5189abfac7c23bc4eb", "guest_origin": "CH_ONLINE"}}'
secret = 'some-secret-phrase'

hmac.new(secret.encode('utf-8'), payload.encode('utf-8'), hashlib.sha256).hexdigest()

After that you can compare new signature you've just calculated with the retrieved one to make sure it's valid.

OCR

Scan a Picture

curl -X POST \
  https://a.chekin.io/api/v3/ocr/picture/ \
  -H 'Authorization: JWT {{TOKEN}}' \
  -H 'Content-Type: application/json' \
  -d '{
        "picture_file": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAGQAAABkCAYAAABw4pVUAAAABHNCSVQICAgIfAhkiAAABERJREFUeAHtmk1S2zAYhj85XXVDMrAnPQHpCTDLhgXuCZqeAHoChhOQG+DewF1Al7g34Aake5jAqmyQ+kqJSWASkD35EeNXMxr/RD+fnlc/n+SIMJAACZAACZAACZAACZAACZAACZAACZAACZAACZAACZAACZAACZAACZAACZAACZAACZAACZAACZAACZAACZAACYRAQPkYkZzfZCJqVz5Gn7K91p1PHqapRiDyyqakKTY+SMcrPRNVJuAniKiBq8FoClIZtV9GP0GMjAXBKGFYKgE/QaIod1YoEy/VGhYufoJIMULUDpktl4CXl2VNSC5urXe1IQqe1pfWwL5bR0h+D9vKyPa8uo2R+2y/dTXv99Dff/A20JhclDoQ/RgjT+qdr2JCB17LjongSBhMlUZZTw/3WsxrZaKLofPYFAMkzCWKTtbZgV4zddZv/oIolaOAA4gS45oiLjRYAURrlO/gQwDdNHb8Ovq4mYzle7ycPwJGwtmptY08PZTTwz7qe7a/lS7U4CUVNmnmGxU4YEZfA9Bdtr/ZeiO518/J+bAjSn9D4gSx/SLTPUZGDiWuIBJi4w49Hc9+YVz2EVLb8qFh9Pk9TGXegtg2Jee3A/S6bbTua9bdyuy7siG5HDbVw+OB0eoIZXWm8qPnS+ZEiBr5oqYZTF99lHuIcn9hlCRT9QV5W06Qi9sjtOIUguQQZK9Mi8ZT0jHyJBCiOc5rRUjhKGRlen+petEB5J8eujxrdkh87C4nyKhxAxS8gfgj627a3vdqeBLCzudPwfzB1Jeual7HKElRtZ26vGx+MnMNN777EGfa6GDR9MZ2nmIKO5xnM4SIk4ubSyyq1xgRRZ6fzm3ubsWrEsPZ59Yi3FlvLfBQaoQUbYHX0oO3dTZ+tutKqgx280bgGekY13hqfSimpf6i1oXCDt/rMhwS37rLpqskiK0EvT/B3qAP8FjkZwQjf/E2xZF9P4Qj+1A2tjNIPXvlvw95lg3u0MjLypwwYvcmpuOSGOxXcPaVdf1d1BdFL+nR7l3wTUekjThADDJUFqRoTSFM8RzuFfsZkV1sPmNcc8QgQ6lFPcgW+BqFDa1v0nWmq48g7+QTQn0EWWe3L1E3BSkBaxVJayPI5GjGeVqrYFupjtoIUonOGjLVS5DRZhWn1jj2DzTUSxBV7D90Eqge3n9yCNX+cnapKHUZlBzjYPQsxJFS+SyrHIlwUr84GMWJDzaM9oukwZ8Bo6kjFY0jFmWaYhonq/zSWDtBbNcYn/4eQQz7sWz24eikD630G0otBZmwhjj2o5v9z7J+bOPwEbEIBiOmMZi4y8V7XkmABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABN4Hgf9R1jRAiigWLAAAAABJRU5ErkJggg=="
    }
    '

The above command returns JSON structured like this:

{
    "id": "6b13b182c3d64cd8ac147340b21dcb63",
    "picture_file": "https://s3.eu-central-1.amazonaws.com/ocr-prod-ng/uploads/pictures/0fbb89eef40f11e9bb1c4e0fa5b591de.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAVGYDLIHUGVPXZ2GC%2F20191021%2Feu-central-1%2Fs3%2Faws4_request&X-Amz-Date=20191021T142833Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=1796000cd1117cb99967173f4355fdf5d3427454be62ae15689abe90026284e2",
    "mrz_detected": false,
    "status": "NEW",
    "type_doc": null,
    "country": null,
    "date_of_birth": null,
    "place_of_birth": null,
    "issue_date": "",
    "expiration_date": null,
    "names": null,
    "surname": null,
    "nationality": null,
    "number": null,
    "sex": null,
    "valid_composite": false,
    "valid_date_of_birth": false,
    "valid_issue_date": false,
    "valid_expiration_date": false,
    "valid_number": false,
    "valid_score": null,
    "created_by": "148fc2c90fe544c181a1c35d24b5d1a2"
}

This endpoint allows you to upload the image of the document to be processed.

Requirements for the image

  1. The document should be fully inside the image;
  2. The document should take 70-80% of the image area;
  3. The document edges should not overlap the image edges;
  4. The document area should be in focus;
  5. There should be no glare or vast shadow on the document;
  6. The background should be as contrast as possible, avoid capturing white on white, and dark on dark;
  7. The minimum resolution for correct OCR is 200 PPI, the recommended resolution is 300 PPI (for ID1 86x54 mm taking ~80% of the image area, image size should be at least 900x600);

The types of files supported are the following:

File Type
PNG
JPEG or JPG
PDF
TIFF or TIF
BMP

HTTP Request

POST https://a.chekin.io/api/v3/ocr/picture/

Query Parameters

Parameter Required Description
picture_file true Image of the document to scan, base64 encoded

Scan a picture and extract the face picture

To extract the face picture from the document, enable the face extraction in the POST request you're making to scan the image.

curl -X POST \
  https://a.chekin.io/api/v3/ocr/picture/ \
  -H 'Authorization: JWT {{TOKEN}}' \
  -H 'Content-Type: application/json' \
  -d '{
        "picture_file": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAGQAAABkCAYAAABw4pVUAAAABHNCSVQICAgIfAhkiAAABERJREFUeAHtmk1S2zAYhj85XXVDMrAnPQHpCTDLhgXuCZqeAHoChhOQG+DewF1Al7g34Aake5jAqmyQ+kqJSWASkD35EeNXMxr/RD+fnlc/n+SIMJAACZAACZAACZAACZAACZAACZAACZAACZAACZAACZAACZAACZAACZAACZAACZAACZAACZAACZAACZAACZAACYRAQPkYkZzfZCJqVz5Gn7K91p1PHqapRiDyyqakKTY+SMcrPRNVJuAniKiBq8FoClIZtV9GP0GMjAXBKGFYKgE/QaIod1YoEy/VGhYufoJIMULUDpktl4CXl2VNSC5urXe1IQqe1pfWwL5bR0h+D9vKyPa8uo2R+2y/dTXv99Dff/A20JhclDoQ/RgjT+qdr2JCB17LjongSBhMlUZZTw/3WsxrZaKLofPYFAMkzCWKTtbZgV4zddZv/oIolaOAA4gS45oiLjRYAURrlO/gQwDdNHb8Ovq4mYzle7ycPwJGwtmptY08PZTTwz7qe7a/lS7U4CUVNmnmGxU4YEZfA9Bdtr/ZeiO518/J+bAjSn9D4gSx/SLTPUZGDiWuIBJi4w49Hc9+YVz2EVLb8qFh9Pk9TGXegtg2Jee3A/S6bbTua9bdyuy7siG5HDbVw+OB0eoIZXWm8qPnS+ZEiBr5oqYZTF99lHuIcn9hlCRT9QV5W06Qi9sjtOIUguQQZK9Mi8ZT0jHyJBCiOc5rRUjhKGRlen+petEB5J8eujxrdkh87C4nyKhxAxS8gfgj627a3vdqeBLCzudPwfzB1Jeual7HKElRtZ26vGx+MnMNN777EGfa6GDR9MZ2nmIKO5xnM4SIk4ubSyyq1xgRRZ6fzm3ubsWrEsPZ59Yi3FlvLfBQaoQUbYHX0oO3dTZ+tutKqgx280bgGekY13hqfSimpf6i1oXCDt/rMhwS37rLpqskiK0EvT/B3qAP8FjkZwQjf/E2xZF9P4Qj+1A2tjNIPXvlvw95lg3u0MjLypwwYvcmpuOSGOxXcPaVdf1d1BdFL+nR7l3wTUekjThADDJUFqRoTSFM8RzuFfsZkV1sPmNcc8QgQ6lFPcgW+BqFDa1v0nWmq48g7+QTQn0EWWe3L1E3BSkBaxVJayPI5GjGeVqrYFupjtoIUonOGjLVS5DRZhWn1jj2DzTUSxBV7D90Eqge3n9yCNX+cnapKHUZlBzjYPQsxJFS+SyrHIlwUr84GMWJDzaM9oukwZ8Bo6kjFY0jFmWaYhonq/zSWDtBbNcYn/4eQQz7sWz24eikD630G0otBZmwhjj2o5v9z7J+bOPwEbEIBiOmMZi4y8V7XkmABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABN4Hgf9R1jRAiigWLAAAAABJRU5ErkJggg==",
        "do_face_extraction": true
    }
    '

Get Scan status & Data

curl -X GET \
  https://a.chekin.io/api/v3/ocr/data/{{OCR_ID}}/ \
  -H 'Authorization: JWT {{TOKEN}}' \
  -H 'Content-Type: application/json'

The above command returns JSON structured like this:

{
    "id": "6b13b182c3d64cd8ac147340b21dcb63",
    "picture_file": "https://s3.eu-central-1.amazonaws.com/ocr-prod-ng/uploads/pictures/0fbb89eef40f11e9bb1c4e0fa5b591de.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAVGYDLIHUGVPXZ2GC%2F20191021%2Feu-central-1%2Fs3%2Faws4_request&X-Amz-Date=20191021T142855Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=7b2600843d99f8f68d8a81853ae4b2f194ae52622eec7627b0ebb8b40bfbe1d1",
    "mrz_detected": true,
    "status": "COM",
    "type_doc": "P",
    "country": "SE",
    "date_of_birth": "1987-03-14",
    "place_of_birth": null,
    "issue_date": "",
    "expiration_date": "2017-01-02",
    "names": "SVEN",
    "surname": "SPECIMEN",
    "first_surname": "SPECIMEN",
    "second_surname": "",
    "nationality": "SWF",
    "number": "59000001",
    "sex": "M",
    "valid_composite": true,
    "valid_date_of_birth": true,
    "valid_issue_date": false,
    "valid_expiration_date": true,
    "valid_number": true,
    "valid_score": 100,
    "created_by": "148fc2c9-0fe5-44c1-81a1-c35d24b5d1a2"
}

This endpoint allows you to obtain the status of the processing and the data extracted from the documents. If the status is PRO, repeat the GET request until you receive the COM status and the data or the ERR status.

The processing status can be:

Status type Description
NEW Image of the stored document without processing.
PRO The image is being processed to extract the data.
COM Image processing has successfully completed.
ERR Error during image processing.

We get the following validation options:

Option Description
valid_composite Composite checksum validity.
valid_date_of_birth Date of birth checksum validity.
valid_expiration_date Expiration date checksum validity.
valid_number Personal number validity score calculated.
valid_score The MRZ trust score calculated. Is calculated based on valid_* fields.

The valid_score field tells us how good the result of the data extraction has been. It has a range [0 - 100], obtaining better results the greater the value of the field.

The different values that the type_doc field can have are the following:

Value Description
P Passports
ID National ID Cards
IX Redisence permission ID Cards (A foreign person living in spain for example)

Dates

The format of the date fields like date_of_birth or expiration_date is: YYYY-MM-DD

HTTP Request

GET https://a.chekin.io/api/v3/ocr/data/{{OCR_ID}}/

URL Parameters

Parameter Required Description
ID true ID that refers to a specific image processing.

Get a Notification with Data when the Scanning is Completed

In order to receive the scanned data to a specified url, make a POST request to https://a.chekin.io/api/v3/ocr/picture/ with the picture file and the url.

curl -X POST \
  https://a.chekin.io/api/v3/ocr/picture/ \
  -H 'Authorization: JWT {{TOKEN}}' \
  -H 'Content-Type: application/json' \
  -d '{
        "picture_file": "data:image/png;base64,iVB..."
        "notification_url": "{{URL}}"
    }
    '

Image Quality Requirements

Below are the details about the expected external image quality and size for successful document image processing using our OCR API:

If the document we are talking about is an ID card, then its size is 86x54 mm. Let’s do the math. 800 pixels * 0.8(80%) / 86 mm *25.4(mm per inch) = 189 PPI. This is really below the limits for correct OCR, as the font used, for example, in German ID cards is only 2 mm in height, so it will be 15 pixels only maximum, including JPEG compression artifacts and background noise, and all this will lead to poor OCR probability and mistakes.

To get successful results, this document image at minimum should be 300 PPI / 25.4 = ~12 pixels per mm (ppm) -> 86 mm * 12 ppm = 1032 pixels for document width -> 1032 / 0,8 (80%) = 1290 pixels for image width, where the document is flat on the surface without tilt to the camera.

If we talk about documents like passport, then calculations should be done accordingly to its larger size of 125x88 mm.

However, passports have MRZ with lower resolution constraints for successful OCR. If you present a passport occupying 80% of the 800x600 image, then its MRZ will be recognized with good probability in 90+% of cases if all other requirements on the image quality are met.

To conclude all that, images from a Full HD resolution (1920x1080) camera with autofocus are recommended to get proven good quality OCR results for any identity document size.

Supported Documents

We can recognize all MRZ formats standardized by ICAO. ICAO List

Biometric Match Service

Extract face on ID image

curl -X POST \
  https://a.chekin.io/api/v3/biomatch/identification/ \
  -H 'Authorization: JWT {{TOKEN}}' \
  -H 'Content-Type: multipart/form-data' \
  -d '{
        "picture_file": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAGQAAABkCAYAAABw4pVUAAAABHNCSVQICAgIfAhkiAAABERJREFUeAHtmk1S2zAYhj85XXVDMrAnPQHpCTDLhgXuCZqeAHoChhOQG+DewF1Al7g34Aake5jAqmyQ+kqJSWASkD35EeNXMxr/RD+fnlc/n+SIMJAACZAACZAACZAACZAACZAACZAACZAACZAACZAACZAACZAACZAACZAACZAACZAACZAACZAACZAACZAACZAACYRAQPkYkZzfZCJqVz5Gn7K91p1PHqapRiDyyqakKTY+SMcrPRNVJuAniKiBq8FoClIZtV9GP0GMjAXBKGFYKgE/QaIod1YoEy/VGhYufoJIMULUDpktl4CXl2VNSC5urXe1IQqe1pfWwL5bR0h+D9vKyPa8uo2R+2y/dTXv99Dff/A20JhclDoQ/RgjT+qdr2JCB17LjongSBhMlUZZTw/3WsxrZaKLofPYFAMkzCWKTtbZgV4zddZv/oIolaOAA4gS45oiLjRYAURrlO/gQwDdNHb8Ovq4mYzle7ycPwJGwtmptY08PZTTwz7qe7a/lS7U4CUVNmnmGxU4YEZfA9Bdtr/ZeiO518/J+bAjSn9D4gSx/SLTPUZGDiWuIBJi4w49Hc9+YVz2EVLb8qFh9Pk9TGXegtg2Jee3A/S6bbTua9bdyuy7siG5HDbVw+OB0eoIZXWm8qPnS+ZEiBr5oqYZTF99lHuIcn9hlCRT9QV5W06Qi9sjtOIUguQQZK9Mi8ZT0jHyJBCiOc5rRUjhKGRlen+petEB5J8eujxrdkh87C4nyKhxAxS8gfgj627a3vdqeBLCzudPwfzB1Jeual7HKElRtZ26vGx+MnMNN777EGfa6GDR9MZ2nmIKO5xnM4SIk4ubSyyq1xgRRZ6fzm3ubsWrEsPZ59Yi3FlvLfBQaoQUbYHX0oO3dTZ+tutKqgx280bgGekY13hqfSimpf6i1oXCDt/rMhwS37rLpqskiK0EvT/B3qAP8FjkZwQjf/E2xZF9P4Qj+1A2tjNIPXvlvw95lg3u0MjLypwwYvcmpuOSGOxXcPaVdf1d1BdFL+nR7l3wTUekjThADDJUFqRoTSFM8RzuFfsZkV1sPmNcc8QgQ6lFPcgW+BqFDa1v0nWmq48g7+QTQn0EWWe3L1E3BSkBaxVJayPI5GjGeVqrYFupjtoIUonOGjLVS5DRZhWn1jj2DzTUSxBV7D90Eqge3n9yCNX+cnapKHUZlBzjYPQsxJFS+SyrHIlwUr84GMWJDzaM9oukwZ8Bo6kjFY0jFmWaYhonq/zSWDtBbNcYn/4eQQz7sWz24eikD630G0otBZmwhjj2o5v9z7J+bOPwEbEIBiOmMZi4y8V7XkmABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABN4Hgf9R1jRAiigWLAAAAABJRU5ErkJggg=="
    }
    '

The above command returns JSON structured like this:

  {
    "id": "64672caf4d2140e19d68b222fa0da318",
    "picture_file": "https://s3.eu-west-2.amazonaws.com/chekinapptest/uploads/identifications/f028266e150211e9a283d64b2af3b94e.jpg?X-Amz-Date=20190110T180957Z&X-Amz-SignedHeaders=host&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAJMSXFFSPIIN6XG4Q%2F20190110%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Expires=3600&X-Amz-Signature=c176e805360ad8bf073931b53214df73ca81333f2d3fc289f6ae3807b51b0ab0",
    "status": "NEW",
    "is_face_detected": false
  }

This endpoint allows you to upload the image of the document to be processed.

HTTP Request

POST https://a.chekin.io/api/v3/biomatch/identification/

Query Parameters

Parameter Required Description
picture_file true Image of the document to extract the face.

Get ID face extraction status & results

curl -X GET \
  https://a.chekin.io/api/v3/biomatch/identification/64672caf4d2140e19d68b222fa0da318/ \
  -H 'Authorization: JWT {{TOKEN}}' \
  -H 'Content-Type: application/json'

The above command returns JSON structured like this:

  {
    "id": "64672caf4d2140e19d68b222fa0da318",
    "picture_file": "https://s3.eu-west-2.amazonaws.com/chekinapptest/uploads/identifications/f028266e150211e9a283d64b2af3b94e.jpg?X-Amz-Date=20190110T180957Z&X-Amz-SignedHeaders=host&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAJMSXFFSPIIN6XG4Q%2F20190110%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Expires=3600&X-Amz-Signature=c176e805360ad8bf073931b53214df73ca81333f2d3fc289f6ae3807b51b0ab0",
    "status": "COM",
    "is_face_detected": true
  }

This endpoint allows you to obtain the status of the processing and if the face has been found.

The processing status can be:

Status type Description
NEW Image of the stored document without processing.
PRO The image is being processed to extract the face.
COM Image processing has successfully completed.
ERR Error during image processing.

HTTP Request

GET https://a.chekin.io/api/v3/biomatch/identification/<ID>/

URL Parameters

Parameter Required Description
ID true identifier that refers to a specific image processing.

Extract face on Selfie image

curl -X POST \
  https://a.chekin.io/api/v3/biomatch/person/ \
  -H 'Authorization: JWT {{TOKEN}}' \
  -H 'Content-Type: multipart/form-data' \
  -d '{
        "picture_file": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAGQAAABkCAYAAABw4pVUAAAABHNCSVQICAgIfAhkiAAABERJREFUeAHtmk1S2zAYhj85XXVDMrAnPQHpCTDLhgXuCZqeAHoChhOQG+DewF1Al7g34Aake5jAqmyQ+kqJSWASkD35EeNXMxr/RD+fnlc/n+SIMJAACZAACZAACZAACZAACZAACZAACZAACZAACZAACZAACZAACZAACZAACZAACZAACZAACZAACZAACZAACZAACYRAQPkYkZzfZCJqVz5Gn7K91p1PHqapRiDyyqakKTY+SMcrPRNVJuAniKiBq8FoClIZtV9GP0GMjAXBKGFYKgE/QaIod1YoEy/VGhYufoJIMULUDpktl4CXl2VNSC5urXe1IQqe1pfWwL5bR0h+D9vKyPa8uo2R+2y/dTXv99Dff/A20JhclDoQ/RgjT+qdr2JCB17LjongSBhMlUZZTw/3WsxrZaKLofPYFAMkzCWKTtbZgV4zddZv/oIolaOAA4gS45oiLjRYAURrlO/gQwDdNHb8Ovq4mYzle7ycPwJGwtmptY08PZTTwz7qe7a/lS7U4CUVNmnmGxU4YEZfA9Bdtr/ZeiO518/J+bAjSn9D4gSx/SLTPUZGDiWuIBJi4w49Hc9+YVz2EVLb8qFh9Pk9TGXegtg2Jee3A/S6bbTua9bdyuy7siG5HDbVw+OB0eoIZXWm8qPnS+ZEiBr5oqYZTF99lHuIcn9hlCRT9QV5W06Qi9sjtOIUguQQZK9Mi8ZT0jHyJBCiOc5rRUjhKGRlen+petEB5J8eujxrdkh87C4nyKhxAxS8gfgj627a3vdqeBLCzudPwfzB1Jeual7HKElRtZ26vGx+MnMNN777EGfa6GDR9MZ2nmIKO5xnM4SIk4ubSyyq1xgRRZ6fzm3ubsWrEsPZ59Yi3FlvLfBQaoQUbYHX0oO3dTZ+tutKqgx280bgGekY13hqfSimpf6i1oXCDt/rMhwS37rLpqskiK0EvT/B3qAP8FjkZwQjf/E2xZF9P4Qj+1A2tjNIPXvlvw95lg3u0MjLypwwYvcmpuOSGOxXcPaVdf1d1BdFL+nR7l3wTUekjThADDJUFqRoTSFM8RzuFfsZkV1sPmNcc8QgQ6lFPcgW+BqFDa1v0nWmq48g7+QTQn0EWWe3L1E3BSkBaxVJayPI5GjGeVqrYFupjtoIUonOGjLVS5DRZhWn1jj2DzTUSxBV7D90Eqge3n9yCNX+cnapKHUZlBzjYPQsxJFS+SyrHIlwUr84GMWJDzaM9oukwZ8Bo6kjFY0jFmWaYhonq/zSWDtBbNcYn/4eQQz7sWz24eikD630G0otBZmwhjj2o5v9z7J+bOPwEbEIBiOmMZi4y8V7XkmABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABEiABN4Hgf9R1jRAiigWLAAAAABJRU5ErkJggg=="
    }
    '

The above command returns JSON structured like this:

  {
    "id": "64672caf4d2140e19d68b222fa0da318",
    "picture_file": "https://s3.eu-west-2.amazonaws.com/chekinapptest/uploads/identifications/f028266e150211e9a283d64b2af3b94e.jpg?X-Amz-Date=20190110T180957Z&X-Amz-SignedHeaders=host&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAJMSXFFSPIIN6XG4Q%2F20190110%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Expires=3600&X-Amz-Signature=c176e805360ad8bf073931b53214df73ca81333f2d3fc289f6ae3807b51b0ab0",
    "status": "NEW",
    "is_face_detected": false
  }

This endpoint allows you to upload the image of the selfie to be processed.

HTTP Request

POST https://a.chekin.io/api/v3/biomatch/person/

Query Parameters

Parameter Required Description
picture_file true Image of the selfie to extract the face.

Get selfie face extraction status & results

curl -X GET \
  https://a.chekin.io/api/v3/biomatch/person/64672caf4d2140e19d68b222fa0da318/ \
  -H 'Authorization: JWT {{TOKEN}}' \
  -H 'Content-Type: application/json'

The above command returns JSON structured like this:

  {
    "id": "64672caf4d2140e19d68b222fa0da318",
    "picture_file": "https://s3.eu-west-2.amazonaws.com/chekinapptest/uploads/identifications/f028266e150211e9a283d64b2af3b94e.jpg?X-Amz-Date=20190110T180957Z&X-Amz-SignedHeaders=host&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAJMSXFFSPIIN6XG4Q%2F20190110%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Expires=3600&X-Amz-Signature=c176e805360ad8bf073931b53214df73ca81333f2d3fc289f6ae3807b51b0ab0",
    "status": "COM",
    "is_face_detected": true
  }

This endpoint allows you to obtain the status of the processing and if the face has been found.

The processing status can be:

Status type Description
NEW Image of the stored document without processing.
PRO The image is being processed to extract the face.
COM Image processing has successfully completed.
ERR Error during image processing.

HTTP Request

GET https://a.chekin.io/api/v3/biomatch/person/<ID>/

URL Parameters

Parameter Required Description
ID true identifier that refers to a specific image processing.

Compare extracted faces

curl -X POST \
  https://a.chekin.io/api/v3/biomatch/compare/ \
  -H 'Authorization: JWT {{TOKEN}}' \
  -H 'Content-Type: application/json' \
  -d '{
        "identification_picture": 2,
        "person_picture": 2
      }
     '

The above command returns JSON structured like this:

  {
    "id": "64672caf4d2140e19d68b222fa0da318",
    "identification_picture": 2,
    "person_picture": 2,
    "status": "NEW",
    "distance": null,
    "is_match": false
  }

This endpoint allows you to compare the faces extracted on ID image & Selfie image.

HTTP Request

POST https://a.chekin.io/api/v3/biomatch/compare/

Query Parameters

Parameter Required Description
identification_picture true identifier of the extraction process of the face in the ID image.
person_picture true identifier of the extraction process of the face in the Selfie image.

Get results of face comparison

curl -X GET \
  https://a.chekin.io/api/v3/biomatch/compare/64672caf4d2140e19d68b222fa0da318/ \
  -H 'Authorization: JWT {{TOKEN}}' \
  -H 'Content-Type: application/json'

The above command returns JSON structured like this:

  {
    "id": "64672caf4d2140e19d68b222fa0da318",
    "identification_picture": 2,
    "person_picture": 2,
    "status": "COM",
    "distance": 0.41156753794555,
    "is_match": true
  }

This endpoint allows you to obtain the results of the comparison between the extracted faces in the ID image and Selfie image.

The distance obtained has a range of values [0-1], when the value is closer to one, the faces are less similar, and when the value approaches zero, the faces are more similar

For security reasons and to prevent the same photo from being uploaded on two occasions, we have decided to take into account limits to validate the identity of the people.

The limit established for identity verification to be valid is that the distance must be included in the following range of values [0.35-0.6]. If distances are obtained outside this range, the verification will be considered invalid.

The processing status can be:

Status type Description
NEW The face comparison has started but not processed.
PRO Face comparison is being processed.
COM The processing of the face comparison has completed successfully.
ERR An error has occurred during processing.

HTTP Request

GET https://a.chekin.io/api/v3/biomatch/compare/<ID>/

URL Parameters

Parameter Required Description
ID true identifier that refers to a face comparison.
shell python