The Bookeo API lets developers extend the capabilities of Bookeo, and integrate it with external services and business processes.
The API and this documentation is designed for experienced developers only. It assumes experience in developing web applications using modern technologies such as HTTP, JSON, web services, and so on.
If you are not a web developer, you do not need to read this documentation.
If you’re looking to get a custom application developed for you, and you’re not a developer, we recommend hiring a developer from one of the many marketplaces dedicated to freelance jobs, such as UpWork.
For any comments and feedback please email api@bookeo.com.
The Bookeo API is based on REST principles, using JSON as the content type.
Full reference documentation of the API is available at https://www.bookeo.com/apiref/
The API specification is also available in OpenAPI format, to help with automation tools (code generators, documentation generators, etc.). The specification file is available at https://www.bookeo.com/apiref/openapi.json.
The API is expected to change over time, with more operations added and various tweaks. Make sure to subscribe to our API updates blog to stay updated with changes.
The API base URL is https://api.bookeo.com/v2 , for the current version (v2).
The address api.bookeo.com resolves to multiple IP addresses spread out across multiple geographical regions (multihoming). This ensures high availability and fault tolerance.
When developing applications that invoke the API, it is important to ensure that if a connection problem arises to the first IP address returned by the DNS service, other addresses are attempted as well. This can often be handled transparently by many modern HTTP client libraries, but it’s worth checking it is the case in your specific circumstances.
It is also recommended to ensure that DNS caching on your server is limited (1 hour or less. We recommend using the recommended TTL, which is 10 minutes), so that your client code has always access to an up-to-date list of available IPs.
Developers wishing to use the API must follow these two steps:
By registering an application you are issued with a “secret key“. This key must be kept secret, as it will be used to validate that any API invocation made in the name of your application is effectively made by your application.
Once a user authorizes (installs) your application, you will also be provided with an “api key” that allows your application to access the user’s account data, with a given set of permissions.
Both the “secret key” and the “api key” must be included in any API invocation.
Users can uninstall an application at any time (from the account>Applications page). Once an application is uninstalled, the corresponding api key is no longer valid. Re-installing the same application again will generate a new api key, different from the old one.
When your application asks the user for authorization, it must also specify what permissions it needs in order to operate. For example it may require the permission to create new bookings, or to read existing bookings, etc.
The permissions granted by the user are tied to the api key. When Bookeo receives an API invocation, it checks the api key provided to verify that the permissions required to carry out the operation are granted to the key.
It is possible to change permissions requested by your application at any time, by asking the user to go through the same authorization process as for new installations. If the user grants the new permissions, a new api key will be provided, and the old one will no longer be valid.
