Hi, developer!

This is the documentation for the tablebooker API.
Do you want to use this API? Contact us at dev@tablebooker.be.


Deprecation warning

This is the documentation for the Tablebooker V1 API. This version has been deprecated in favor of the V2 API.

The v1 API will become unavailable in the near future. So if you are already using it, please make sure to update your application soon. Instructions on how to migrate to V2 can be found here: https://api.tablebooker.be/#migration_to_v2.

Content Types

The tablebooker API supports a bunch of different request/response formats, including XML and JSON.

You can change the content type of the response by appending the format to the base URL, or by adding the format parameter to the request. This means your URLs can look like this:

https://api.tablebooker.be/v1/restaurants/info.xml
https://api.tablebooker.be/v1/restaurants/info?format=json

You can also set the HTTP Accept header to specify the format.

$ curl -H "Accept: application/xml" https://api.tablebooker.be/v1/restaurants

Multilingual Support

The tablebooker API will automatically parse the HTTP Accept-Language header and provide the required language in the responses. Currently only Dutch (nl), French (fr) and English (en) are supported.

$ curl -H "Accept-Language: nl" https://api.tablebooker.be/v1/...

API Key

In order to connect and use our API, you need to request an API key. You should set your API key in the header of every request you make.

$ curl -H "X-API-KEY: your_key_here" https://api.tablebooker.be/v1/...

Restaurant Information

The restaurant information API returns all public information on a specific restaurant. The base URL for this GET data source is:

https://api.tablebooker.be/v1/restaurants/info

The restaurant can be specified in multiple ways. The easiest way is to use the tablebooker ID of the restaurant. The tablebooker ID is the 7+ digit ID you can find in the URL of the restaurant page on www.tablebooker.be. The tablebooker ID can be added to the info URL as an URL segment or a GET parameter:

https://api.tablebooker.be/v1/restaurants/info/1234567
https://api.tablebooker.be/v1/restaurants/info?tablebooker_id=1234567

Additionally, you can use IDs of other services, such as Foursquare, to specify the restaurant. Currently, we support the following services:

Service Parameter URL
tablebooker tablebooker_id www.tablebooker.be
Resto resto_id www.resto.be
Yelp yelp_id www.yelp.be
Foursquare foursquare_id www.foursquare.com
Foodspotting foodspotting_id www.foodspotting.com

The restaurant search API returns a list of tablebooker restaurants near a location, optionally matching a search term. The base URL for this GET data source is:

https://api.tablebooker.be/v1/restaurants/search

The location of the restaurants can be specified using a city name or a latitude/longitude value. Optionally, an extra search term can be added to filter the returned restaurants.

By default, the restaurant list is limited to pages of 20 restaurants. Using the page parameter, additional restaurants can be fetched. The rpp parameter can be used to change the number of restaurants per page.

Parameters

All parameters are optional, unless otherwise indicated.

city Antwerpen Required unless latlng is specified. Name of the city in which the user is looking for restaurants.
latlng 44.3,37.2 Required unless city is specified. Latitude and longitude of the user's location, separated with a comma. If this parameter is specified, a distance field (in kilometers) is added to every restaurant in the result list.
radius 5 Limit results to restaurants within this number of kilometers of the specified location. Default is 10 kilometers, maximum is 25 km.
query leeuw Limit results to restaurant names that match this search term.
page 4 The page number of the requested page. Defaults to the first page (with page number 1).
rpp 10 Results per page. Default is 20.

Restaurant Availability

The restaurant availability interface allows you to retrieve the availability of one or more restaurants on a given day for a certain amount of people. The base URL for this GET data source is:

https://api.tablebooker.be/v1/restaurants/availability

The API method returns for each restaurant the general availability (boolean), a general message (which should be shown to the user if present) and a list of all possible arrival times during opening hours. If the time parameter is specified, only this time slot is returned. For each of the arrival times, the availability for this time slot is shown (boolean) together with a list of messages that have to be shown to the end user when the user selects this arrival time.

Parameters

All parameters are optional, unless specified otherwise.

tablebooker_id 0003487,0001234 Required A single tablebooker ID, or a comma-separated list of tablebooker IDs.
date 2019-10-19 Required Show the availability for this date. Specified in the format YYYY-MM-DD.
guests 4 Required Show the availability for this amount of guests.
time 19:00 Show the availability for this time only.

Restaurant Menu

The restaurant menu API returns the menu information of a restaurant. The base URL for this GET data source is:

https://api.tablebooker.be/v1/restaurants/menu

The restaurant can be specified by providing the tablebooker_id. The tablebooker ID is the 7+ digit ID you can find in the URL of the restaurant page on www.tablebooker.be. The tablebooker ID can be added to the info URL as an URL segment or a GET parameter:

https://api.tablebooker.be/v1/restaurants/menu/1234567
https://api.tablebooker.be/v1/restaurants/menu?tablebooker_id=1234567
tablebooker_id 1234567 Required unless the id is specified as an URL segment. A single tablebooker ID.

Send message to restaurant

The "Restaurant Message" API makes it possible to send a message to the restaurant.
The base URL for this POST data source is:

https://api.tablebooker.be/v1/restaurants/message/{restaurantId}

Authentication

Basic auth is required for this call.

Parameters

subject "My message subject" Optional subject line. A default subject will be used when this is not filled in.
message "My message for the restaurant" Required The actual message.
reservation_id 00124356 An optional reservation id. When the id is passed, the message will be linked to the reservation.
sender_name John Doe Optional/Required The name of the sender. This field is only required when no Reservation Id is supplied.
sender_email john@doe.com Optional/Required The email address of the sender. This field is only required when no Reservation Id is supplied.

Response

The response contains a status field, which is either "OK" when the message was send successfully, or "error" when something went wrong.

When the message was successful it also returns the message Id.

When returning an error response, this response is accompanied with an error_code field. This error code can be used to handle the error correctly, and to return the appropriate error message to the customer. In the table below you can find a list of possible error codes.

error_code HTTP Status code Explanation
unknown_reservation 404 The specified reservation is unknown and could not be updated.
invalid_field 400 One of the input fields is invalid or missing. This message is accompanied with an extra field field, which contains the name of the field that is missing or contains invalid input.
unexpected_error 500 Something went wrong trying to make this reservation. Contact us at support@tablebooker.be with the request details if this response occurs frequently.

Making a reservation

The "New reservation" API makes it possible to add a new reservation to the calendar of a restaurant.
The base URL for this POST data source is:

https://api.tablebooker.be/v1/reservations/new

Parameters

tablebooker_id 0001234 Required The tablebooker ID of the restaurant in which the reservation should be made.
date 2019-10-19 Required Make a reservation on this day. Specified in the format YYYY-MM-DD.
time 19:00 Required Make a reservation at this arrival time. Specified in the format HH:MM. The restaurant should accept reservations at this time, and the time slot should be available.
guests 4 Required Make a reservation for this amount of guests.
customer_id 12345678 The customer ID that was returned by the login API.
customer_token f94e59...e405ac The customer token that was returned by the login API.
customer_type personal Required unless customer_id and customer_token are specified.
The type of the customer making a reservation, either "personal" or "business".
customer_lastname Janssens Required unless customer_id and customer_token are specified.
The last name of the customer for which a reservation is made.
customer_firstname Koen The first name of the customer for which a reservation is made.
customer_phone 031234567 Required unless customer_id and customer_token are specified.
The phone number of the customer for which a reservation is made.
customer_email koen.janssens@exemple.be Required unless customer_id and customer_token are specified.
The email address of the customer for which a reservation is made.
customer_company tablebooker CVBA Required when customer_type is "business", unless customer_id and customer_token are specified.
The company for which a reservation is made.
customer_vat BE0849393861 Required when customer_type is "business", unless customer_id and customer_token are specified.
The VAT number of the company for which a reservation is made.
customer_message This is a message An optional message to go with the reservation. For example a message about allergies or seating.

Response

The response contains a status field, which is either "OK" when the reservation has been made successfully, or "error" when something went wrong.

When returning an error response, this response is accompanied with an error_code field. This error code can be used to handle the error correctly, and to return the appropriate error message to the customer. In the table below you can find a list of possible error codes.

error_code HTTP Status code Explanation
unknown_restaurant 404 The specified restaurant is unknown or doesn't accept reservations from you.
invalid_field 400 One of the input fields is invalid or missing. This message is accompanied with an extra field field, which contains the name of the field that is missing or contains invalid input.
no_table_available 403 There is no table available for making this reservation. Check again using the availability API before making a reservation attempt.
invalid_customer_credentials 403 Could not authenticate the customer using the customer_id and customer_token. Prompt the user to log in again.
unexpected_error 500 Something went wrong trying to make this reservation. Contact us at support@tablebooker.be with the request details if this response occurs frequently.

Update a reservation

The "Update reservation" API makes it possible to update an existing reservation.
The base URL for this POST data source is:

https://api.tablebooker.be/v1/reservations/update/{reservationId}

Authentication

Basic auth is required for this call.

Parameters

date 2019-10-19 Required Make a reservation on this day. Specified in the format YYYY-MM-DD.
time 19:00 Required Make a reservation at this arrival time. Specified in the format HH:MM. The restaurant should accept reservations at this time, and the time slot should be available.
guests 4 Required Make a reservation for this amount of guests.

Response

The response contains a status field, which is either "OK" when the reservation has been updated successfully, or "error" when something went wrong.

When the change was successfull it also returns the reservation Id, the reservation status and the reservation url.

When returning an error response, this response is accompanied with an error_code field. This error code can be used to handle the error correctly, and to return the appropriate error message to the customer. In the table below you can find a list of possible error codes.

error_code HTTP Status code Explanation
unknown_reservation 404 The specified reservation is unknown and could not be updated.
invalid_field 400 One of the input fields is invalid or missing. This message is accompanied with an extra field field, which contains the name of the field that is missing or contains invalid input.
no_table_available 403 There is no table available for making this reservation. Check again using the availability API before making a reservation attempt.
unexpected_error 500 Something went wrong trying to make this reservation. Contact us at support@tablebooker.be with the request details if this response occurs frequently.

Cancel a reservation

The "Cancel reservation" API makes it possible to cancel an existing reservation.
The base URL for this POST data source is:

https://api.tablebooker.be/v1/reservations/cancel/{reservationId}

Authentication

Basic auth is required for this call.

Parameters

No additional parameters

Response

The response contains a status field, which is either "OK" when the reservation has been cancelled successfully, or "error" when something went wrong.

When the cancellation was successful then the response also contains the reservation id, reservation status and reservation url.

When returning an error response, this response is accompanied with an error_code field. This error code can be used to handle the error correctly, and to return the appropriate error message to the customer. In the table below you can find a list of possible error codes.

error_code HTTP Status code Explanation
unknown_reservation 404 The specified reservation is unknown.
invalid_field 400 One of the input fields is invalid or missing. This message is accompanied with an extra field field, which contains the name of the field that is missing or contains invalid input.
no_table_available 403 There is no table available for making this reservation. Check again using the availability API before making a reservation attempt.
invalid_customer_credentials 403 Could not authenticate the customer using the customer_id and customer_token. Prompt the user to log in again.
unexpected_error 500 Something went wrong trying to make this reservation. Contact us at support@tablebooker.be with the request details if this response occurs frequently.

Login

The "Login" API allows a customer to log in into its tablebooker account.
The base URL for this GET data source is:

https://api.tablebooker.be/v1/customers/login

Parameters

email tony@tablebooker.be Required Contains the e-mail address of the user that wants to login into its tablebooker account.
password tony123 Required The customer's tablebooker password. Never store this password locally, instead exchange it using this API for a customer_id and customer_token.

Response

The response contains a status field, which is either "OK" when the login was successfull, or "error" when something went wrong.

When the login was successfull, the API returns a customer_id and a customer_token, which can be stored locally for future use. When the status of the API call was "error", you should prompt the user for its login credentials again.

Login with Facebook

The "Login with Facebook" API allows a customer to log in into its tablebooker account using Facebook.
The base URL for this GET data source is:

https://api.tablebooker.be/v1/customers/login_with_facebook

Parameters

facebook_id 1037841836 Required Facebook ID of the user logging in.
facebook_access_token dhcj399...e47dtte Required The Facebook access token for the user's Facebook session.

Response

The response contains a status field, which is either "OK" when the login was successfull, or "error" when something went wrong.

When the login was successfull, the API returns a customer_id and a customer_token, which can be stored locally for future use. When the status of the API call was "error", you should prompt the user for its login credentials again.

Information

Retrieve information

The "info" API allows you to fetch customer information. The base URL for this GET data source is:

https://api.tablebooker.be/v1/customers/info

Parameters

customer_id 12345678 Required The customer ID that was returned by the login API.
customer_token f94e59...e405ac Required The customer token that was returned by the login API.

If the customer id or customer token is invalid, a 403 error is returned.

Update information

The same "info" API also allows you to update customer information. The base URL for this POST data source is:

https://api.tablebooker.be/v1/customers/info

Parameters

customer_id 12345678 Required The customer ID that was returned by the login API.
customer_token f94e59...e405ac Required The customer token that was returned by the login API.
customer_type personal The type of the customer, either "personal" or "business".
customer_firstname Tony The first name that has to be stored in the customer.
customer_lastname Tablebooker The last name that has to be stored in the customer.
customer_company Tablebooker CVBA The company name that has to be stored in the customer (only for "business" customers).
customer_vat BE0849393861 The VAT number that has to be stored in the customer (only for "business" customers).
customer_email tony@tablebooker.be The e-mail address that has to be stored in the customer.
customer_phone 093323323 The phone number that has to be stored in the customer.
customer_gender male The gender of the customer, either "male" or "female".
customer_birthday 1980-01-01 The birthday that has to be stored in the customer, in the format YYYY-MM-DD.

Access reviews from customers that have visited a restaurant.

Get Reviews

https://api.tablebooker.be/v1/reviews

Examples

        https://api.tablebooker.be/v1/reviews/1234567
https://api.tablebooker.be/v1/reviews?restaurant_id=1234567

By default, the reviews list is limited to pages of 20 reviews. Using the page parameter, additional reviews can be fetched. The rpp parameter can be used to change the number of reviews per page.

Parameters

Either the id or restaurant_id are required

id 012345 Required The unique id of a review. When this parameter is provided only a single review is returned.
restaurant_id 012345 Required The unique tablebooker ID of the restaurant. When this parameter is provided all public reviews of the restaurant will be returned.
page 4 The page number of the requested page. Defaults to the first page (with page number 1).
rpp 10 Results per page. Default is 20.

If you are a tablebooker partner and received an API partner key, you have access to all methods of the Restaurant API and Reservation API discussed above. Through these methods, only restaurants that enabled you as a reservation partner are available, other tablebooker restaurants are invisible.

Furthermore, you also have access to the partner-specific API methods below.

Restaurants

The partner restaurants API returns the list of restaurants that have the partner enabled. The base URL for this GET data source is:

https://api.tablebooker.be/v1/partners/restaurants

By default, the restaurant list is limited to pages of 20 restaurants. Using the page parameter, additional restaurants can be fetched. The rpp parameter can be used to change the number of restaurants per page.

Parameters

No parameters are required.

page 4 The page number of the requested page. Defaults to the first page (with page number 1).
rpp 10 Results per page. Default is 20.

Restaurant API

Restaurant information

Acquiring in depth information about a given restaurant using the v1 api was possible by sending a request to the v1/restaurants/info endpoint. The v2 api is used in a quasi identical way, with the only restriction that it is no longer possible to use a Resto restaurant id in order to gain information about a restaurant. See the /v2/restaurants/info documentation for more information.

Restaurant availablility

In the v1 api getting the availability for a restaurant was done using the /restaurants/availability endpoint. The v2 api splits this endpoint up in 2 different endpoint, one for fetching available dates given a number of guests, and one for fetching available timeslots given a number of guests and a date.

In the v2 api users will be able to add additional data to the request in order to further specify the checked date or time range. See the /v2/reservations/availabledays documentation or the /v2/reservations/availablehours documentation for more information on requesting available days or hours for a restaurant.

A restaurant has the possibility to set certain alerts on given days or timeslots that accompany a reservation on those given days and timeslots. The /reservations/alerts endpoint provides this data and can be called with a request containing a restaurant id, amount of guests, a specific timeslot and if relevant, extra reservation information such as the table or duration of the reservation. More information about this endpoint can be found at the /v2/reservations/alerts api documentation.

Restaurant menus

In the v1 api it was possible to fetch all the menus for a restaurant with a call to the /restaurants/menu endpoint with a restaurant id. In the v2 api this is split up in 2 endpoints, the /menus/restaurant/{restaurantId} endpoint provides a the list of menus with their name, corresponding id, etc.. and the /menus/menu/{menuId} endpoint provides all the details about a specific menu when given a menu id. For more information on how to use these endpoints see the /menus/restaurant/{restaurantId} and /menus/menu/{menuId} documentation.

Warning! The way items are returned in the v2 api is different from the way the v1 api returns them, menu items are no longer embedded in sections but are returned in a flat list.

Reservation API

Creating a reservation

In the v1 api it was possible to create a reservation in one go using the /reservations/new endpoint. In the v2 we introduced the concept of a reservation lock, this is a temporary reservation object that is kept by the availability service to ensure that the related timeslots are reserved for the person who is making this reservation. A valid reservation lock is then required in order to confirm a reservation and reserve the related timeslots permanently, it's important to know that a reservation lock is only valid for a set amount of time(1 minute in most cases) . In order to create a reservation lock you can make use of the /reservations/checkReservation endpoint in the V2 api. See the /v2/reservations/checkReservation documentation for more information about how to create a reservation lock.

If you want to extend the lifetime of your reservation lock because the confirmation process of a reservation might be taking longer than the reservation lock lifetime you can renew your lock on the related timeslots using the /reservations/renewLock endpoint in the v2 api. See the /v2/reservations/renewLock documentation for more information about how to extend the lifetime of a reservation lock. This will reset the lifetime of the lock and give you additional time to complete the reservation confirmation.

In order to make a reservation permanent after creating a lock you will need to POST the reservation data to the /reservations endpoint. This endpoint requires all information previously given to the /reservations/checkReservation endpoint(guests, day, timeslot, ...) as well as all the customer data that is required by the restaurant to complete the reservation process. See the /v2/reservations documentation for more information about how to confirm a reservation.

Warning! One of the more significant changes in the new reservation API is that users will be required to send a device id along with every call done to the v2/reservations api where reservation locks are involved. It is important that a reservation lock is created, renewed and confirmed with the same device id. If a device tries to create multiple reservations with the same device id, or uses a different device id for the creation and the confirmation of a reservation, the confirmation of the reservation will fail or previous locks made by this device will be overwritten.

Warning! All the API requests mentioned above now require authentication with an api key. For more information about API authentication for the v2 api, see here

Updating a reservation

The v1 api provided a way of updating the amount of guests, date and time of a reservation through the /reservations/update/{reservationId} endpoint. A similar endpoint exists in the v2 api, this time requiring additional data about the user for which the reservation will be updated. See the /v2/reservations documentation for more information about how to confirm a reservation.

Warning! The API request to update a reservation now requires authentication with an api key as well as authentication with basic auth. For more information about API authentication for the v2 api, see here

Cancelling a reservation

The v1 api provided a way of cancelling a reservation based on a reservation id. The v2 api expanded the capabilities of the cancel, you can now provide additional data to the cancel request in order to get certain payment handling behaviour. See here for more information about the cancel reservation api.

Warning! The API request to cancel a reservation now requires authentication with an api key as well as authentication with basic auth. For more information about API authentication for the v2 api, see here

Review API

Restaurant Reviews

The way the v1 api and v2 api exposes the fetching of reviews is largely the same. The v2 api provides some extra optional parameters to further specify the fetching of reviews on the /reviews/index endpoint. In the v2 api it is possible to only fetch reviews that have been updated after a certain point in time, also it is possible to differentiate between reviews that have a comment(text) added to them, or reviews that are only a rating. For more information on how to fetch reviews for a reservation using the v2 api check the /reviews/index documentation.

Restaurant Rating

The restaurant rating, that was exposed in the v1 api with the /reviews/rating is still available in the v2 api. For more information on fetching the restaurant rating with the v2 api, see the /reviews/rating documentation.