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 use case 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.

All our GET endpoints are also available on Make. Get our app here.

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

API Authentication

Authentication is done by using the following URL: https://app.hostkit.pt/api/endpoint?APIKEY=[Your_API_Key]

CURL components:

1. The API endpoint 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 enhanced security, API keys are property based, therefore must be generated and maintained in the Hostkit App -> Properties -> API key tab of each property.

API Rate Limit

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

API Enumerations

The possible enumerations that our API may request are:

API Errors

The possible errors that our API may return are:

API Endpoints

getProperty

This endpoint 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": "owner@myproperty.com",
	"activated": "1",
	"id": "1",
	"address": "R. das Quintinhas, 7", 
	"property_name": "Quintinhas",
	"cp": "1000-000", // zip
	"localidade": "Lisboa", // city
	"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@gestao.pt", 
	"invoicing_phone": "+351928617112", 
	"invoicing_address": "Av. Republica, 36, 1o", 
	"codigo_al": "12345", // registration number
	"tmt": "2", // city tax
	"comm_email": "mail@myproperty.com", 
	"property_info":"PHAVG....", // base64
	"default_series": "2022",
	"default_product": "Alojamento"
}
                     

getProperties

This endpoint returns ALL properties, similar data as getProperty but as a list.

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

addProperty

This endpoint allows to add a single property, using any existing APIKEY. Returns the ID and the corresponding APIKEY.

curl "https://app.hostkit.pt/api/addProperty?APIKEY=[Your_API_Key]&property_name=[Property_Name]&address=[Property_Address]&zip=[Property_ZIP_Code]&city=[Property_City]"

{ 
	"status": "success",
	"apid": "12345",
	"apikey": "XXXXXXX"
}
                     

Mandatory parameters:

Optional parameters:

Please find all available licenses types here.

updateProperty

This endpoint allows to update a single property, given an ID.

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

{ 
	"status": "success" 
}
                     

Mandatory parameters:

Optional parameters:

Please find all available licenses types here.

getReservation

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

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

{
	"owner": "owner@myproperty.com", 
	"rcode": "25901",
	"apid": "1234",
	"room": "",
	"beds": "",
	"firstname": "Antonio",
	"lastname": "Ficelli",
	"email": "email@guest.com", 
	"phone": "+39123456789",
	"flight": "TP821",
	"flight_time": "17:17",
	"arrival_by": "",
	"reservation_date": "1561489289", // unix timestamp
	"in_date": "1574255100",  // unix timestamp
	"out_date": "1574726400",  // unix timestamp
	"arrival": "1574208000",  // unix timestamp
	"departure": "1574726400",  // unix timestamp
	"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": "Milan"
	}],
	"service_in": "", 
	"service_out": "", 
	"service_cleaning": "",
	"service_laundry": "",
	"service_transfer_arr": "", 
	"service_transfer_dep": "", 
	"service_notes": "", 
	"private_note": "", 
	"feedback": "",
	"language": "en",
	"sefdate": "0",
	"provider": "airbnb", 
	"received_amount": "90", 
	"host_commission": "10",
	"extra_fees": "0",
	"city_tax": "0",
	"shortlink": "https://icheckin.pt/?9DSCNKPE", 
	"block_sef": "0",
	"block_emails": "0",
	"block_payments": "0",
	"block_invoicing": "0",
	"block_updates": "0"
}
                     

Mandatory parameters:

Optional parameters:

getReservationByCmId

This endpoint returns similar data as getReservation but by a Channel Manager reservation ID.

curl "https://app.hostkit.pt/api/getReservationByCmId?APIKEY=[Your_API_Key]&channelmanager=[CM_Name]&id=[CM_Reservation_ID]"

Mandatory parameters:

getReservations

This endpoint returns similar data as getReservation but as a list.

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

Optional parameters:

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 parameters:

Optional parameters:

Payment parameter:

Please find all available providers here.

updateReservation

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

{ 
	"status": "success" 
}
                     

Mandatory parameters:

Optional parameters:

Please find all available providers here.

cancelReservation

This endpoint 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 parameters:

deleteReservation

This endpoint deletes a specific reservation.

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

{ 
	"status": "success" 
}
                     

Mandatory parameters:

addReservationExtra

This endpoint adds an extra invoicing item to a specific reservation. Each extra is treated as an invoicing product, therefore use the same extra_id whenever possible.

curl "https://app.hostkit.pt/api/addReservationExtra?APIKEY=[Your_API_Key]&rcode=[Reservation_Code]&extra_id=[Extra_ID]&extra_name=[Extra_Name]&extra_vat=[Extra_VAT_Rate]&extra_total=[Extra_Total]&extra_type=[Extra_Type]"

{ 
	"status": "success" 
}
                     

Mandatory parameters:

If extra ID doesn't exist as product, we will create it in the respective invoicing account.

Please find all available invoicing product types here.

deleteReservationExtras

This endpoint deletes all extra items of a specific reservation.

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

{ 
	"status": "success"
}
                     

Mandatory parameters:

getKeycode

This endpoint gets the keycode or invite code of smartlocks of a specific reservation.

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

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

Mandatory parameters:

getPayments

This endpoint gets all payments for a specific reservation, as a list.

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

[
	{
	"amount": "250",
	"info": "Security deposit",
	"enabled": true, // false otherwise
	"paid": true // false otherwise
	},
	...
]
                     

Mandatory parameters:

getOnlineCheckin

This endpoint gets the link and online check-in status of a specific reservation.

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

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

Mandatory parameters:

addGuest

This endpoint 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 parameters:

removeGuest

This endpoint 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 parameters:

removeAllGuests

This endpoint 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 parameters:

validateSIBA

This endpoint receives data to be sent to SIBA and validates it by returning "success" if all data is correctly formatted.

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

{ 
	"status": "success" 
}
                     

Mandatory parameters:

sendSIBA

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

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

{ 
	"status": "success" 
}
                     

Mandatory parameters:

getLastSIBADate

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

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

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

getInvoices

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

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

[
	{
	"invoice_type": "FR",
	"series": "2023",
	"id": "10",
	"nif": "123456789", 
	"name": "John Smith", 
	"address": "",
	"value": "1.44",
	"date": "1620644915",  // unix timestamp
	"closed": "0",
	"rcode": "A8J2H8A", 
	"comment": "",
	"partial": false,
	"notes": "", // partial invoices
	"invoice_token": "dXNlcm5hbWU9aGZjYW5kZWlhc0BnbWFpbC5jb20",
	"invoice_url": "https://hostk.it/i/123/A1B2C3D4E5F6G7H8I9",
	"has_receipt": "0" // 0 no receipt, 1 receipt available (only for invoice_type FT)
	},
	...
]
                     

Optional parameters:

getReservationInvoices

This endpoint 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]"

[
	{
	"invoice_type": "FR",
	"series": "2022",
	"id": "9",
	"nif": "123456789",
	"name": "Melanie Johnson", 
	"address": "",
	"value": "129.06",
	"date": "1620641390",  // unix timestamp
	"closed": "1",
	"rcode": "1BVD4R",
	"comment": "",
	"partial": false,
	"notes": "", // partial invoices
	"invoice_token": "dXNlcm5hbWU9aGZjYW5kZWlhc0BnbWFpbC5jb20",
	"invoice_url": "https://hostk.it/i/123/A1B2C3D4E5F6G7H8I9",
	"has_receipt": "0" // 0 no receipt, 1 receipt available (only for invoice_type FT)
	},
	...
]
                     

Mandatory parameters:

Optional parameters:

addInvoice

This endpoint allows to create a new invoice. The invoice will NOT be created if a draft exists in the same invoicing VAT ID and series. If no VAT ID or series are specified, it will be used the default from the property.

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

{ 
	"status": "success",
	"id": "35" // use this to addInvoiceLine, closeInvoice, addReceipt or addCreditNote
}
                     

Mandatory parameters:

Optional parameters:

addInvoiceLine

This endpoint allows to add a new invoice line into an existing draft invoice.

curl "https://app.hostkit.pt/api/addInvoiceLine?APIKEY=[Your_API_Key]&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": "1"
}
                     

Mandatory parameters:

closeInvoice

This endpoint closes a draft invoice.

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

{ 
	"status": "success",
	"invoice_token": "dXNlcm5hbWU9aGZjYW5kZWlhc0BnbWFpbC5jb20",
	"invoice_url": "https://hostk.it/i/123/A1B2C3D4E5F6G7H8I9"
}
                     

Mandatory parameters:

deleteInvoice

This endpoint deletes a DRAFT invoice.

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

{ 
	"status": "success"
}
                     

Mandatory parameters:

getReceipts

This endpoint returns the receipts as a list. If no invoicing VAT ID is specified, it will be used the default from the property.

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

[
	{
	"series": "2023",
	"id": "1",
	"nif": "123456789", 
	"value": "1.44",
	"date": "1620644915",  // unix timestamp
	"refseries": "2023",
	"refid": "10",
	"receipt_token": "dXNlcm5hbWU9aGZjYW5kZWlhc0BnbWFpbC5jb20",
	"receipt_url": "https://hostk.it/i/123/A1B2C3D4E5F6G7H8I9"
	},
	...
]
                     

Optional parameters:

addReceipt

This endpoint allows to create a receipt based on an EXISTING CLOSED invoice. If no invoicing VAT ID or series is specified, it will be used the default from the property.

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

{ 
	"status": "success",
	"id": "5"
}
                     

Mandatory parameters:

getCreditNotes

This endpoint returns the all credit notes as a list. If no invoicing VAT ID is specified, it will be used the default from the property.

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",  // unix timestamp
	"reason": "",
	"refseries": "2022",
	"refid": "10",
	"reftype": "FR",
	"credit_note_token": "dXNlcm5hbWU9aGZjYW5kZWlhc0BnbWFpbC5jb20",
	"credit_note_url": "https://hostk.it/i/123/A1B2C3D4E5F6G7H8I9"
	},
	...
]
                     

Optional parameters:

Please find all available invoice types here.

addCreditNote

This endpoint allows to create a credit note based on an EXISTING CLOSED invoice. If no invoicing VAT ID or series is specified, it will be used the default from the property.

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

{ 
	"status": "success",
	"id": "5"
}
                     

Mandatory parameters:

Please find all available invoice types here.

generateSAFT

This endpoint allows to generate a SAFT based on an EXISTING invoicing account.

curl "https://app.hostkit.pt/api/generateSAFT?APIKEY=[Your_API_Key]&invoicing_nif=[Invoicing_VAT_ID]&year=[Year]&month=[Month]"

{ 
	"status": "success"
}
                     

Mandatory parameters:

getSAFT

This endpoint allows to get a SAFT from an EXISTING invoicing account. SAFT content output is in base64.

curl "https://app.hostkit.pt/api/getSAFT?APIKEY=[Your_API_Key]&invoicing_nif=[Invoicing_VAT_ID]&year=[Year]&month=[Month]"

{ 
	"generated": "2024-08-16 10:00:00",
	"sent": "2024-08-16 10:00:01",
	"saft": "PD94bWwgdmVyc..." // base64
}
                     

Mandatory parameters:

getExpenses

This endpoint returns the all expenses as a list, based on document date.

curl "https://app.hostkit.pt/api/getExpenses?APIKEY=[Your_API_Key]&date_start=[Document_Date_Start_UnixTimeStamp]&date_end=[Document_Date_End_UnixTimeStamp]"

[
	{
	"id": "1",
	"active": "1", // 1 for active, 0 for inactive
	"category": "furniture",
	"type": "variable", 
	"vendor": "IKEA",
	"description": "Lorem ipsum",
	"number": "123456789", 
	"amount": "50.00",
	"vat": "23", // rate percentage
	"document_date": "1730000000", // unix timestamp
	"creation_date": "1730000000", // unix timestamp
	"payment_date": "1730000000", // unix timestamp
	"last_update_date": "1730000000", // unix timestamp
	"lines": [{
		"line_id": "1", 
		"line_description": "Lorem ipsum", 
		"line_amount": "50.00", 
		"line_vat": "23"
	}]
	},
	...
]
                     

Mandatory parameters:

getLicense

This endpoint returns the license expiration date.

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

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

API Changelog

CW4 2024: New endpoints to add or delete reservation extra items were created, addReservationExtra and deteteReservationExtras.

CW49 2025: New endpoint to add a receipt was created, addReceipt.

CW47 2025: New endpoint to get receipts was created, getReceipts.

CW45 2025: Implemented create_payment in endpoint addReservation.

CW44 2025: Implemented room, vat_number and vat_name in endpoint addReservation.

CW41 2025: New endpoint to add properties was created, addProperty.

CW37 2025: New endpoint to update properties was created, updateProperty.

CW24 2025: sendSEF is now sendSIBA. validateSEF is now validateSIBA. getLastSEFDate is now getLastSIBADate.

CW20 2025: New endpoint to get expenses was created, getExpenses.

CW8 2025: New endpoint to get reservation by Channel Manager ID was created, getReservationByCmId.

CW43 2024: Updated endpoint getInvoices with new customer ID and date filters.

CW33 2024: New endpoints to generate and get SAFTs were created, generateSAFT and getSAFT.

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.