This page will help you get started with Hostfully. You'll be up and running in a jiffy!
Welcome to the Hostfully API Version 3
This API is always under development. If you need help with implementing the API for your system, please contact our professional services contact us and we'll help you with your project.
If you notice the docs are out of date or are unclear, please don't be shy about clicking the "Suggest Edits" link! We're working to keep these docs up to date, however sometimes we get behind – and we'd love your help.
Prerequisites
Access to the Hostfully API is granted to users with Premium accounts, or to organizations being part of the Hostfully Preferred Partners group. If you need to upgrade your account to Premium level, you can do so from the page Agency Settings > Account Upgrade tab. If you want to apply to be a preferred partner, you can do so by sending an email to [email protected].
Authentication
There are three forms of authentication in the Hostfully V3 API.
- Basic Auth, which is required for Partners to be able to for example exchange Authorization Code for the tokens in the OAuth flow.
- OAuth 2.0 Authorization Code Flow, which is how Hostfully Customers authorize Partners to access their data.
- For Premium accounts, authentication, similar to V1 and V2 API versions, will continue to be served by API keys, which can be obtained from your Agency Settings page and must be included in every API request as an HTTP header called X-HOSTFULLY-APIKEY.
For more details, please see the Authentication tab.
Sandbox vs Production
API development will always have to start on our sandbox. Once you feel that you got things under control, just send us a note and we'll enable your access to production. Testing the APIs on the dev portal here will only work with a sandbox api key.
Rate Limit
The Hostfully API allows 10,000 calls within a 1 hour window per calling client.
HTTP Headers and Response Codes
Use the HTTP headers in order to understand where the application is at for a given rate limit, on the method that was just utilized. The HTTP headers to monitor are the following:
x-ratelimit-limit: the rate limit ceiling for that given endpoint
x-ratelimit-remaining: the number of requests left for the 15 minute window
When hitting the rate limit, please pause your code for 1 hour and retry the call.
API returns standard error codes:
400 - Bad request (parameters or payload issue)
401 - Unauthorized
403 - Forbidden
404 - Resource not found
405 - Method not allowed
409 - Conflict (usually an issue with the data, logical conflict)
429 - Rate limit
Result Pagination
If pagination is provided on the given endpoint it will be used by default. Hostfully has adopted cursor-based pagination in V3 of the API. We've done so to ensure that our API's internal optimization will not break the contract regardless of the under-the-hood implementation.
Blacklisting
If a client application abuses the rate limits, it will be blacklisted. Blacklisted client apps are unable to get a response from the Hostfully API. If you or your application has been blacklisted and you think there has been a mistake, you can email us at [email protected] to request assistance.
Support, Feedback and CVD
Using the API as a Hostfully Partner
Partner Listing on the Integration Zone
In order to get started with an integration, a partner needs to first get their organization
listed on the Hostfully Integration Zone page. In order to first get your organization listed on
the Integration Zone, please email [email protected].
Once listed on our Sandbox server, your organization will show on the page
https://sandbox.hostfully.com/app/#/agency-settings
Here’s an example of an integration listed on that page:
In V3 an integration build into Hostfully API, needs to be started from the integration end. We will provide redirect button on our integrations page that will take the user to a URL provided by the partner.
Important note about API key usage
Note that if you are a partner building an integration and you will be provided with an account on our Sandbox server, you will see an API key provided on the Agency Settings page. Do not use this API key to connect to the API. This can skew your testing of your integration. Instead, please go through the proper OAuth flow using provided Sandbox account.
Using the API with a Hostfully Premium account
If you signed up as a Premium account, you will find your production API key on your Agency Settings
page ((https://platform.hostfully.com/app/#/agency-settings).
Testing on Sandbox
The Hostfully Developer Center provides a testing sandbox, allowing developers to initially test
the API calls without writing any code.
- On the API documentation interface, select an API and click on the Try It button
- Enter your API key and click Enter - this will send the API call. If the API requires some
data, just enter them in in the fields in the form.
