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.

Liza avatar
Written by Liza
Updated yesterday

🛠️ 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?