List endpoints
All endpoints that serve lists of resources are paginated and allow filtering and sorting the lists.
Pagination
All list endpoints are paginated, meaning they do not return all results at once but instead return pages with a limited number of results.
Users can navigate through paginated lists using page and limit query string parameters. page determines which page should be returned and limit determines how many results a single page can have. For example, if you wanted to fetch the third page of a list of Persons with 25 results per page you would call the following URL:
Both of these parameters are optional. You could hit the same endpoint without any parameters and you would get the first page of the Persons list with 10 results. In other words, the default for the page parameter is 1 and the default for the limit parameter is 10.
In order to support pagination, these endpoints also return additional information on top of the data that was actually requested. Namely, all list endpoint responses are objects with three root properties:
datalinksmeta
data
dataThis property holds an array of resources that represent the currrent page of the results the user requested by calling the endpoint. In other words, this array will contain a list of Persons, Invoices, Bookings or another resource, depending of which endpoint was called.
The content of this property, as well as its structure, changes depending on the endpoint that was called.
links
linksThis property is an object that contains links to other pages of the same paginated list. It contains the same structure with only slightly variable content for each endpoint. It contains the following four properties (each holding a URL):
first- URL to the first page of the paginated listlast- URL to the last page of the paginated listprev- URL to the previous page in the list. This isnullwhen the first page of the list is loadednext- URL to the next page in the list. This isnullwhen the last page of the list is loaded
meta
metaThis property is also an object, it contains additional information about the number of results and pages available in the list being loaded. Its structure is the same in all endpoints it is available in. It contains the following seven properties:
current_page- number of the current page being returnedlast_page- number of the last pagefrom- the position in the list of all resource that the first resource in the returned page takesto- the position in the list of all resources that the last resource in the returned page takesper_page- the number of resources returned in a single pagetotal- the total number of resources in the whole listpath- the URL to the endpoint without any parameters
Filtering
All list endpoints can be filtered in order to retrieve scoped results. Filtering only affects pagination in terms of which results are returned, otherwise the whole functioning and structure of pagination remain the same regardless if filters are enabled or disabled.
Note that each combination of filters and sorting results in a different paginated list. Therefore changing filters and/or sorting may (and most likely will) give you different ordering of resources in paginated lists, and therefore different results on each page.
Filtering can be performed by using query string parameters. Each endpoint has a different set of parameters it accepts, this is documented on dedicated pages for each endpoint. For example, the Guests list endpoint can be filtered by arrival date (this is one of the many parameters that endpoint can be filtered by) using the arrives_at parameter:
Even though each endpoint has a different set of filters, there are predefined types of filters and their input expectations.
Equality filters
This is the simplest type of filter. It simply accepts a single value and ensures only results with a predefined field that matches the specified value are returned. This type of filter is frequently used for flags and unique values. For example, if you know an email of a Person but not its ID and you need to find you can do so by calling the Persons list endpoint and filtering it by email:
Equality or range filters
Some equality filters support a syntax for filtering both by a single value or by ranges. With these filters it is possible to specify either a single value in order to find resources with predefined properties that match the value exactly, or define a range and find resources with predefined properties that fall in the specified range. This filter is applicable only for numerical fields.
Filtering by a single value works the same as the equality filter. If you wanted to filter Bookings by their exact price you could do so in the following manner:
If, however, you wanted to fetch only Bookings cheaper than 500 you would hit:
Note the , (comma) symbol before the number 500 in the final_price_incl_tax parameter. That symbol specifies that only Bookings with final_price_incl_tax <= 500 should be included in the response.
Fetching Bookings more expensive than 500 would require appending the , (comma) to the amount:
Finally, it is also possible to define a range in which the filtered result properties would fall in. As such, fetching Bookings that are more expensive than 500 but cheaper than 1000 can be achieved with:
This could be translated to the following formula: final_price_incl_tax >= 500 && final_price_incl_tax <= 1000. Note that these filters are inclusive, i.e. they include the amounts specified in the query parameter.
One-of filters
These filters accept a comma-separated list of values and ensure lists only contain results that have a predefined field that matches one of the values if the filter. If you wanted to fetch Bookings that belong to several bookers you could do so by calling the following URL:
The two values in the booker parameter are Person ID's. This request would return only bookings made by either one of the two specified bookers.
Date(time) filters
Date and datetime filters offer a lot of flexibility and power. It's possible to filter by a single date/datetime, filter by a range or filter resources that have any date/datetime set or have null in their date/datetime fields.
For example, fetching all Bookings that begin on a certain date can be achieved like this:
Fetching Bookings that begin before December 2023:
Akin to the Equality or range filter, the , (comma) symbol before the date specifies the filter should only include dates before the one specified in the query parameter.
Fetching Bookings that begin after December 20th 2023:
In this case the , (comma) is placed after the date, signaling the filter to include dates after the one specified in the query parameter.
Fetching Bookings that Begin in December 2023:
Here we see the , (comma) placed between the two dates, thus defining a range of dates the filter should include.
In case of nullable date/datetime fields, for instance the arrives_at field on the Guest resource, it is possible to filter only resources that have the property set to any value.
Conversly, it is also possible to filter only the resources that contain null in place of the designated field.
Custom filters
A lot of endpoints support custom filters with custom input expectations. These filters are documented on the dedicated pages for the endpoints as query string parameters.
Sorting
Sorting can also be applied using query string parameters, however it is much simpler than filtering. In order to sort a paginated list response you should simply add a sort_by={field},{direction} query parameter. The {field} represents the field you want to sort the list by and the {direction} represents the direction you want it sorted in. Each endpoint has its own set of fields that can be used for sorting, this is documented on dedicated pages for each endpoint, and the direction can be either asc or desc.
For example, if you wanted to sort the bookings list by start date ascending (older first) you would call:
And if you wanted the same sorting just in the opposite direction (descending, younger first):
Last updated