Use the MyTourist API to integrate availability checks, bookings, debtors, invoices and a lot more into your website or app. MyTourist and your back-end communicate by sending HTTP requests back and forth.
The API implements a REST architecture. Sounds technical, but it is really quite easy: the HTTP methods GET, POST and DELETE match the operations to read, create or update, and delete. Every resource lives under one base URL, followed by the name of the resource you want to interact with.
We recommend reading these introduction topics entirely. If you have any questions about integrating our API, please contact us. We're happy to help!
Base URL
{BASE_URL}
Obtain an API token
The first thing you need is an API token. Each company profile has its own API token, shown on the API page in MyTourist (Connections → API). It is very important to keep your API token secure: never share it and never use it in front-end code. You can reset the token on the API page at any time; the old token stops working immediately.
Authentication
The API token must be sent with each API request in the Authorization header, using the Bearer method:
Authorization: Bearer {YOUR_API_TOKEN}
A request without a valid token returns HTTP 403 with the message Access denied, bearer token not found!. In the example on the right we use the API token to fetch the list of debtors.
Example request
curl -X GET '{BASE_URL}/debtors' \
-H 'Authorization: Bearer {YOUR_API_TOKEN}'
Requests and responses
Send parameters as form fields (multipart/form-data or application/x-www-form-urlencoded) or as a JSON body with the header Content-Type: application/json. Query parameters of GET requests go in the URL.
Every response is JSON, except the invoice PDF download.
Updates are partial: when you leave out a field, we keep the current value. When you send a field empty, it is cleared or reset to its default.
IDs are strings or numbers as shown in the examples. Always use the id from a response; never guess them.
The API is rate limited to 10 requests per 10 seconds. Above that, requests are refused with HTTP 429. Use the list endpoints with a date range instead of fetching items one by one.
Use at your own risk
No warranty: the API is provided as is. Test in a dummy company profile first.
We validate each request on basic rules, but via the API you operate outside the MyTourist interface and its checks. You are responsible for the data you add or change via the API. Each call is logged and kept for at least 24 months; you can see the most recent calls on the API page under "Recent API calls".
We strongly recommend testing your connection in a dummy company profile before you use it on your production profile. You can manage your company profiles in your account settings. If your connection causes data to become corrupt, we can charge you for restoring a backup of your company profile.
Start developing, test and deploy
Postman is a great tool for the first steps of building a connection. It lets you test all GET, POST and DELETE requests before you write any code. Leave the "Recent API calls" window on the API page open while you test: it refreshes every 10 seconds and shows each call with its result.
We sometimes host custom APIs on our infrastructure for customers and direct partners. Please contact us for more information.
HTTP responses
Every response comes with one of these HTTP status codes. On an error, the body contains a short message that tells you what went wrong.
Code
Status
Meaning
200
OK
The request has been processed without any exceptions.
204
No content
The calendar cache is being built. Try again in a moment.
400
Failed
Not all required parameters are set, or the action is not allowed.
403
Forbidden
The bearer token is missing or not valid.
404
Not found
The URL is incorrect or the requested data no longer exists.
429
Too many requests
More than 10 requests in 10 seconds. Wait a moment and try again.
500
Error
The data you sent us could not be processed.
Common error messages
Message
When
Access denied, bearer token not found!
The bearer token is missing or invalid.
Missing required field(s)
Required parameters are missing.
Start-/end date are not set, or selected time period is longer than 36 days.
Invoice or payment list without a valid date range.
Not possible to cancel bookings from external platforms.
You tried to cancel a booking from a connected channel.
No rates are set for this roomtype
The roomtype has no price rates, so the booking cannot be created.
Category locked
You tried to change or delete the default product category.
Property
General address and company data of the company profile that belongs to the API token.
1 endpoints
Retrieve property data
GET/api/v1/property
Returns the address, contact and bank details of the company profile.
Fields in the response 20
uniquestring
ID of the company profile.
namestring
Company name.
streetstring|null
Street and house number.
zipcodestring|null
citystring|null
countrystring|null
ISO 3166-1 alpha-2.
websitestring|null
emailstring|null
phonestring|null
mobilestring|null
currencystring
ISO 4217, for example EUR.
iban_namestring|null
Account holder.
ibanstring|null
bicstring|null
iban_alt_namestring|null
Account holder of the second bank account.
iban_altstring|null
Second bank account.
bic_altstring|null
company_idstring|null
Chamber of commerce number.
registration_idstring|null
VAT number.
custom_coordinatesboolean|null
The location on the map is set by hand.
Request
curl -X GET '{BASE_URL}/property' \
-H 'Authorization: Bearer {YOUR_API_TOKEN}'
Add and manage bookings. When you create a booking, MyTourist automatically creates the invoice and attaches the debtor. Bookings placed by other connected channels are partly locked.
11 endpoints
List bookings between dates
GET/api/v1/bookings
Returns all bookings in the period for each roomtype in your account. To prevent heavy requests you need to give a from and until date; these may not be more than 36 days apart.
Returns all bookings that arrive, stay or depart on the given date (default today). Like the insights page in MyTourist, the bookings are sorted by the order of the rooms and roomtypes.
This endpoint expects that you have already checked the availability. It validates the availability of the roomtype once more, but checking it first with the availability endpoint is faster.
const body = new FormData();
body.append('number_of_guests', '3');
body.append('recalculate_invoice_logies', 'true');
const response = await fetch('{BASE_URL}/bookings/{BOOKING_ID}', {
method: 'POST',
headers: {
'Authorization': 'Bearer {YOUR_API_TOKEN}'
},
body
});
const data = await response.json();
Cancel a booking
DELETE/api/v1/bookings/{BOOKING_ID}
Only bookings from mytourist, website (booking engine) or api can be cancelled via the API. Bookings with a live connection to an external platform cannot be cancelled here. If a booking is out of sync, please contact support.
const body = new FormData();
body.append('main_reservation', '1210531312');
const response = await fetch('{BASE_URL}/bookings/{BOOKING_ID}/attach', {
method: 'POST',
headers: {
'Authorization': 'Bearer {YOUR_API_TOKEN}'
},
body
});
const data = await response.json();
Detach from a booking
POST/api/v1/bookings/{BOOKING_ID}/detach
Detach this booking from its main booking. MyTourist creates a new invoice for the detached booking. Only bookings from mytourist, website or api can be detached.
Request
curl -X POST '{BASE_URL}/bookings/{BOOKING_ID}/detach' \
-H 'Authorization: Bearer {YOUR_API_TOKEN}'
const body = new FormData();
body.append('firstname', 'Max');
body.append('lastname', 'Musterman');
const response = await fetch('{BASE_URL}/bookings/{BOOKING_ID}/guests/{GUEST_ID}', {
method: 'POST',
headers: {
'Authorization': 'Bearer {YOUR_API_TOKEN}'
},
body
});
const data = await response.json();
Available channels
Channel
Meaning
mytourist
Creates the booking as if it was created in the MyTourist interface.
api
Creates the booking as an external channel. The booking is locked in MyTourist and can only be changed via the API.
Availability
Check which roomtypes are available in a date range, with the calculated total logies price per price rate. With this result you have enough data to create a booking.
1 endpoints
Check availability
GET/api/v1/availability
This endpoint returns cached results. The cache refreshes after a change in your account; it can take a few minutes before the change is visible.
Checks the availability of one or all roomtypes in a date range. The API always returns the number of available rooms per roomtype, some information about the roomtype (so you need fewer calls to the roomtypes endpoint) and its price rates.
Need the availability and price per day, for example for a calendar? Use Fetch the calendar data instead.
[
{
"id": "81912063",
"rooms_available": 1,
"name": "Doubleroom Deluxe with balcony",
"description": "Our best room with an amazing view over the city!",
"rates": [
{
"id": 66118004,
"rate_available": true,
"total_price": 200,
"name": "Conform arrangement",
"reasons": []
},
{
"id": 82010274,
"rate_available": false,
"total_price": 0,
"name": "Bubbles arrangement - Long weekend",
"reasons": ["closedonarrival", "minstay"]
}
]
}
]
Calendar
The MyTourist calendar is the central place where it all comes together: bookings, price rates, available rooms and restrictions like minimum and maximum stay and closed for arrival or departure.
3 endpoints
Fetch the calendar data
POST/api/v1/calendar
This endpoint returns cached results. The cache refreshes after a change in your account; it can take a few minutes. While the cache is being built, you get HTTP 204: try again shortly.
Returns the number of available rooms and the current logies price per price rate for each day of the month of the given date. You can fetch all roomtypes or a single one.
Parameters
datedaterequired
Format YYYY-MM-DD. The month of this date is returned.
Change the availability, price and restrictions of one price rate for one day or a period. With this endpoint you no longer need to make bulk changes in the MyTourist calendar by hand. The until date may be at most 2 years ahead.
Parameters
fromdaterequired
Format YYYY-MM-DD.
untildaterequired
Format YYYY-MM-DD.
rooms_to_sellinteger
Rooms to sell; never higher than the actual number of rooms. Bookings are subtracted automatically. Use auto for the default.
min_stayinteger
Nights, or auto for the default of the price rate.
max_stayinteger
Nights, or auto for the default of the price rate.
close_to_arrivalstring
closed or open, or default to reset to the price rate settings.
close_to_departurestring
closed or open, or default to reset to the price rate settings.
Returns the debtors that match all given search terms. Searched fields: first name, last name, company name, company ID, email, phone, street, city, zipcode and debtor ID.
By default, MyTourist creates an invoice for each booking and calculates the logies price, tourist tax and fixed products. You can also create single invoices without a booking, for example for boat or bike rentals, a bar or activities. With these endpoints you manage invoices, product lines and payments.
14 endpoints
List invoices
GET/api/v1/invoices
Returns all invoices with an invoice date in the period. To prevent heavy server load, from and until are required and may be at most 36 days apart.
Query parameters
fromdaterequired
Format YYYY-MM-DD.
untildaterequired
Format YYYY-MM-DD.
Fields in the response 30
idstring
Invoice ID, for example P1020077. Use it for the other invoice endpoints.
invoiced_atstring
Invoice date, YYYYMMDD.
invoice_idstring|null
Invoice number from your administration; null while the invoice is a proforma.
languagestring
Language of the invoice.
typestring
proforma, invoice or creditinvoice. See the table.
Reference of the customer, for example an order or PO number.
product_lines[].idstring
Line ID. Use it to update or remove the line.
product_lines[].typestring
logies or product.
product_lines[].numbernumber
Number of items.
product_lines[].descriptionstring
product_lines[].price_incl_vatstring
Total of the line incl. VAT.
product_lines[].price_excl_vatstring
Total of the line excl. VAT.
product_lines[].tax_amountstring
VAT amount of the line.
product_lines[].tax_ratestring|null
VAT percentage.
product_lines[].tax_typestring|null
Type of the tax rate: standard, zero (0% VAT) or exempt (no VAT: exempt or outside the scope of VAT, tax_rate is then 0). null when the line has no tax rate or was created before this field existed.
product_lines[].product_idstring|null
ID of the product, or null for a line added by hand.
tourist_taxobject
Only for booking invoices: amount, based_on_guests and outdated.
vat_linesobject
VAT amount per rate: { "21": 12.50 }. Lines without VAT (tax_typeexempt) are under the key exempt, always with amount 0: { "21": 12.50, "exempt": 0 }.
Reference of the customer, for example an order or PO number.
product_lines[].idstring
Line ID. Use it to update or remove the line.
product_lines[].typestring
logies or product.
product_lines[].numbernumber
Number of items.
product_lines[].descriptionstring
product_lines[].price_incl_vatstring
Total of the line incl. VAT.
product_lines[].price_excl_vatstring
Total of the line excl. VAT.
product_lines[].tax_amountstring
VAT amount of the line.
product_lines[].tax_ratestring|null
VAT percentage.
product_lines[].tax_typestring|null
Type of the tax rate: standard, zero (0% VAT) or exempt (no VAT: exempt or outside the scope of VAT, tax_rate is then 0). null when the line has no tax rate or was created before this field existed.
product_lines[].product_idstring|null
ID of the product, or null for a line added by hand.
tourist_taxobject
Only for booking invoices: amount, based_on_guests and outdated.
vat_linesobject
VAT amount per rate: { "21": 12.50 }. Lines without VAT (tax_typeexempt) are under the key exempt, always with amount 0: { "21": 12.50, "exempt": 0 }.
Creates a single invoice without a booking. It works exactly like a booking invoice, except that the automatic price calculation (price rates and tourist tax) is not active. A new invoice is always a proforma.
Reference (for example the order or PO number of the customer), shown on the invoice. Max. 255 characters; send it empty to clear it.
Response
Returns the updated invoice.
Request
curl -X POST '{BASE_URL}/invoices/{INVOICE_ID}' \
-H 'Authorization: Bearer {YOUR_API_TOKEN}' \
--form 'reference=PO-12345' \
--form 'footnote=Thank you for your stay!'
$client = new \GuzzleHttp\Client();
$response = $client->request('POST', '{BASE_URL}/invoices/{INVOICE_ID}', [
'headers' => [
'Authorization' => 'Bearer {YOUR_API_TOKEN}',
],
'form_params' => [
'reference' => 'PO-12345',
'footnote' => 'Thank you for your stay!',
],
]);
$data = json_decode($response->getBody(), true);
const body = new FormData();
body.append('reference', 'PO-12345');
body.append('footnote', 'Thank you for your stay!');
const response = await fetch('{BASE_URL}/invoices/{INVOICE_ID}', {
method: 'POST',
headers: {
'Authorization': 'Bearer {YOUR_API_TOKEN}'
},
body
});
const data = await response.json();
Make an invoice final
POST/api/v1/invoices/make-final/{INVOICE_ID}
Gives the proforma invoice the next invoice number from your administration and changes its type to invoice. A final invoice can no longer be removed; it can only be credited.
Parameters
invoice_datedate
Format YYYY-MM-DD. Default: today.
Response
Returns the final invoice.
Request
curl -X POST '{BASE_URL}/invoices/make-final/{INVOICE_ID}' \
-H 'Authorization: Bearer {YOUR_API_TOKEN}'
Creates a credit invoice for a final invoice: a copy with the same lines, all with negative amounts. This is the same as the button "Credit" in MyTourist. The credit invoice starts as a proforma, so you can still check it; make it final with its id. Only final invoices can be credited (HTTP 400 for a proforma).
Roomtypes are groups of rooms, like "Doubleroom" with "Room 6, 1st floor" and "Room 4, 3rd floor". A B&B often has one room per roomtype, with the same name. Roomtypes and rooms are managed in MyTourist; via the API you can read them.
1 endpoints
List all roomtypes
GET/api/v1/roomtypes
Returns all roomtypes with their rooms, pictures and price rates.
Query parameters
languagestring
ISO 639-1, for example en.
Fields in the response 12
idstring
Roomtype ID. Use it as roomtype_id in other endpoints.
typestring
Kind of roomtype, for example double.
number_of_roomsinteger
namestring
Internal name.
square_metersinteger|null
amenitiesarray
Codes of the amenities, for example safe or hair_dryer.
public_namesobject
Name in the booking engine per language.
public_descriptionsobject
Description per language.
default_picturestring|null
URL of the main picture.
picturesarray
URLs of all pictures.
rooms[]array
Rooms: id (use it as unit_id in bookings) and name.
rates[]array
Price rates: id, name and public_names.
Request
curl -X GET '{BASE_URL}/roomtypes' \
-H 'Authorization: Bearer {YOUR_API_TOKEN}'
Each roomtype has its own price rates. You can have as many as you want, for example weekend arrangements or long and short stay rates. Price rates can be connected to channels like Booking.com.
2 endpoints
List all price rates
GET/api/v1/price-rates
Returns the price rates of one roomtype, or of all roomtypes.
Query parameters
roomtype_idstring
Recommended. Only return the price rates of this roomtype.
languagestring
ISO 639-1, for example en.
Fields explained
Field
Meaning
parent_id
Set when the rate is a sub rate of another rate (cleaner calendar, price can follow the parent in percentages).
public_name
When the rate is visible in the booking engine, your name is translated automatically into about 15 languages.
enabled_for_booking_engine
The rate is bookable in your booking engine.
min_advance / max_advance
Number of hours before arrival.
closed_on_arrival
Weekdays without arrival: mo,tu,we,th,fr,sa,su.
closed_on_departure
Weekdays without departure: mo,tu,we,th,fr,sa,su.
default_price_per_night
Default price per night, in your currency or as a percentage.
price_per_night_percentage
The price is a percentage of the parent rate (only for sub rates).
const body = new FormData();
body.append('label', 'Exempt');
body.append('rate', '0');
body.append('type', 'exempt');
body.append('invoice_note', 'Exempt from VAT under article 11');
const response = await fetch('{BASE_URL}/tax-rates', {
method: 'POST',
headers: {
'Authorization': 'Bearer {YOUR_API_TOKEN}'
},
body
});
const data = await response.json();
Update a tax rate
POST/api/v1/tax-rates/{RATE_ID}
Final invoices keep the rate and type they were made with. Proforma invoices follow the change when you save the rate in the app with Apply to all proforma invoices.
Changes the fields you send and returns the tax rate.
Parameters
labelstring
ratefloat
Percentage. Ignored (set to 0) for the types zero and exempt.
typestring
standard, zero or exempt.
invoice_notestring
Text on the invoice. Send an empty value to remove it.
Check your products and invoice lines before you delete a tax rate.
Invoice lines can still refer to this rate. Existing invoices keep their calculated amounts, but when you change such a line later, no tax is calculated anymore.
Products can be added to invoices, or offered as extras in your booking engine. You can also add a product to each booking automatically, for example final cleaning, and calculate the price per guest and/or per night.
5 endpoints
List all products
GET/api/v1/products
Returns all your products.
Fields in the response 9
idstring
Product ID. Use it as product_id in invoice lines.
We advise to write name and description in the language of your invoices, so your invoices do not show an automatic translation. Translations of name and description are made automatically 30 minutes after your last change.
Parameters
languagestringrequired
nl, de, fr or en: the language of name and description.
Get a message from MyTourist as soon as something happens with a booking, instead of asking the API again and again.
Set up webhooks
You find the webhooks page under Connections → Webhooks. Add a URL (starting with https://, max. 250 characters) and choose when it is called. As soon as that happens, we send a POST request to your URL.
The body contains the field trigger plus all booking data, in the same format as Retrieve a booking.
Reply with HTTP 200 to confirm that you received the webhook. Any other response, or no response, counts as failed. A failed webhook is sent again after 5, 15 and 60 minutes. After the third retry we stop.