This article covers:
What is an API?
An API (Application Programming Interface) enables two technologies to communicate. Different HTTP methods define what action you want to take with the data. For example:
GET: Retrieves existing information
POST: Creates something new
PATCH: Modifies existing information
DELETE: Removes existing information
Version 2.0.0
In January 2020, we launched our v2 API. Currently, the API only allows access to event information. However, we plan to include booking data in the future.
✨ You can create an API access token from any Bookwhen account.
API Overview
Our current API allows you to GET certain information from your Bookwhen account. The following data can be accessed:
Events (singular or list)
Locations
Attachments
Tickets
Passes
This means you can display the above public information from your scheduling page on your website, but it’s important to note that this is view-only data.
What the API doesn’t do
The API does not allow for bookings to be made directly. Instead, you'll need to create a button that redirects customers to your Bookwhen site for booking.
Additionally, the API cannot pull this information into your CRM, as it does not support reporting metrics.
Data refresh frequency
You decide how often the API pulls data. Your development team can specify how frequently the information is updated or refreshed by adding additional code to the API.
💡 If you delete a schedule page from your account, it will break the API. After making this change, you’ll need to re-authenticate the API to continue using it.
Difference between API and iframe
The API
Read-only: The API only allows you to GET public data, meaning you cannot make changes.
Doesn’t list attendance: Customer information or attendance data is not accessible via the API.
Event listing: The API only returns events from today and into the future by default.
The iframe
Embed your schedule: The iframe allows you to display your Bookwhen schedule on a separate website.
Browser permissions: You’ll need to grant permission from the browser to use the iframe on your site.
Reflects your Bookwhen schedule: The iframe shows an exact copy of your Bookwhen schedule, with no additional edits.
No cookies: Unlike other integrations, the iframe does not use cookies.
Version 1.0.0 (deprecated)
Our v1 API is now deprecated. If you require a v1 API access key for your account, please email support@bookwhen.com with your account link.
Setting up the API integration
To enable the Bookwhen API:
Select Settings, then Integrations from the left-hand menu on your account.
Select View integration next to Bookwhen API:
Then Create a new API access permission:
Enter the Name of permission, review or amend the permission options depending on the desired outcome, and select Create:
Creating the token set
Once you have set up the API, you can create the access token set. To do this:
Select View permission set:
Select Add a new token set under Token sets:
Enter the Name of the token set, review or amend the permission options depending on the desired outcome, and select Create:
Retrieving the token code
After you have set up the API and created the access token, you can retrieve the token code. To do this:
Select View under Token sets:
You can find your unique access Token code for this permission set under Tokens:
Using the access token
Once you have set up the API permission set and access token, you can use the token code for your API requests.
Example curl call to list accounts:
curl "https://api.bookwhen.com/v2/events" -u 'xxxxxxxxxxxxxxxxxxxxxxxxxxxx:'
💡 The "x...x" part in the code snippet needs to be replaced with the token code from your account.
Customising the API code
You can customise the API call results using various filter parameters. For more details, please refer to our API documentation and the alternative layout.
By default, results are paginated with 20 per page. For more than 20 results, use page[offset]=XX to access additional pages.
Please note: The API documentation covers setup and filter parameters. If you run into issues, debugging the code may be necessary. Our support team can’t assist with debugging, but external resources may help.
Disabling the integration
To disable the API integration:
Select Settings, then Integrations from the left-hand menu on your account.
Select View integration next to Bookwhen API on your Integrations page:
Select View permission set:
Scroll down and select Delete API access permission set in the bottom right-hand corner:
💬 Need extra help?
For the quickest response, contact us via live chat on our homepage or your account. Buddy, our trusty chatbot, will assist first and pass you to a support team member if needed.
Prefer email? Send us an email instead.
Thank you! 🕺