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

Idempotency

Retrying a request that creates or modifies data is risky when you never received the response. The first attempt may have been applied before the connection dropped, so a blind retry can duplicate the record.

To make a retry safe, send an Idempotency-Key header:

Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

The header is honoured on every request method, so it covers POST, PATCH, PUT and DELETE on any endpoint. It is only meaningful on requests that change data.

The key must be a valid UUID. Generate it with a standard UUID library and validate it on your side before sending, as other formats are not accepted.

The first request presenting a given key is processed normally. If it responds with a status between 200 and 399, the full response — status, headers and body — is stored for up to one week and returned verbatim to any later request that presents the same key and is the same request. The retry is never processed again, so no duplicate record is created.

A request counts as the same request when its method, path and body are all identical to the original. Present a key alongside anything else and the API responds 409 Conflict without executing it:

{
  "errors": [
    {
      "code": "idempotency_key_mismatch",
      "details": "Idempotency-Key has already been used for a different request."
    }
  ]
}

Responses outside the 200–399 range are not stored, 409 included. Retrying after a 4xx or a 5xx therefore re-runs the request, which is what you want when the original attempt never reached us.

Rules to follow:

• Generate a new UUID per logical operation, at the first attempt, and persist it alongside whatever tracks the retry.
• Reuse that same key for every retry of that operation, and send the identical request each time. Generating a fresh key on retry defeats the mechanism; changing the body under the same key gets you a 409.
• Use a new key whenever you genuinely want the operation to happen again. Within the retention window, the old key keeps returning the original response.

Three things worth knowing:

• Always use randomly generated UUIDs rather than values derived from your own identifiers.
• The response is stored once the first request completes, so two requests sent concurrently with the same key are both processed. This protects sequential retries, not parallel duplicates.
• A replayed response is served from the stored copy without re-processing the request, so its X-RateLimit-* headers carry the values captured at the time of the original call.

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.