API Reference

Accessing the API

The BookingSync API can be accessed over HTTPS with base URL at https://www.bookingsync.com/api/v3/.

JSON

All data is sent and received as JSON.

Regardless whether the response returns a single resource or a collection, the body is expected to be in the following format:

{
  "plural_resource_name": [
    {
      "id": "1",
      "attribute_name": "attribute_value"
    }
  ]
}

Example cURL requests

GET:

curl --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' https://www.bookingsync.com/api/v3/rentals

POST:

curl --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' --header 'Content-Type: application/vnd.api+json'
--data '{"rentals":[{"name":"Name"}]}' https://www.bookingsync.com/api/v3/rentals

PUT:

curl --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' --header 'Content-Type: application/vnd.api+json'
--request PUT --data '{"rentals":[{"name":"New Name"}]}' https://www.bookingsync.com/api/v3/rentals/RENTAL_ID

DELETE:

curl --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' --request DELETE
https://www.bookingsync.com/api/v3/rentals/RENTAL_ID

Request Options

Pagination

Large collections are paginated, meaning the response will include only a subset of resources and links to other pages.

The links are sent in the Link header, e.g.:

Link: <https://www.bookingsync.com/api/v3/accounts?page=1>; rel="first", <https://www.bookingsync.com/api/v3/accounts?page=2>; rel="next", <https://www.bookingsync.com/api/v3/accounts?page=3>; rel="last"
X-Total-Pages: 3

The possible rel values are:

Name	Description
next	Shows the URL of the immediate next page of results.
last	Shows the URL of the last page of results.
first	Shows the URL of the first page of results.
prev	Shows the URL of the immediate previous page of results.

We've built in a default limit on results, you can use the per_page parameter to change how many results per page you want to get. Large queries can hurt performance, so per_page is capped by the default limit. If you wish to retrieve more records, you should make multiple requests using the page parameter and combine the results within your application.

Limiting Fields

For retrieving collection of large resources, it is sometimes useful to limit the attributes returned by the API. For example, if we wanted to get only the id and business_name fields of the Accounts, we could specify that in the request:

GET https://www.bookingsync.com/api/v3/accounts?fields=id,business_name

Sideloading Associations

For lowering the number of requests, it is sometimes useful to sideload associations. For example, if we wanted to sideload availabilities of the Rentals, we could specify that in the request:

GET https://www.bookingsync.com/api/v3/rentals?include=availability

HTTPS

Every request to the API must use HTTPS. When the API is accessed over HTTP, a 302 redirect will be returned with the correct HTTPS url.

Rate limiting

Rate limiting is applied per OAuth application (i.e. per CLIENT_ID). All access tokens issued to the same application share a single bucket, regardless of which user authorized them. There is no separate per-user/per-token quota and no separate per-endpoint quota — the same bucket applies to every /api/v3 endpoint.

Each application has a default limit of 1000 requests per hour, with a fixed hourly window. This default can be raised on request when there is a legitimate justification.

Rate limiting information is returned on every response:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1395140400

X-RateLimit-Reset is the UNIX time at which the next limit reset happens.

When the limit is exceeded the API responds with 429 Too Many Requests, the error message API v3 rate limit exceeded., and an additional header indicating how long to wait before retrying:

Retry-After: 600

Retry-After is the number of seconds until the bucket resets. It is only returned on 429 responses.

GDPR

Refer to GDPR guide.