API for Pronestor Planner

This guide provides a description of how to use the API for Pronestor Planner.
Support and development/usage of the API are not included in the service level agreement.

The Pronestor Planner API will ensure access to the Pronestor Planner engine and thereby data for integrations with 3rd. party software, most often a finance software that will allow you to ease the process of billing the right cost centers for catering and/or booking fees for resources. When resources such as catering or meeting rooms have a price attached in Planner, it is often necessary to export the financial data to be used as the basis for invoicing your customers whether they are internal or external.

The API is a tool you can use to integrate with other software. Pronestor makes the API available but we do not create the integrations themselves. Integrations are usually made by a developer, so check with your IT department whether you have someone who has the ability or skills to help with the API integration. 

Table of content

• How to find your API
• Documentation of commands
• Example of use
• Code example
• How to create a Financial Data Export from Pronestor Planner using the API
  • Basic concepts
  • Calling the API endpoint
  • The data returned
  • Example requests

How to find your API

Every Pronestor Planner cloud site has an API interface. The way you access the API depends on your site name. If your site is https://customername.pronestor.com/ then you access the API by typing /api.mvc after your site name e.g. https://customername.pronestor.com/api.mvc

Please note that the site might take a while to load the very first time you access it

When you access it, there is an explanation of the code commands to assist a developer creating an integration.

IMPORTANT
Each request must include a cookie with authentication credentials - this can be retrieved using the "Authenticate" method.

Documentation of commands

An overview of methods and types available in the API can be viewed by opening your site API link in a browser.

Example of use

The most common use of Pronestor API is to create an export directly to your finance system - which is described in greater detail in the chapter How to create a Financial Data Export from Pronestor Planner using the API

We have several customers who use the API with room bookings, door locking integration e.t.c.

The steps below can be used to find the room bookings for the current day, including information on who has booked the rooms during the day:

PLEASE NOTE: Remember to change the customer name in the URLs described below with your personal reference to your site.

•  Authenticate – required since the other methods require authentication to be performed for the session
• FindBookingsByResourceType in a given period (using type=1, which will be the booking of rooms)
• The result from the method above will return an array of bookings.  (https://customername.pronestor.com/api.mvc#ApiBooking)
• Loop of that array to find the relevant bookings
• Each booking will contain a reference to a meeting (https://customername.pronestor.com/api.mvc#ApiMeeting)
• Each meeting will contain a reference to the owner of the meeting and thus the user/owner of the booked room (https://customername.pronestor.com/api.mvc#ApiUser)

Code example

An example of a C# proxy class is attached at the bottom of this guide. 

How to create a Financial Data Export from Pronestor Planner using the API

Basic concepts

The API endpoint is designed so it is easy to pick up where you left and only get the data that is new to you.

It is also easy to go back and get historical data if you need to fetch data once more.

The most important thing to know about the data returned from this API endpoint is that it is immutable. No matter how often or how long between calls, the data is always going to be the same. The bookings returned are always locked, which means that they cannot be altered.

All data is included so all filters must be applied after the client has received the data.

Calling the API endpoint

The endpoint used to get this data is the FindLockedBookings method.

The endpoint takes two query string parameters.

• startLockTime (mandatory)

The parameter is a datetime in UTC formatted like this: 2021-12-01 00:00:00Z

This parameter tells the server to return all bookings locked after this time. The time is exclusive, so it returns all booking after but not on this time.

• endLockTime (optional)

The parameter is a datetime in UTC formatted like this: 2021-12-31 23:59:59Z

This parameter tells the server to return all bookings locked before this time. The time is inclusive, so it returns all booking before or on this time.

The reason startLockTime is mandatory and exclusive and endLockTime is optional and inclusive is that this makes it possible to always just get the bookings you haven’t already fetched. If you just include the latest LockedTime you have fetched as the startLockTime in your next request without an endLockTime, then you will always get all bookings that have been locked since you last fetched locked bookings without the risk of fetching the same bookings twice.

A few rules you must follow

• The startLockTime must be earlier than the endLockTime.
• endLockTime must not be in the future. Omit this parameter to get all bookings locked up to now.
• You cannot request more than 6 months of data in one request.

The data returned

The endpoint returns all bookings locked within the time interval specified by the parameters supplied in the request.

The most up to date description of all the properties of a booking can found on your API site. This is located on your solution like this:

https://<customer-tenant-name>.pronestor.com/api.mvc#ApiBooking

Example requests

Get all bookings locked after November 3rd 2021 at 10.51 UTC.

GET https://mytenant.pronestor.com/Api.mvc/v1/FindLockedBookings?startLockTime=2021-11-03 10:51:00Z

Get all bookings locked in October 2021.

GET https://mytenant.pronestor.com/Api.mvc/v1/FindLockedBookings?startLockTime=2021-09-30 23:59:59Z&endLockTime=2021-10-31 23:59:59Z

Remember that all times must be UTC, so this is corrected when specifying your date interval.