Booking Form API
The Booking API allows FormSmarts members to offer a limited number of resources for booking (e.g. eighty tickets for an event) through an online booking form. The booking form is automatically disabled once the event is fully booked or the booking period has ended. As explained in this documents, the Booking API allows the form owner to access information about bookings and events online. Feel free to try this booking form demo, quickly make a simple booking form, learn how bookings work, and contact us if you have any questions.
Events & Other Bookable Resources
A bookable resource is called an event. An event can be anything with a name, date and a limited number of bookable slots. A bookable resource is typically an event associated with a number of tickets that can be booked via an online form, but it could also be a product with the corresponding inventory.
How to Create an Event
To create an event, log in to the API Console and submit a POST request to https://formsmarts.com/api/v1/events, providing a value for each of the required parameters listed below.
| API Endpoint | ||
|---|---|---|
| https://formsmarts.com/api/v1/events | ||
| HTTP Method | ||
| POST | ||
| Parameter (in request body) | Description | Notes |
| label | Name or label of the event or bookable resource | Required |
| slots | Total number of slots available for booking, e.g. tickets, seats | Required |
| date | Date and time of the event in ISO 8601 format, e.g. 2014-12-30T15:00:00 | Required |
| timezone | Timezone of the event as listed here, e.g. America/Los_Angeles | Required |
| booking_starts | Date and time on which bookings start, in the timezone specified under timezone. | Optional |
| booking_ends | Date and time on which bookings end, in the timezone specified under timezone. | Optional |
Listing Events
To retrieve the details of events or bookable resources, submit a GET request. All parameters are optional.
| API Endpoint | ||
|---|---|---|
| https://formsmarts.com/api/v1/events | ||
| HTTP Method | ||
| GET | ||
| Parameter (in query string) | Description | Notes |
| fields | A comma-separated list of attributes to return in the API response. Event attributes are: event_id, slots, usedslots, label, status, date, timezone, booking_starts, booking_ends | Optional |
| limit | Maximum number of results to return in the API response. | Optional |
| offset | If provided, results are returned in the API response starting at the element specified in offset. | Optional |
To get the details of a particular event, append the event's ID to the API endpoint URL and submit a GET request:
| API Endpoint | ||
|---|---|---|
https://formsmarts.com/api/v1/events/Event_ID | ||
| HTTP Method | ||
| GET |
Adding Event Data to a Booking Form
Basic information about active events is publicly available so it may be integrated to a booking form.
| API Endpoint | ||
|---|---|---|
| https://formsmarts.com/api/v1/events/public | ||
| HTTP Method | ||
| GET | ||
| Parameter (in query string) | Description | Notes |
| session_id | The session ID of the form the booking is associated with. | Required |
Canceling an Event
To cancel an event (a.k.a. bookable resource), append the event's ID to the API endpoint and submit a DELETE request:
| API Endpoint | ||
|---|---|---|
https://formsmarts.com/api/v1/events/Event_ID | ||
| HTTP Method | ||
| DELETE |
An event may only be deleted if it doesn't have bookings. Cancel the associated bookings first if needed.
How to Make a Booking Form
You can easily make a simple booking form via the form builder, but if you would like to adjust booking options, you'll need to use the Booking API instead.
To create an online booking form via the Booking API:- Create a form, adding at least one booking field like on this demo. A booking field is a simple text box that should allow Letters + Numbers.
- Create an event as outlined in the previous section
- Integrate the form with the Booking API as explained next.
Associate Events with a Form
To associate an event (or any bookable resource) with a form, sign in to the API Console and submit a PUT request to the API endpoint below, replacing Form_ID with the ID of the form. All parameters but booking_fields are optional.
| API Endpoint | ||
|---|---|---|
https://formsmarts.com/api/v1/forms/Form_ID/booking | ||
| HTTP Method | ||
| PUT | ||
| Parameter (in request body) | Description | Notes |
| booking_fields | A comma-separated list of the IDs of the booking fields you've added to the form. You can find out the ID of an input field with the API. | Required |
| event_label_fields | A comma-separated list of the IDs of the event label fields, if any. | Optional |
| event_ids | A comma-separated list of Event IDs. If not specified, a list of all active events is retrieved when the form is loaded. | Optional |
| max_slots | The maximum number of slots (i.e. tickets or seats) that can be booked in a booking field. Between 1 and 5, defaults to 1. | Optional |
| interactive | Force form users to interact with the booking user-interface, even when booking one slot for a single event. Defaults to no. | Optional |
Review a Form's Booking Integration
To list the current integration parameters of a form, submit a GET request.
| API Endpoint | ||
|---|---|---|
https://formsmarts.com/api/v1/forms/Form_ID/booking | ||
| HTTP Method | ||
| GET |
Remove a Form's Booking Integration
To cancel a form's booking integration, submit a DELETE request.
| API Endpoint | ||
|---|---|---|
https://formsmarts.com/api/v1/forms/Form_ID/booking | ||
| HTTP Method | ||
| DELETE |
Booking
Booking an Event
To book a slot for event, send a POST request. A slot will be pre-booked. A booking form must be submitted within 30 minutes to confirm the booking.
| API Endpoint | ||
|---|---|---|
| https://formsmarts.com/api/v1/bookings | ||
| HTTP Method | ||
| POST | ||
| Parameter (in request body) | Description | Notes |
| event_id | The ID of the event. | Required |
| session_id | The session ID of the form the booking is associated with. | Required |
| allow_multiple | Allow multiple bookings to be associated with a form entry. 'yes' or 'no' ('no' by default). | Optional |
Note: List events as described above to find out the ID of an event.
Canceling a Booking
To cancel a booking, append the booking's ID to the URL and send a DELETE request:
| API Endpoint | ||
|---|---|---|
https://formsmarts.com/api/v1/bookings/Booking_ID | ||
| HTTP Method | ||
| DELETE | ||
| Parameter (in query string) | Description | Notes |
| session_id | A booking can also be canceled by the form user that made the booking. To cancel a booking as a form user, pass the session ID of the form associated with the booking in the session_id parameter. | Optional |
Listing the Details of a Booking
To retrieve the details of a booking, append the booking's ID to the URL and submit a GET request:
| API Endpoint | ||
|---|---|---|
https://formsmarts.com/api/v1/bookings/Booking_ID | ||
| HTTP Method | ||
| GET | ||
| Parameter (in query string) | Description | Notes |
| fields | A comma-separated list of attributes to return in the API response. Options are: fs_ref_num, event_id, slot, status, booking_id, booking_date | Optional |
Listing All Bookings for an Event
To list all bookings for an event, insert the event's ID in the URL and submit a GET request:
| API Endpoint | ||
|---|---|---|
https://formsmarts.com/api/v1/events/Event_ID/bookings | ||
| HTTP Method | ||
| GET | ||
| Parameter (in query string) | Description | Notes |
| fields | A comma-separated list of attributes to return in the API response. Options are: fs_ref_num, event_id, slot, status, booking_id, booking_date, event_date | Optional |
| limit | Maximum number of results to return in the API response. | Optional |
| offset | If provided, results are returned in the API response starting at the element specified in offset. | Optional |