RESTful API Documentation.

Use the MyTourist API to integrate availability check, debtors and a lot more intro your website or app. MyTourist and your website or app back-end will communicate by sending HTTP requests back and forth. This page provides an overview of the MyTourist API. The topics in the chapter deal with a number of specific aspects of the API. We recommend to read these topics entirely.

If you have any questions about integrating our API, please contact us. We’re happy to help!

Quick jump to:

• Get an API key
• Risk and warranty
• Authentication
• Start developing, test and deploy
• Webhooks
• HTTP responses table
• API Endpoints

Calendar, Availability, Bookings, Debtors, Invoices, Products, ProductCategories, PriceRates, Roomtypes or TaxRates

• API Endpoints (certified access only)

• ObtainBearerToken

• Latest update 10th july ‘23

The MyTourist REST API

The API implements a Representational state transfer (REST) architecture. Sounds technical, but it’s really quite easy. It mainly breaks down to HTTP-methods GET, PATCH, POST and DELETE matching the operations to read, update, create and delete.

REST also implies a nice and clean structure for URLs or endpoints. This means you can reach any part of the MyTourist API on https://app.mytourist.com/api/v1 adding the name of the resource you want to interact with.

Default the throttle limit is 25 requests each 60 seconds. We can individually increase this amount but only on good substantiation. All endpoints will return their data in JSON format.

Obtain a API token

The first thing you need is a API token. Each location-/company profile has a API token printed inside the API page found in preferences. Of course it’s very important to keep your API token secure. Do not ever share them.

Use at your own risk / No warranty

We validate each request based on basic validation rules and you will operate outside the GUI of MyTourist with all the nice checks inside. You are responsible for the data you will add or change via the API. Each call is logged and kept for at least 24 months. We strongly recommend to test your API first in an dummy company profile before you use your production based company profile. Inside your account settings you are free to manage your company profiles. If your connection causes data to become corrupt, we can charge you to restore a backup of your company profile.

Authentication

The API token must be sent along with each API request, by providing it in the HTTP call’s Authorization header using the Bearer method. For example: a valid Authorization header is Bearer $2y$10$FP4s6cunWIGSjohTBDRO5eXNQAxWeG1.OxySTKv6FVVbaVhgwh7I6.

In the example below we use a API token on the GET method of the debtors resource. This method fetches a list of debtors.

curl -X GET https://app.mytourist.cloud/api/v1/debtors -H 'Authorization: Bearer $2y$10$FP4s6cunWIGSjohTBDRO5eXNQAxWeG1.OxySTKv6FVVbaVhgwh7I6'

Certification

For some eg. create/update endpoints an really good understanding of the OTA process is required. Thats why these functions are only available for contracted software/platform partners. To request access, please contact us.

Start developing, test and Deploy

By far Postman is a great tool to help you out in the first steps of build any connection with us. This tool enables you to test all GET/POST/PUT/Etc.. requests. We do sometimes host custom API’s on our high-end cluster infrastructure for our customers and direct partners. Please contact us for more information.

Webhooks

In Mytourist you will find the webhooks page within the settings page. Here you can enter URLs with a corresponding trigger point. As soon as a booking is checked in, checked out, created, edited or canceled, we will send a POST request to the URL you entered. This request contains trigger field and all booking data as described in the example json on the booking endpoint documentation page.

To test your webhooks, we recommend using https://webhook.site/.

HTTP responses table

200	OK	Request is done without any exceptions.
400	FAILED	Not all required parameters/fields are set to execute this request.
404	FAILED	URL incorrect or requested data no longer exists.
500	FAILED	Data you'll send us, can not be parsed.

API Endpoints

Calendar

The MyTourist calendar is the centralized space where all the magic happens. Your bookings, price rates, available rooms, and restrictions like min./max. stay and check-in/out restrictions printed into one single calendar. Go to the documentation or jump direct to Fetch the calendar data or Bulk changes

Availability

Check for available roomtypes in a predefined date range. This endpoint will return the roomtypes and available Rate plan ID’s. Go to the documentation

Debtors

Manage your debtors easily from this endpoint. Go to the documentation or jump direct to List all debtors, Retrieve a single debtor, Create / Update a debtor.

Bookings

Via this endpoint it is possible to add and manage bookings. It will create fully automatically the invoice and debtor. Bookings already placed by other connected providers are not editable. Go to the documentation or jump direct to List bookings between dates, List of bookings from specific debtor, Retrieve a single booking, Create a booking, Update a booking, Cancel a booking, Available form parameters, Available channels.

Invoices

With this endpoint you can manage your invoices, payments and product lines. Go to the documentation or jump direct to List invoices, Retrieve a single Invoice, Add or Update a simple invoice, Make invoice official by adding an unique ID, Manage product lines, Manage Payments, Download invoices.

TaxRates

You can manage your tax rates by this endpoint. Its based on an label and rate itself. Most of the time tax rates stay untouched, but can be changed via this API. Go to the documentation or jump direct to List all rates, Create / Update a rate, Delete a single rate.

Roomtypes

Via this endpoint you can obtain information about your roomtypes and rooms bellow. Changing roomtypes and their rooms need to be done via the MyTourist interface. Go to the documentation

Products

Products can be added to your invoices or as selectable additional product inside your booking engine. You can also add product fixed to bookings this becomes handy when you want to add final cleaning to each booking invoice. It is also possible to automatically calculate the price times the number of both guests and/or nights. Go to the documentation or jump direct to List all products, Retrieve a single product, Create a product, Update a product, Remove a product, Available form parameters.

ProductCategories

To keep a clean overview of all the product you’ll have. You can add a name and color to your categories, they only be visible for you and not for your customers. Go to the documentation or jump direct to List all product categories, Create or update a product category, Remove a product category, Available form parameters.

PriceRates

Each roomtype has his own set of price rates. You can have as many as you want, you can create eg. weekend arrangements or long and short-stay price rates based on a small amount of criteria. These price rates can be connected to platforms like booking.com. Go to the documentation or jump direct to .. List all price rates,Retrieve a single price rate, Create a price rate, Update a price rate, Delete a price rate.

API Endpoints (certified access only)

For the endpoints below, your own authentication bearer token in MyTourist must be marked as certified. Please contact us or start a ticket to begin the certification process.

ObtainBearerToken

This function makes it possible to request a bearer token on behalf of your customer in order to use the API. This way your customer does not have to log in to mytourist first to request his or her bearer token. Go to the documentation

Updates

2024 03 28 - We added public naming and descriptions, amenities, square_meters and picture URLS inside the roomtype endpoint.

2023 07 10 - All individual guest data will be displayed as well from now one by adding guests (object) to the JSON response inside the bookings endpoint.

2023 04 13 - Added the breakfast_booked (true/false) to the JSON response inside the bookings endpoint. And we solved an typo inside the invoices endpoint. total_payed changed into total_paid. We have also added the light mode on the bookings endpoint. List of bookings currently staying has now a light mode for faster response time.

2023 02 23 - We have added an extra function inside the bookings endpoint. List of bookings currently staying provides a list with booking who are leaving, staying of arriving today (or other date)

2022 11 01 - We have made an small correction to the invoices endpoint documentation. Making invoices final had a incorrect URL, and we added a parameter to this endpoint to set other invoice dates.

2022 05 26 - Added some extra times inside the expected_arrival_time parameter on the bookings endpoint and documented with the supported written times.

2022 04 27 - Registering payments in the invoices endpoint.

2022 04 05 - Corrected URL for downloading PDF invoices.

2022 01 24 - We improved the pricing examples inside the calendar endpoint for more information.

2022 01 12 - From now on it is possible to add door access codes access_code behind individual bookings. These can be sent to the customer later with, for example, automatic email templates. See the bookings endpoint for more information.

2021 11 22 - We moved the Availability Monthly calendar from the availability endpoint into it’s own endpoint called calendar. This because we released bulk changes into our API which is also an endpoint for the calendar. The old POST url into the availability endpoint is still working and redirects automatically to the new endpoint.

2021 10 22 - Latitude and Longitude (view and editable) added to the debtors endpoint.

2021 10 19

• Added mobile phone number to the endpoint debtor.
• Full debtor data is also shown on the bookings endpoint.
• Expected arrival is retrieve and editable from the bookings endpoint.
• We now trigger also the webhook booking_updated when an debtor is detached from the booking itself.

2021 07 07 - We added a new bookings endpoint List of bookings from specific debtor. Like List of bookings between dates, this function provides a list view of all bookings. But now based on a specific debtor ID.

2021 06 02 - We added related_bookings to the response JSON for the endpoints Retrieve a single booking and List bookings between dates. This way you can retrieve directly all the related sub-bookings (each booked room has their own booking id). Also check which booking is the main booking. In previous version only the main-booking gave back all the invoice data. We’d changed that so either the main of related sub booking return the invoice.