Rest API
Getting started with the REST api. There are two ways to connect with Formitable:
1. Expose your integration as an APP
For integrations with publicly available applications, we provide the
app store as a way for restaurant owners to easily expand their Formitable experience.
Your app will be publicly advertised in the app store. Your app will have access to the restaurants that
have your app installed.
Configure your app...
2. Create an integration for your restaurant
For integrations that are specific for one restaurant,
we provide api keys per user linked to a restaurant.
Contact us to obtain your api key!
Configuring your app integration
Apps have a technical configuration part and publicly facing marketing info. These settings consist of:
- Visuals (banner, feature images)
- App description
- Tags and category
- Installation instructions
- Developer information
- App settings configuration
- Webhook registrations
Currently, it is not possible to configure the app yourself, but we are happy to do this for you.
When restaurants install your app, they can configure the app. You can specify which settings can be configured using a json schema to present the settings to the restaurant user in a meaningful way.
You can retrieve these settings for a specific restaurant using this call. When a webhook is invoked, the settings will be sent along with the request so a separate call is not needed.
Contact us to create your app!
Specifying settings
Settings are specified using a json schema.
- {
- "$schema": "http://json-schema.org/draft-07/schema#",
- "description": "A representation of my app settings.",
- "properties": {
- "serverSettings": {
- "title": "Server settings",
- "type": "object",
- "description": "The connection to the server.",
- "properties": {
- "companyIdentifier": {
- "title": "Company identifier",
- "type": "string",
- "description": "The company identifier",
- }
- "userName": {
- "title": "User name",
- "type": "string",
- "description": "The username to connect with",
- }
- }
- }
- }
Above settings will render as:
Authentication
Authentication is done by providing your api key in the header of the requests.
GET https://api.formitable.com/api/v1.2/restaurants
ApiKey: thisisyourtoken
Accept: application/json
An api key is linked to an app or to a specific user of a restaurant. When the app is setup, we will send you your authentication key.
You can create an ApiKey for a user in Settings > Team.
Consuming the API
The API swagger definition (JSON) can be downloaded at: https://api.formitable.com/swagger/v1.2/swagger.json. You can use this definition to generate boilerplate code to directly consume the API. See more at: swagger.io/swagger-codegen
Api versions
Although we create backwards compatible api versions, try to upgrade to the latest api version for your integrations.
Environments
We provide you with a test restaurant to develop and test your integration.
Endpoints
-
Restaurant - Get information about the restaurant you have access to and get the reviews of restaurants.
Booking - Create, update, cancel bookings; get information; send messages to the restaurant and view the activity that occurred.
Availability - Get information about the availability and opening times of a restaurant.
Area - Get information about the areas of a restaurant.
Table - Get information about the tables of a restaurant.
Product - Get information about the products of a restaurant.
Order - Get information about the orders of a restaurant.
Review - Get information about the reviews of a restaurant.
Message - Get information about the messages of a restaurant.
Guest profile - Get information about the guest profiles.
Webhook - Get information about the webhooks of apps linked to a restaurant.
Restaurant endpoint
Booking endpoint
Availability endpoint
Area endpoint
Table endpoint
Product endpoint
Order endpoint
Review endpoint
Message endpoint
Guest profile endpoint
Webhook endpoint
Webhooks
Use webhooks to get notified of events that occur in the formitable system.
Webhook events
booking.created | Occurs when a booking has been created. |
booking.accepted | Occurs when a booking has been accepted. |
booking.changed | Occurs when a booking has been updated. |
booking.checkin | Occurs when guest checked in at the restaurant. |
booking.checkout | Occurs when a guest checked out from the restaurant. |
booking.canceled | Occurs when a booking has been canceled. |
booking.failed | Occurs when a booking failed. |
option.created | Occurs when a booking option has been created. |
option.accepted | Occurs when a booking option has been accepted. As a result of this, a booking.accepted event will also be fired. |
option.canceled | Occurs when a booking option has been canceled. |
option.expired | Occurs when a booking option has expired. |
order.ordered | Occurs when a takeaway order has been made, or a gift voucher has been purchased. |
message.sent | Occurs when a message has been sent by the customer. |
message.received | Occurs when a message has been sent by the restaurant to the customer. |
review.created | Occurs when a review has been created. |
review.request | Occurs when a review request can be sent to the customer. Typically 1 day after reservation date. |
Model
When an event occurs you registered for, your webhook will receive data about the event. This data is wrapped in the WebhookViewModel model.