Are you partnering with a restaurant and would you like to get their data, create new reservations, modify existing reservations, send messages or manage their webhooks?
With the Formitable REST API you can do all of that and much more. Follow the 7 steps in this article to set up an API connection between your software and a Formitable restaurant.
Do you think the integration you want to build will be of interest to more Formitable customers? Please contact our Partnerships team at firstname.lastname@example.org.
1. Get the 'API key' and 'restaurantUid' from a restaurant
The first step to connect with restaurants that use Formitable is to ask their permission and get their API key. A restaurant is in charge of its own data and decides itself if they want to share their data with third party software.
Make sure you have discussed your integration with the restaurant(s) you want to connect with. If they agree to work together, ask them to share their API key with you:
First, ask the restaurant owner to navigate to their Team page in Formitable.
Select one of the admin accounts on the Team page.
Scroll down to the Advanced section in the account.
Turn on 'API user'.
Press 'Get API key'.
Ask the restaurant owner to share the API key that is shown with you.
Check out this GIF to see the steps described above:
After you received the API key, you will need to request the
restaurauntUid of the restaurant. This is the unique identifier of a restaurant that is required to make calls on the endpoints. For the
restaurantUid, ask a restaurant owner to go to Settings > Widgets > scroll down to Your Keys > Restaurant Key.
Please note that, due to caching, it takes 5 minutes before an API user becomes active.
2. Discuss permissions with the restaurant
On the same page where you get the API key from, the restaurant owner can give you permissions to read parts of your data, modify bookings, etc. By clicking 'Manage permissions' under the 'Get API key' button, they can decide which permissions to share.
Possible permissions are:
Check availability and opening times of your restaurant
View your bookings
Create new bookings and modify existing bookings
View information about your restaurant
View sold tickets, gift vouchers and takeaway orders
View information about your tickets, gift vouchers and takeaway items
View reviews about your restaurant
View the areas of your restaurant
View the tables of your restaurant
View installed webhooks (a way for Formitable to send data to the app)
Add new webhooks and modify existing webhooks
Send messages to guests
View messages from guests
Modify your restaurant's settings
View guest profiles of your restaurant
Add/modify guest profiles of your restaurant
3. Read the Formitable REST API documentation
Next, read the Formitable REST API documentation carefully. This will tell you how to connect to a restaurant, which endpoints are available and which webhooks you can set up.
This documentation is also written for setting up a permanent integration in our App Store. If you have more restaurants requesting this integration, please reach out to email@example.com.
Please note: Our partnerships team will evaluate if the integration will be added to the Formitable App Store.
4. Test your connection with a restaurant
You can start out with testing your connection by getting the information of a restaurant via the Get Restaurant call in the Restaurant Endpoint:
See Get Restaurant in the Restaurant Endpoint for the expected response.
5. Set up the connection using the desired endpoints and/or webhooks
You are now ready to start building your integration. If you need any technical assistance, need more information about what endpoints to use or need some advice on how to set up your integration, you can reach us at firstname.lastname@example.org.
In order to understand how Formitable works, it is advised to read these articles about setting up tickets and availability. That way, you have more knowledge about how a restaurant is structured in Formitable:
6. Make sure you handle errors
If you are working with the Booking endpoint to create bookings for a restaurant, please make sure you build in a way to handle errors. For example, when a restaurant is full, you get a 400 error stating so. Please make sure you or the restaurant is aware that the integration tried to make a booking but failed, in order to avoid angry guests at the door of the restaurant.
You can find the possible Response Messages for each call in the API documentation.
7. Test your integration
Testing your integration means that you are testing with real data of a restaurant. And you are creating real bookings in the restaurant. Discuss with a restaurant how to do this, so you don't interfere with their day-to-day business.
For example, you could create bookings far into the future and cancel them after testing. Or ask a restaurant to create an extra, fake area for you to test in.
If none of this is possible, please contact us at email@example.com to check the possibilities of setting up a demo restaurant for you to test with.