Hostkit API Documentation

Our REST based API allow you to get access to the Hostkit application. On this page we explain you a little bit more detailed what you need for your usecase as a host.

Please contact us before you start coding. Tell us a few words about your ideas and plans. We are always happy to help our customers and partners to build the best integrated applications.

If you have any questions about our API, please feel free to open a ticket in our Helpdesk.


API Access

The access to the API is done by using the following URL: https://app.hostkit.pt/api/method?APIKEY=[Your_API_Key]

CURL components:

  1. The API method shall be added after /api/
  2. The APIKEY parameter is mandatory
  3. API calls must be requested with GET
  4. Special characters need to be encoded

For all reservations related endpoints, the API key is different for each property, therefore must be generated and maintained in the "Properties" -> "API key" tab of each property. For invoicing related endpoints, you may use any of your API keys.


API Rate Limit

We have a rate limit of 100 requests per each 10 seconds. If you need more, please contact us.


API Errors

The possible errors that our API may return are:

Missing parameter There is a mandatory parameter for SEF missing.
Incorrect format The format of one of the parameters is wrong.
Departure is before arrival Arrival date is earlier than departure date.
Parameter is invalid The parameter is not valid.
Parameter too long The parameter exceeded the maximum size.
SEF error Specific SEF error.
Reservation already exists The reservation you are trying to add/edit already exists.
Reservation not found The reservation you are trying to edit/delete doesn't exist.
Unknown reservation code The reservation code you are trying to obtain doesn't exist.
Guest already exists The guest you are trying to add already exists.
Guest not found The guest you are trying to edit/delete doesn't exist.
Invalid format for check-in/out Incorrect check-in/out date format, must be YYYY-MM-DD.
Invalid property ID for your user Specified property is not licensed to the API key user.
No APIKEY provided API key not specified.
Account expired Your Hostkit account license expired.
Invalid plan Your plan does not allow access to the API.
Incorrect APIKEY provided An incorrect API key has been specified.
Limit exceeded Requests rate limit exceeded.
Incorrect protocol Incorrect API protocol call.
Internal error Internal Hostkit error, please contact us.
Unknown error An unknown error has occurred.

API Methods

getLicense

This method returns the expiry date of the Hostkit license.

curl "https://app.hostkit.pt/api/getLicense?APIKEY=[Your_API_Key]"

{ 
	"plan": "Business", 
	"valid_until": "2022-01-04" 
}
                     


getProperty

This method returns the details of a single property, given an ID.

curl "https://app.hostkit.pt/api/getProperty?APIKEY=[Your_API_Key]&id=[Property_ID]"

{
	"owner": "[email protected]",
	"activated": "1",
	"id": "1",
	"address": "R. das Quintinhas, 7", 
	"property_name": "Quintinhas",
	"cp": "1000-000",
	"localidade": "LISBOA",
	"nif": "123456789",
	"seforder": "0",
	"sefcode": "10938247374",
	"lat": "38",
	"lon": "-9",
	"default_checkin": "15",
	"default_checkout": "12",
	"invoicing_nif": "123456789",
	"invoicing_name": "Gestão Lda", 
	"invoicing_email": "[email protected]", 
	"invoicing_phone": "+351928617112", 
	"invoicing_address": "Av. Republica, 36, 1o", 
	"codigo_al": "12345",
	"tmt": "2",
	"comm_email": "[email protected]", 
	"property_info":"PHAVG......[encoded base64]==", 
	"default_series": "2022",
	"default_product": "Alojamento"
}
                     

Mandatory curl parameters:

id=[Property_ID] id=12345

getProperties

This method returns similar data as getProperty but inside a list.

curl "https://app.hostkit.pt/api/getProperties?APIKEY=[Your_API_Key]"


getReservation

This method returns the details of a booking. If the parameter get_archived=true is used it returns a booking that is archived.

curl "https://app.hostkit.pt/api/getReservation?APIKEY=[Your_API_Key]&rcode=[Reservation_Code]"

{
	"owner": "[email protected]", 
	"rcode": "25901",
	"apid": "0",
	"room": "",
	"firstname": "Antonio",
	"lastname": "Ficelli",
	"email": "[email protected]", 
	"phone": "+39123456789",
	"flight": "TP821",
	"flight_time": "17:17",
	"arrival_by": "",
	"in_date": "1574255100",
	"out_date": "1574726400",
	"arrival": "1574208000",
	"departure": "1574726400",
	"pax": "1",
	"guest_data": [{
		"name": " Antonio Ficelli", 
		"document_type": "P", 
		"document_number": "JH191HA", 
		"document_country": "ITA", 
		"nationality": "ITA",
		"birthday": "1980-10-01",
		"arrival": "2022-11-20", 
		"departure": "2022-11-26", 
		"country": "ITA",
		"city": "Milano"
	}],
	"service_in": "", 
	"service_out": "", 
	"service_cleaning": "",
	"service_laundry": "",
	"service_transfer_arr": "", 
	"service_transfer_dep": "", 
	"service_notes": "", 
	"private_note": "", 
	"feedback": "",
	"sefdate": "0",
	"block_sef": "0",
	"provider": "external", 
	"received_amount": "90", 
	"host_commission": "0", 
	"shortlink": "https://icheckin.pt/?9DSCNKPE", 
	"block_emails": "0"
}
                     

Mandatory curl parameters:

rcode=[Reservation_Code] rcode=HMK71DA91ALK

Optional curl parameters:

get_archived=[Archived_Reservation] get_archived=true

getReservations

This method returns similar data as getReservation but inside a list.

curl "https://app.hostkit.pt/api/getReservations?APIKEY=[Your_API_Key]"

Optional curl parameters:

get_archived=[Archived_Reservation] get_archived=true
from_date=[Checkin_Date] from_date=2023-05-10

addReservation

curl "https://app.hostkit.pt/api/addReservation?APIKEY=[Your_API_Key]&rcode=[Reservation_Code]&first_name=[Guest_FirstName]&last_name=[Guest_LastName]&check_in=[ArrivalDate]&check_out=[ArrivalDate]&pax=[Nr_Guests]"

{ 
	"status": "success" 
}
                     

Mandatory curl parameters:

rcode=[Reservation_Code] rcode=HMK71DA91ALK
first_name=[Guest_FirstName] first_name=Alana
last_name=[Guest_LastName] last_name=Bolsch
check_in=[ArrivalDate] check_in=2023-05-20 16:00
check_out=[ArrivalDate] check_out=2023-05-25 11:00
pax=[Nr_Guests] pax=2

Optional curl parameters:

email=[Guest_Email] [email protected]
phone=[Guest_Phone] phone=00351123456789
received_amount=[Received_Amount] received_amount=1234.56
host_commission=[Channel_Commission] host_commission=123.45
cleaning_fee=[Cleaning_Fee_Amount] cleaning_fee=50
provider=[Channel_Name] provider=airbnb
reservation_date=[Date_Reservation] reservation_date=2023-05-10
flight=[Flight_Nr] flight=FR1234
flight_time=[Flight_Time] flight_time=13:10
arrival_by=[Arrival_Transport] arrival_by=Taxi
service_in=[Checkin_Service_User] [email protected]
service_out=[Checkout_Service_User] [email protected]
service_cleaning=[Cleaning_Service_User] [email protected]
service_laundry=[Laundry_Service_User] [email protected]
service_transfer_arr=[Trans_Arr_Service_User] [email protected]
service_transfer_dep=[Trans_Dep_Service_User] [email protected]

updateReservation

curl "https://app.hostkit.pt/api/updateReservation?APIKEY=[Your_API_Key]&rcode=[Reservation_Code]"

{ 
	"status": "success" 
}
                     

Mandatory curl parameters:

rcode=[Reservation_Code] rcode=HMK71DA91ALK

Optional curl parameters:

first_name=[Guest_FirstName] first_name=Alana
last_name=[Guest_LastName] last_name=Bolsch
check_in=[ArrivalDate] check_in=2023-05-20 16:00
check_out=[ArrivalDate] check_out=2023-05-25 11:00
pax=[Nr_Guests] pax=2
email=[Guest_Email] [email protected]
phone=[Guest_Phone] phone=00351123456789
received_amount=[Received_Amount] received_amount=1234.56
host_commission=[Channel_Commission] host_commission=123.45
cleaning_fee=[Cleaning_Fee_Amount] cleaning_fee=50
provider=[Channel_Name] provider=airbnb
flight=[Flight_Nr] flight=FR1234
flight_time=[Flight_Time] flight_time=13:10
arrival_by=[Arrival_Transport] arrival_by=Taxi
service_in=[Checkin_Service_User] [email protected]
service_out=[Checkout_Service_User] [email protected]
service_cleaning=[Cleaning_Service_User] [email protected]
service_laundry=[Laundry_Service_User] [email protected]
service_transfer_arr=[TrArr_Service_User] [email protected]
service_transfer_dep=[TrDep_Service_User] [email protected]

cancelReservation

This method moves a specific reservation to our cancelations table.

curl "https://app.hostkit.pt/api/cancelReservation?APIKEY=[Your_API_Key]&rcode=[Reservation_Code]"

{ 
	"status": "success" 
}
                     

Mandatory curl parameters:

rcode=[Reservation_Code] rcode=HMK71DA91ALK

deleteReservation

This method deletes a specific reservation.

curl "https://app.hostkit.pt/api/deleteReservation?APIKEY=[Your_API_Key]&rcode=[Reservation_Code]"

{ 
	"status": "success" 
}
                     

Mandatory curl parameters:

rcode=[Reservation_Code] rcode=HMK71DA91ALK

getOnlineCheckin

This method gets the link and filling status of the online check-in.

curl "https://app.hostkit.pt/api/getOnlineCheckin?APIKEY=[Your_API_Key]&rcode=[Reservation_Code]"

{ 
	"shortlink": "https://icheckin.pt/?9DSCNKPE",		 
	"status": "done" // empty otherwise
}
                     

Mandatory curl parameters:

rcode=[Reservation_Code] rcode=HMK71DA91ALK

getKeycode

This method gets the keycode or invite code of smartlocks.

curl "https://app.hostkit.pt/api/getKeycode?APIKEY=[Your_API_Key]&rcode=[Reservation_Code]&provider=[Provider]"

{ 
	"keycode": "1234" // otherwise keycode not found
}
                     

Mandatory curl parameters:

rcode=[Reservation_Code] rcode=HMK71DA91ALK
provider=[Provider] provider=nuki (nuki, homeit or ttlock)

getInvoices

This method returns the all invoices OR a single invoice, as a list.

curl "https://app.hostkit.pt/api/getInvoices?APIKEY=[Your_API_Key]"

[{
	"series": "2023",
	"id": "10",
	"nif": "123456789", 
	"name": "John Smith", 
	"address": "",
	"value": "1.44",
	"date": "1620644915", 
	"closed": "0",
	"rcode": "A8J2H8A", 
	"partial": true,
	"notes": "Paid in cash",
	"invoice_url": "https://app.hostkit.pt/getCustomerInvoice.cgi?YY=A1B2C3D4E5F6G7H8I9"
	},
	...
]
                     

Optional curl parameters:

id=[Invoice_ID] id=1234
series=[Invoice_Series] series=2023
invoicing_nif=[Invoicing_VAT_ID] invoicing_nif=234567890

getReservationInvoices

This method returns a list of all the invoices for a given reservation. Can be one (full invoice) or a set of partial invoices.

curl "https://app.hostkit.pt/api/getReservationInvoices?APIKEY=[Your_API_Key]&rcode=[Reservation_Code]"

[{
	"series": "2022",
	"id": "9",
	"nif": "123456789",
	"name": "Melanie Johnson", 
	"address": "",
	"value": "129.06",
	"date": "1620641390", 
	"closed": "1",
	"rcode": "1BVD4R",
	"partial": true,
	"notes": "",
	"invoice_url": "https://app.hostkit.pt/getCustomerInvoice.cgi?YY=A1B2C3D4E5F6G7H8I9"
	},
	...
]
                     

Mandatory curl parameters:

rcode=[Reservation_Code] rcode=HMK71DA91ALK

addInvoice

This method allow to create a new invoice. The invoice cannot be created if the previous one has not yet been closed.

curl "https://app.hostkit.pt/api/addInvoice?APIKEY=[Your_API_Key]&series=[Invoice_Series_ID]&customer_id[Customer_ID]&name=[Invoice_Recipient_Name]&country=[Country_ICAO_Code]"

{ 
	"status": "success",
	"id": "[Invoice_ID]"
}
                     

Mandatory curl parameters:

series=[Invoice_Series_ID] series=AL2023
customer_id=[Customer_ID] customer_id=HA19837264
name=[Invoice_Recipient_Name] name=Alana Bolsch
country=[Country_ICAO_Code] country=FRA

Optional curl parameters:

address=[Invoice_Recipient_Address] address=Rua do Exemplo 10
cp=[Invoice_Recipient_ZIP] cp=12345-678
city=[Invoice_Recipient] city=Lisboa
rcode=[Reservation_Code] rcode=HMK71DA91ALK
payment_method=[Payment_Method] payment_method=TB
comment=[Invoice_Comment] comment=My%20special%20note

Please find all available payment methods here.


addInvoiceLine

This method allow to create a new invoice line in an existing invoice.

curl "https://app.hostkit.pt/api/addInvoiceLine?APIKEY=[Your_API_Key]&series=[Invoice_Series_ID]&id=[Invoice_ID]&product_id=[Invoice_Line_Product_ID]&custom_descr=[Invoice_Line_Description]&qty=[Invoice_Line_Quantity]&price=[Invoice_Line_Price]&discount=[Invoice_Line_Discount]&vat=[Invoice_Line_VAT]&reason_code=[Invoice_Line_Exemption_Code]"

{ 
	"status": "success",
	"line": "[Invoice_Line_ID]"
}
                     

Mandatory curl parameters:

series=[Invoice_Series_ID] series=AL2023
id=[Invoice_ID] id=35
product_id=[Invoice_Line_Product_ID] product_id=AL
custom_descr=[Invoice_Line_Description] custom_descr=Alojamento Local
qty=[Invoice_Line_Quantity] qty=1
price=[Invoice_Line_Price] price=1234.56
discount=[Invoice_Line_Discount] discount=0 (int)
vat=[Invoice_Line_VAT] vat=6 (int)
reason_code=[Invoice_Line_Exemption_Code] only if VAT is 0. M99 (non-taxed), M10 (VAT exempt), otherwise empty

Please find all available reason codes here.


closeInvoice

This method closes a specific invoice.

curl "https://app.hostkit.pt/api/closeInvoice?APIKEY=[Your_API_Key]&series=[Invoice_Series_ID]&id=[Invoice_ID]"

{ 
	"status": "success",
	"invoice_url": "https://app.hostkit.pt/getCustomerInvoice.cgi?YY=A1B2C3D4E5F6G7H8I9"
}
                     

Mandatory curl parameters:

series=[Invoice_Series_ID] series=AL2023
id=[Invoice_ID] id=35

deleteInvoice

This method deletes a specific invoice. Invoice CANNOT be closed.

curl "https://app.hostkit.pt/api/deleteInvoice?APIKEY=[Your_API_Key]&series=[Invoice_Series_ID]&id=[Invoice_ID]"

{ 
	"status": "success"
}
                     

Mandatory curl parameters:

series=[Invoice_Series_ID] series=AL2023
id=[Invoice_ID] id=35

getCreditNotes

This method returns the all credit notes as a list.

curl "https://app.hostkit.pt/api/getCreditNotes?APIKEY=[Your_API_Key]"

[{
	"series": "2022",
	"id": "9",
	"nif": "123456789",
	"name": "Melanie Johnson", 
	"address": "",
	"value": "129.06",
	"date": "1620641390", 
	"closed": "1",
	"rcode": "1BVD4R",
	"partial": true,
	"notes": ""
	},
	...
]
                     

Optional curl parameters:

series=[Invoice_Series_ID] series=AL2023
id=[Invoice_ID] id=35

addCreditNote

This method allow to create a credit note based on an EXISTING CLOSED invoice.

curl "https://app.hostkit.pt/api/addCreditNote?APIKEY=[Your_API_Key]&refseries=[Invoice_Series_ID]&refid=[Invoice_ID]"

{ 
	"status": "success",
	"id": "[Credit_Note_ID]"
}
                     

Mandatory curl parameters:

refseries=[Invoice_Series_ID] refseries=INVMD
refid=[Invoice_ID] refid=737

validateSEF

This method receives data to be sent to SEF and validates it by returning "OK" if all data is correctly formatted.

curl "https://app.hostkit.pt/api/validateSEF?APIKEY=[Your_API_Key]&rcode=[Reservation_Code]"

{ 
	"status": "success" 
}
                     

Mandatory curl parameters:

rcode=[Reservation_Code] rcode=HMK71DA91ALK

sendSEF

This method performs the validation described above and, if everything is correct,triggers the submission of the SEF bulletin within a specific reservation.

curl "https://app.hostkit.pt/api/sendSEF?APIKEY=[Your_API_Key]&rcode=[Reservation_Code]"

{ 
	"status": "success" 
}
                     

Mandatory curl parameters:

rcode=[Reservation_Code] rcode=HMK71DA91ALK

getLastSEFDate

This method returns the date and time of the last successfully submitted bulletin to SEF in the format: YYYY-MM-DD HH:MM:SS

curl "https://app.hostkit.pt/api/getLastSEFDate?APIKEY=[Your_API_Key]"

{ 
	"sefdate": "2023-05-22 10:00:01" 
}
                     


addGuest

This method adds a single guest data to a specific reservation.

curl "https://app.hostkit.pt/api/addGuest?APIKEY=[Your_API_Key]&rcode=[Reservation_Code]&arrival=[Arrival_Date]&departure=[Departure_Date]&first_name=[Guest_FirstName]&last_name=[Guest_LastName]&nationality=[Guest_Nacionality]&birthday=[Guest_Birthdate]&doc_id=[Guest_Document_Nr]&doc_type=[Guest_Document_Type]&doc_country=[Guest_Document_Country]&country_residence=[Guest_Country]"

{ 
	"status": "success" 
}
                     

Mandatory curl parameters:

rcode=[Reservation_Code] rcode=HMK71DA91ALK
arrival=[Arrival_Date] arrival=2023-05-20
departure=[Departure_Date] departure=2023-05-25
first_name=[Guest_FirstName] first_name=Alana (max. 40 chars)
last_name=[Guest_LastName] last_name=Bolsch (max. 40 chars)
nationality=[Guest_Nacionality_ICAO] nationality=FRA
birthday=[Guest_Birthdate] birthday=1990-12-01
doc_id=[Guest_Document_Nr] doc_id=123456789 (max. 16 chars)
doc_type=[Guest_Document_Type] doc_type=P (P for Passport; ID for ID Card; O for Other)
doc_country=[Guest_Document_Country_ICAO] doc_country=FRA
country_residence=[Guest_Country_ICAO] country_residence=FRA

removeGuest

This method removes a single guest data in a specific reservation.

curl "https://app.hostkit.pt/api/removeGuest?APIKEY=[Your_API_Key]&rcode=[Reservation_Code]&name=[Guest_First_or_Last_Name]"

{ 
	"status": "success" 
}
                     

Mandatory curl parameters:

rcode=[Reservation_Code] rcode=HMK71DA91ALK
name=[Guest_First_or_Last_Name] name=Alana

removeAllGuests

This method removes all guests data in a specific reservation.

curl "https://app.hostkit.pt/api/removeAllGuests?APIKEY=[Your_API_Key]&rcode=[Reservation_Code]"

{ 
	"status": "success" 
}
                     

Mandatory curl parameters:

rcode=[Reservation_Code] rcode=HMK71DA91ALK

API Changelog

CW19 2024: New endpoint to get smartlocks keycodes was created, getKeycode.

CW7 2024: New endpoint to get the status of online check-in was created, getOnlineCheckin.

CW2 2024: New endpoint to cancel reservations was created, cancelReservation.

CW47 2023: Implemented payment_method in endpoint addInvoice.

CW46 2023: Implemented invoice URL in endpoint closeInvoice.

CW44 2023: Implemented comment in endpoint addInvoice.

CW43 2023: Implemented a rate limit of 100 requests per each 10 seconds.

CW33 2023: New endpoint to update single reservation was created, updateReservation.

CW29 2023: Implemented invoice URL in endpoints getInvoices and getReservationInvoices.

CW22 2023: New endpoints for credit notes generation have been created, getCreditNotes and addCreditNote.


Copyright 2024 © Hostkit. All rights reserved. Hostkit is a registered trademark.