Skip to main content

​
Response formats

The API supports JSON, CSV, and PDF response formats. Specify your preferred format using the Accept header.

​
Expanding responses

Some endpoints support expanding nested objects in the response using the expand query parameter. You can expand multiple objects with a comma-separated list, and use dot notation for nested objects. For example, when retrieving an order, you can expand the contact, line_items, and line_items.item:
You can find examples of fully expanded responses in the “Show a <RESOURCE_NAME>” endpoints.
For each expanded resource, ensure the access token has read scope for that resource. For example, when expanding the site on subscription, the public.site:read scope is required.

​
Pagination

List endpoints are paginated. The defaults are:
  • 50 items per page by default
  • 100 items per page maximum (set via the limit query parameter)
  • Use the page query parameter to navigate through pages
Pagination data (count, last, limit, next, page, pages, and prev) is returned in the response’s meta/pagination field. Some resources include a _links field containing HATEOAS-style links. These provide URLs to related actions or pages, such as signing a contract on the storefront or starting a new booking for a unit type.

​
Structure

Each link is keyed by a namespaced relation name and contains an href (relative path) and a human-readable title:

​
CURIEs

Link relation names use a CURIE (Compact URI) prefix to indicate which application the link points to: The meta object includes a curies array that maps each prefix to a URL template. To resolve a full URL, replace {rel} in the CURIE href with the link’s href:
For example, a link sf:new_order with href /sites/belfast/5x5-unit/order/contact-details?unit_type_slug=5x5-unit resolves to:
Links can be conditional — they only appear when the action is available. For example:
  • A contract only has sf:show_contract when it is not voided or deleted
  • A unit type only has sf:new_order when its status is bookable
When no links are available, the _links field is an empty object {}.