Who is this page for?

You are a third party integrator with a system containing data that represents occupancies for a space. A basic example would be a PMS provider that works with reservations in a hotel and you want to sync your reservations into the betterspace platform.

What you need before creating occupancies

  • You need to subscribe to the occupancy API. Please refer to the Authentication Page for more details.

  • You will need API access to a location, more precisely a client Id and client secret (to create an access token) for this location including the company Id and location Id. Please refer to the Authentication Page for more details.

Step by step guide

  1. Get a list of all spaces

  2. Get all occupancies

  3. Create an occupancy for a space

  4. Edit an occupancy

  5. Delete an occupancy from a space

Get a list of all spaces

An occupancy needs a space which it is attached to. As both systems contain spaces (or rooms), you need to find the correct mapping between the spaces. Most of the time the spaces have a clear name which can be used for the mapping. You should also only care for the space names and ignore the subspaces in this case. For example:

GET https://api.betterspace.cloud/occupancy/api/v1/companies/{companyId}/locations/{locationId}/spaces
Request - with example data
GET https://api.betterspace.cloud/occupancy/api/v1/companies/480c7da7-5911-441b-8aa4-3f3333dad75c/locations/e440d5a3-9b33-44c9-b46b-16c70d7d1ef8/spaces
Request - with placeholder
curl Example - make sure to replace {companyId} and {locationId}
Example Response

Get all occupancies

Please make sure a use a fitting date range to request all occupancies. Longer ranges will result in bigger response delays.

GET https://api.betterspace.cloud/occupancy/api/v1/companies/{companyId}/locations/{locationId}/occupancies?startDate={startDate}&endDate={endDate}
Request - with placeholder
GET https://api.betterspace.cloud/occupancy/api/v1/companies/480c7da7-5911-441b-8aa4-3f3333dad75c/locations/e440d5a3-9b33-44c9-b46b-16c70d7d1ef8/occupancies?startDate=2025-02-27T22:00:00Z&endDate=2025-03-05T22:00:00Z
Request - with example data
curl example - make sure to replace {companyId}, {locationId}, {startDate} and {endDate}
Example Response

Create an occupancy for a space

When creating an occupancy, the occupancyNumber can be used as another reference to map the occupancy to your system. If you integrate a hotel PMS, it would make sense to use the reservation number here.

POST https://bs360-prod-apim.azure-api.net/occupancy/api/v1/companies/{companyId}/locations/{locationId}/occupancies
Request - with placeholder
POST https://bs360-prod-apim.azure-api.net/occupancy/api/v1/companies/480c7da7-5911-441b-8aa4-3f3333dad75c/locations/e440d5a3-9b33-44c9-b46b-16c70d7d1ef8/occupancies
Request - with example data
curl example - make sure to replace {companyId} and {locationId}
Example Payload
Example Response

The system will prevent you from creating overlapping occupancies. Please make sure to remove the overlapping occupancies before creating a new one. The system will notify you with a 400 Bad Request:

{"ErrorMessage":"Occupancy overlaps existing manual occupancy","ErrorCode":"OVERLAPPING_MANUAL_OCCUPANCY","Status":"ERROR"}

Edit an occupancy

Editing an occupancy is just you modifying the data you already get from us and send it back. You can use the same body as during the create request.

PUT https://bs360-prod-apim.azure-api.net/occupancy/api/v1/companies/{companyId}/locations/{locationId}/occupancies/{occupancyId}
Request - with placeholder
PUT https://bs360-prod-apim.azure-api.net/occupancy/api/v1/companies/480c7da7-5911-441b-8aa4-3f3333dad75c/locations/e440d5a3-9b33-44c9-b46b-16c70d7d1ef8/occupancies/a07eb7ac-857a-480e-99a9-8f90a0b0ec27
Request - with example data
curl Example - make sure to replace {companyId} and {locationId}
Example Playload
Example Response

Delete an occupancy from a space

There are no special cases here, it just deletes an occupancy. You will receive a 204 No Content on success, otherwise 404 Not Found on error.

DELETE https://bs360-prod-apim.azure-api.net/occupancy/api/v1/companies/{companyId}/locations/{locationId}/occupancies/{occupancyId}
Request - with placeholder
DELETE https://bs360-prod-apim.azure-api.net/occupancy/api/v1/companies/480c7da7-5911-441b-8aa4-3f3333dad75c/locations/e440d5a3-9b33-44c9-b46b-16c70d7d1ef8/occupancies/a07eb7ac-857a-480e-99a9-8f90a0b0ec27
Request - with placeholder
curl Example - make sure to replace {companyId} and {locationId}