You can retrieve bookings from the /api/bookings endpoint. This SHOULD have the X-Venue-Id header set to automatically filter by venue. You can do a simple search using the search parameter:
GET /api/bookings?itemsPerPage=10&page=1&search=foo HTTP/1.1
Accept: application/ld+jsonThis will return a list of the associated bookings as you can see below. Some of the UUIDs have been shortened for ease of reading. The search parameter gives you a very quick way of finding bookings. You can search by Order/Booking Reference, Customer name, email, notes, invoice IDs, phone number and customer type. If you supply the search string, results are ordered by relevance before being ordered by the supplied order parameter.
{
"@context": "/api/contexts/Booking",
"@id": "/api/bookings",
"@type": "hydra:Collection",
"hydra:member": [
{
"@id": "/api/bookings/56bed4c2-af4...ffe9",
"@type": "Booking",
"order": {
"@id": "/api/orders/34abb5eb-29...ec2a1",
"@type": "Order",
"venue": {
"@id": "/api/venues/4813dbc0-4...dd",
"@type": "Venue",
"name": "Bankside Leisure Centre"
},
"instantBlockBooking": null,
"customerType": null
},
"facility": {
"@id": "/api/facilities/cdf3351d-87...7c6",
"@type": "Facility",
"space": {
"@id": "/api/spaces/40bd31...efec",
"@type": "Space",
"name": "7-a-side 3G Pitch",
"venue": {
"@id": "/api/venues/4813d...31dd",
"@type": "Venue",
"name": "Bankside Leisure Centre"
}
},
"name": "Squash Court A"
},
"eventStart": "2021-07-10T10:00:00",
"eventEnd": "2021-07-10T11:00:00",
"state": "completed",
"blockingEvents": [],
"notes": null,
"blockBooking": false,
"allowCustomerCancellation": true,
"pendingApprovals": [],
"attendees": [],
"customerAttended": "not_updated",
"id": "56bed4c2-af40-4b17-bd1a-afd9a93bffe9",
"customer": {
"@id": "/api/customers/4609...341c",
"@type": "Customer",
"organisationName": null,
"email": "nathan@example.com",
"phone": "07894561233",
"fullName": "Nathan Foo"
},
"number": 1,
"price": 5000,
"vatAmount": 833,
"vatPercentage": 20,
"priceExVat": 4167,
"originalPrice": 5000,
"originalVatAmount": 833,
"originalVatPercentage": 20,
"originalPriceExVat": 4167,
"createdAt": "2021-06-10T15:49:13+00:00",
"updatedAt": "2022-08-11T17:27:54+00:00",
"createdBy": "admin@playfinder.com",
"updatedBy": null,
"customerNotes": "Fooooo",
"inBasket": false,
"expiryDate": null,
"paymentState": "unpaid",
"discount": 0,
"totalPrice": 5000,
"feeAmount": 0,
"totalVatAmount": 833,
"overallVatPercentage": "20.00%",
"discountPercentage": 0,
"type": "booking",
"enabledLockPassword": null,
"enabledLockRecord": null,
"customerCancellationAllowsRefund": false,
"customerCancellationEnabled": true,
"customerCancellationInTime": false,
"bookingPendingApproval": null,
"duration": "1 hour",
"refundable": false,
"reference": "BNK1203-1",
"currentInvoice": null,
"paidOnline": true,
"nicePaymentState": "Unpaid",
"paid": 0,
"humanReadablePaymentState": "Unpaid",
"totalPriceExVat": 4167
},
...
],
"hydra:totalItems": 599,
"hydra:view": {
"@id": "/api/bookings?order%5Breference%5D=desc\u0026itemsPerPage=10\u0026search=foo\u0026page=1",
"@type": "hydra:PartialCollectionView",
"hydra:first": "/api/bookings?order%5Breference%5D=desc\u0026itemsPerPage=10\u0026search=foo\u0026page=1",
"hydra:last": "/api/bookings?order%5Breference%5D=desc\u0026itemsPerPage=10\u0026search=foo\u0026page=60",
"hydra:next": "/api/bookings?order%5Breference%5D=desc\u0026itemsPerPage=10\u0026search=foo\u0026page=2"
},
"hydra:search": {
"@type": "hydra:IriTemplate",
"hydra:template": "/api/bookings{?search,order[reference],order[type],order[status],order[facility],order[eventStart],order[customer],order[price]}",
"hydra:variableRepresentation": "BasicRepresentation",
"hydra:mapping": [
{
"@type": "IriTemplateMapping",
"variable": "search",
"property": "search",
"required": false
},
{
"@type": "IriTemplateMapping",
"variable": "order[reference]",
"property": "reference",
"required": false
},
{
"@type": "IriTemplateMapping",
"variable": "order[type]",
"property": "type",
"required": false
},
{
"@type": "IriTemplateMapping",
"variable": "order[status]",
"property": "status",
"required": false
},
{
"@type": "IriTemplateMapping",
"variable": "order[facility]",
"property": "facility",
"required": false
},
{
"@type": "IriTemplateMapping",
"variable": "order[eventStart]",
"property": "eventStart",
"required": false
},
{
"@type": "IriTemplateMapping",
"variable": "order[customer]",
"property": "customer",
"required": false
},
{
"@type": "IriTemplateMapping",
"variable": "order[price]",
"property": "price",
"required": false
}
]
}
}
Using the hydra:totalItems and hydra:view properties you can easily create pagination from this.
Note that you SHOULD NOT use this API for reporting, as it is not guaranteed n later pages that results are not repeated. If you need to pull out lists of bookings for reporting, please contact us or use the CSV export link on the bookings table. Reports from there are guaranteed to be correct.
You can order the results by supplying order[<name>]=<direction> in the path. E.g. ?order[eventStart]=desc.
If you need to do more advanced filtering we have tools for that as well. For example you can use this query:
GET /api/bookings?order[reference]=desc&itemsPerPage=10&page=1&price=IS_GREATER_THAN|1000&facility=IS|d8ac6815-6949-4b20-9440-248b1221a887,e9a333ef-0dc6-4e1a-a538-c6fcf96b3b40,07b7d070-4e78-4b70-bd93-f8a3aa13fa6e,1d562b9f-b25c-4c25-a582-0949490c25a0&type=IS|booking&date[type]=IS_BETWEEN&date[from]=2024-11-14&date[to]=2024-11-30 HTTP/1.1
Accept: application/ld+jsonLet’s break that down a bit to be clearer. Advanced searches are a Key, a search Type, then the pipe (|) character, then the required value(s).
type=IS|bookingThis searches for bookings where the type property is booking.
price=IS_GREATER_THAN|1000Returns bookings where the price is greater than 1000 pence (£10.00). All pricing in Bookteq is done via the smallest price currency unit (e.g. pence, cents). Other options are IS, IS_LESS_THAN , IS_NOT, IS_GREATER_OR_EQUAL_TO and IS_LESS_OR_EQUAL_TO.
facility=IS|d8ac6815-6949-4b20-9440-248b1221a887,e9a333ef-0dc6-4e1a-a538-c6fcf96b3b40,07b7d070-4e78-4b70-bd93-f8a3aa13fa6e,1d562b9f-b25c-4c25-a582-0949490c25a0This matches facilities with any of the supplied IDs, separated by commas. You can also supply IS_NOT to filter out facilities.
date[type]=IS_BETWEEN&date[from]=2024-11-14&date[to]=2024-11-30Date types have three properties, if you’re using IS_BETWEEN, to supply the range of dates. These can include times as well, e.g. date[from]=2024-11-14T11:00:00. Timezones are optional here and are ignored if supplied, it will simply use the time at the venue.
If you’re using one of IS, IS_NOT, IS_BEFORE, IS_AFTER, IS_ON_OR_BEFORE or IS_ON_OR_AFTER, you don’t need to supply the date[to] parameter (and it is ignored).
You can also use CONTAINS to do a fuzzy search on that property. The full list of properties is:
| Name | Type |
|---|---|
| customer | Text |
| reference | Text |
| attendee | Text |
| organisation | Text |
| type | Options |
| state | Options |
| pending_approval_state | Options |
| space | UUIDs |
| facility | UUIDs |
| payment_state | Options |
| venue | UUIDs |
| customer_id | UUIDs |
| customer_email |
Text |
| customer_type | Text |
| price | Number |
| date | Date |
| time | Date |
