Skip to main content

API Guide: Create a Resource or Onsite Booking

This guide walks developers through creating a booking in Kadence using our Public API. You can use this flow to book resources (desks, rooms, pods, parking, lockers) or create general onsite bookings.

Written by Liza
Updated over 2 months ago

Prerequisites

Before getting started:

  • You must have a Kadence account

  • A Global Admin must generate an API key

Need help? Follow the API Getting Started Guide.

All datetime values must be in UTC and follow the format YYYY-MM-DDThh:mm:ss.

Pagination: All collection endpoints are paginated except bookable days. Use page and itemsPerPage (10–500) as needed.

API Documentation & Sample Code

Explore the API

Visit our full API specification: https://api.kadence.co/

You'll find:

  • Full list of available endpoints

  • Request/response examples

  • Supported query parameters

Sample Applications

View example code and starter projects on GitHub: https://github.com/wearekadence/kadence-public-api-examples

Step 1: Get an Access Token

Use your API key to obtain a bearer token via OAuth 2.0 client credentials grant.

See our Authentication section for example request and response bodies.

Step 2: Find the User

Use the /v1/public/users endpoint to search by email, first name, or last name.

GET <https://api.onkadence.co/v1/public/[email protected]>

Example response:

{ "hydra:member": [ { ... "id": "01GTBV1CT3BM8A42SEJ2J5F4EG", "email": "[email protected]", "firstName": "John", "lastName": "Smith", ... } ], "hydra:totalItems": 1 }

Store the userId from the response. This user will "own" the booking.

Delegate bookings are not currently supported via the API.

Step 3: Select the Building

Use /v1/public/buildings to find the building to book in:

GET <https://api.onkadence.co/v1/public/buildings?countryCode=GB&city=London&name=Bell%20Yard>

Example response:

{ "@context": "/v1/contexts/Building", "@id": "/v1/public/buildings", "@type": "hydra:Collection", "hydra:totalItems": 1, "hydra:member": [ { "@id": "/v1/public/buildings/01EMPPAER4FWYN1MSBW0NAZSBK", "@type": "Building", "id": "01EMPPAER4FWYN1MSBW0NAZSBK", "name": "Bell Yard Coffee - Bell Yard", "timeZone": "Europe/London", "latitude": "51.51459200", "longitude": "-0.11192900", "addressLine1": "1 Quality Court", "addressLine2": "Holborn", "city": "London", "county": "Greater London", "countryCode": "GB", "createdAt": "2023-06-29T08:40:31+00:00", "modifiedAt": "2023-07-07T10:27:00+00:00", "countryName": "United Kingdom" } ], "hydra:view": { "@id": "/v1/public/buildings?countryCode=GB&city=London&name=Bell%20Yard", "@type": "hydra:PartialCollectionView" }, "hydra:search": { "@type": "hydra:IriTemplate", "hydra:template": "/v1/public/buildings{?}", "hydra:variableRepresentation": "BasicRepresentation", "hydra:mapping": [] } }

Store the buildingId for later use.

Step 4: Check Bookable Days

Use /v1/public/bookable-days to see valid date ranges for the user and building:

GET <https://api.onkadence.co/v1/public/bookable-days?userId=01H434ZA7PCXR9AZC8NR791EZA&buildingId=01EMPPAER4FWYN1MSBW0NAZSBK>

Example response:

{ "@context": "/v1/contexts/Bookable%20Day", "@id": "/v1/public/bookable-days", "@type": "hydra:Collection", "hydra:totalItems": 2, "hydra:member": [ { "start": "2023-07-13T14:15:00+00:00", "end": "2023-07-13T16:00:00+00:00" }, { "start": "2023-07-14T08:00:00+00:00", "end": "2023-07-14T16:00:00+00:00" }, ], "hydra:view": { "@id": "/v1/public/bookable-days?userId=01H434ZA7PCXR9AZC8NR791EZA&buildingId=01EMPPAER4FWYN1MSBW0NAZSBK", "@type": "hydra:PartialCollectionView" } }

This will return the earliest and latest bookable time per day.

Bookings are constrained by the building’s booking window and opening hours.

Step 5: Book a Specific Resource (Optional)

If you're creating a resource booking, continue with the steps below. If you're only creating an onsite booking, skip to Step 6.

5.1 Retrieve Floors

GET <https://api.onkadence.co/v1/public/floors&buildingId=01EMPPAER4FWYN1MSBW0NAZSBK>

Example response:

{ "@context": "/v1/contexts/Floor", "@id": "/v1/public/floors", "@type": "hydra:Collection", "hydra:totalItems": 2, "hydra:member": [ { "@id": "/v1/public/floors/01F01JHXDZCKNP4J9N9PA878Q1", "@type": "Floor", "id": "01F01JHXDZCKNP4J9N9PA878Q1", "name": "Floor 1" }, { "@id": "/v1/public/floors/01FXSN478SSJAEEWJ26F9MHK4W", "@type": "Floor", "id": "01FXSN478SSJAEEWJ26F9MHK4W", "name": "Floor 2" }, ], "hydra:view": { "@id": "/v1/public/floors?buildingId=01EMPPAER4FWYN1MSBW0NAZSBK", "@type": "hydra:PartialCollectionView" } }

Store the floorId.

5.2 Get Bookable Resources

GET <https://api.onkadence.co/v1/public/bookable-spaces?userId=01H434ZA7Y10V1EXG6JCZBDZ5H&startDateTime=2023-07-11T09%3A00%3A00&endDateTime=2023-07-11T15%3A59%3A59&floorId=01F01JHXDZCKNP4J9N9PA878Q1>

Example response:

{ "@context": "/v1/contexts/Bookable%20Space", "@id": "/v1/public/bookable-spaces", "@type": "hydra:Collection", "hydra:totalItems": 2, "hydra:member": [ { "@id": "/v1/public/spaces/01F01HVMYGM69JGRP4FQ5DNG3M", "@type": "Space", "id": "01F01HVMYGM69JGRP4FQ5DNG3M", "name": "Desk 007", "type": "desk" }, { "@id": "/v1/public/spaces/01F01HVMYGM69JGRP4FQ5DNG3N", "@type": "Space", "id": "01F01HVMYGM69JGRP4FQ5DNG3N", "name": "Desk 008", "type": "desk" } ], "hydra:view": { "@id": "/v1/public/bookable-spaces?userId=01H434ZA7Y10V1EXG6JCZBDZ5H&startDateTime=2023-07-11T09%3A00%3A00&endDateTime=2023-07-11T15%3A59%3A59&floorId=01F01JHXDZCKNP4J9N9PA878Q1", "@type": "hydra:PartialCollectionView" } }

Choose a spaceId from the response.

5.3: Create a Resource Booking

Request: 

POST <https://api.onkadence.co/v1/public/bookings>

Request body: 

{ "userId": "01H434ZA7PCXR9AZC8NR791EZA", "spaceId": "01F01HVMYGM69JGRP4FQ5DNG3M", "startDateTime": "2023-07-20T10:00:00", "endDateTime": "2023-07-20T12:00:00" }

Example response:

{ "@context": "/v1/contexts/Booking", "@id": "/v1/public/bookings/01H57XE2NNRWM7RY6RRAEX74F7", "@type": "Booking", "id": "01H57XE2NNRWM7RY6RRAEX74F7", "userId": "/v1/public/users/01H434ZA7PCXR9AZC8NR791EZA", "space": { "@id": "/v1/public/spaces/01F01HVMYGM69JGRP4FQ5DNG3M", "@type": "Space", "id": "01F01HVMYGM69JGRP4FQ5DNG3M", "name": "Desk 007", "type": "desk", "floor": { "@id": "/v1/public/floors/01F01JHXDZCKNP4J9N9PA878Q1", "@type": "Floor", "id": "01F01JHXDZCKNP4J9N9PA878Q1", "name": "Floor 1" } }, "startDate": "2023-07-20T10:00:00+00:00", "endDate": "2023-07-20T12:00:00+00:00", "createdAt": "2023-07-13T15:20:40+00:00", "updatedAt": "2023-07-13T15:20:40+00:00", "checkedInSource": "unknown", "checkOutSource": "unknown", "permanent": false, "hasGuests": false, "guestBooking": false, "recurringBooking": false, "selfCertifySource": "unknown", "source": "publicApi", "status": "booked", "type": "desk", "building": "/v1/public/buildings/01EMPPAER4FWYN1MSBW0NAZSBK" }

Response will include full booking details.

Step 6: Make an Onsite Booking

For general onsite bookings (no specific desk or room):

6.1 (Optional) Check Onsite Passes

Only needed if your building has limited capacity.

GET <https://api.onkadence.co/v1/public/bookable-onsite-passes/?startDateTime=2023-07-20T07:00:00&endDateTime=2023-07-20T10:00:00&buildingId=01EMPPAER4FWYN1MSBW0NAZSBK>

Example response:

{ "@context": "/v1/contexts/Bookable%20Onsite%20Pass", "@id": "/v1/public/bookable-onsite-passes", "@type": "Bookable Onsite Pass", "numPassesAvailable": 0, "available": false, "startDateTime": "2023-07-20T07:00:00+00:00", "endDateTime": "2023-07-20T10:00:00+00:00", "unavailabilityReason": "openingHours" }

Look for:

  • numPassesAvailable: capacity left

  • available: true/false

Sample - some availability

Example request:

GET <https://api.onkadence.co/v1/public/bookable-onsite-passes/?startDateTime=2023-07-20T10:00:00&endDateTime=2023-07-20T12:00:00&buildingId=01EMPPAER4FWYN1MSBW0NAZSBK>

Example response:

{ "@context": "/v1/contexts/Bookable%20Onsite%20Pass", "@id": "/v1/public/bookable-onsite-passes", "@type": "Bookable Onsite Pass", "numPassesAvailable": 20, "available": true, "startDateTime": "2023-07-20T10:00:00+00:00", "endDateTime": "2023-07-20T12:00:00+00:00" }

Sample - infinite availability

Example request:

GET <https://api.onkadence.co/v1/public/bookable-onsite-passes/?startDateTime=2023-07-20T10:00:00&endDateTime=2023-07-20T12:00:00&buildingId=01EMPPAER4FWYN1MSBW0NAZSBK>

Example response:

{ "@context": "/v1/contexts/Bookable%20Onsite%20Pass", "@id": "/v1/public/bookable-onsite-passes", "@type": "Bookable Onsite Pass", "available": true, "startDateTime": "2023-07-20T10:00:00+00:00", "endDateTime": "2023-07-20T12:00:00+00:00" }

6.2 Create an Onsite Booking

Request: 

POST <https://api.onkadence.co/v1/public/bookings>

Request Body: 

{ "userId": "01H434ZA7PCXR9AZC8NR791EZA", "buildingId": "01EMPPAER4FWYN1MSBW0NAZSBK", "startDateTime": "2023-07-20T10:00:00", "endDateTime": "2023-07-20T12:00:00" }

Example response:

{ "@context": "/v1/contexts/Booking", "@id": "/v1/public/bookings/01H57XKRE5TYYTV59ZJN5A4GA0", "@type": "Booking", "id": "01H57XKRE5TYYTV59ZJN5A4GA0", "userId": "/v1/public/users/01H434ZA7PCXR9AZC8NR791EZA", "startDate": "2023-07-20T10:00:00+00:00", "endDate": "2023-07-20T12:00:00+00:00", "createdAt": "2023-07-13T15:23:46+00:00", "updatedAt": "2023-07-13T15:23:46+00:00", "checkedInSource": "unknown", "checkOutSource": "unknown", "permanent": false, "hasGuests": false, "guestBooking": false, "recurringBooking": false, "selfCertifySource": "unknown", "source": "publicApi", "status": "booked", "type": "onsite", "building": "/v1/public/buildings/01EMPPAER4FWYN1MSBW0NAZSBK" }

Kadence will respond with a booking object containing the type "onsite".

FAQs

Do I need a floor or space ID for onsite bookings?

No, only buildingId is required.

Can I create bookings for other users?

Yes, as long as you provide their userId. No delegate bookings supported.

How do I check real-time space availability?

Always use /bookable-spaces before placing space bookings.

Do onsite bookings consider capacity limits?

Yes, use /bookable-onsite-passes to check if slots are available.

Need Help?

For support, reach out to:
📩 [email protected]

Check our service status at:

📶 status.kadence.co

For more helpful articles see:
📚 Kadence Help Center

Related Articles
How to Create and Configure Resources
API Guide: Check-in/Out of Bookings
API Guide: Retrieve Bookings
API Guide: Display Space Availability on a Floorplan
Did this answer your question?