1. Warehouse - HMAC Auth
Calven Developer Docs
  • Overview
  • Access Control
  • Basic Authentication
  • HMAC Authentication
  • SDKs
  • Calven Data Models
  • Changelog
  • Authentication
    • Generate a token with an API key and HMAC
      POST
    • Generate a token with an API key and client secret
      POST
  • Presence
    • Presence Overview
    • Submit presence events
      POST
    • Submit presence events (Basic auth)
      POST
  • Occupancy
    • Occupancy Overview
    • Submit occupancy events
      POST
  • Time Off
    • Submit time off updates
      POST
  • Access Credentials
    • Submit access credentials
      POST
  • Warehouse - Basic Auth
    • Warehouse API (Basic Auth)
    • Users (Basic auth)
    • Groups (Basic auth)
    • Locations (Basic auth)
    • Desks (Basic auth)
    • Bookings & Attendance (Basic auth)
    • Presence (Basic auth)
    • User Actions Log (Basic auth)
    • Events (Basic auth)
  • Warehouse - HMAC Auth
    • Warehouse API (HMAC Auth)
    • Users
      GET
    • Groups
      GET
    • Locations
      GET
    • Desks
      GET
    • Bookings & Attendance
      GET
    • Presence
      GET
    • User Actions Log
      GET
    • Events
      GET
  • Hierarchy Information
    • Org Hierarchy Information Overview
    • Submit group hierarchy relationships
    • Submit group hierarchy relationships (Basic auth)
  • User Attributes
    • User Attributes Overview
    • Write directory user attributes
    • Write directory user attributes (Basic auth)
  • Visitor Management
    • Submit visitor arrival events
    • Submit visitor arrival events (Basic auth)
  • Parking
    • Retrieve parking bookings
    • Retrieve parking bookings (Basic auth)
  • Schemas
    • Schemas
    • DWEventsResponseDto
  1. Warehouse - HMAC Auth

Warehouse API (HMAC Auth)

Calven provides analytics in the Backoffice administration tool that can be accessed at https://backoffice.calven.com/analytics/.
The warehouse APIs are used to retrieve that Calven data to bring the information into your own data warehouse.

Overview#

The warehouse APIs consist of the following endpoints:
GET /v1/analytics/users
GET /v1/analytics/groups
GET /v1/analytics/locations
GET /v1/analytics/desks
GET /v1/analytics/change-log/user
GET /v1/analytics/user-booking-attendance
GET /v1/analytics/presence
GET /v1/analytics/events

Authentication#

See the Oveview page for details on API keys and details on the authentication types.
All warehouse APIs are available using either HMAC or Basic Authentication. This section outlines the HMAC Authentication endpoints.

Rate limiting#

Calven's external APIs do not currently implement rate limiting in order to facilitate adoption by our customers.
However, Calven reserves the right to block access to users that are improperly using the APIs and requesting very large amounts of data from the warehouse.

Data size limits#

The warehouse APIs will limit the number of days that can be queried in one request to limit the size of the data returned. Generally, 30 days is the longest query range for the endpoints. The events endpoint is the exception: it returns one row per event, so it accepts a range of up to 550 days.

Getting Started#

We recommend you get started testing with the Basic Auth endpoints first, see that page for details.

Best practices#

When structuring an integration with Calven via the warehouse APIs, it is best to have up-to-date values for users, locations and desks and then make calls to the subsequent APIs utilizing those values.
Because the historical datasets can be large, in particular on the Bookings & Attendance and Presence Details APIs, incremental loading of the data should be utilized.

Use cases#

Backfilling of historical data into a warehouse#

To backfill historical data into your data warehouse:
1.
Query users, locations and desks endpoints to get up-to-date information on those entities and store the results in your warehouse tables.
2.
Iterate through each location, querying the Bookings & Attendance endpoint to retrieve the details.
3.
The Bookings & Attendance endpoint can retrieve at most 30 days of data. Query the endpoint for 30-day ranges, retrieving the data until you have backfilled all of your data, storing this data in a table.
4.
Join the users table with the Bookings & Attendance table in your warehouse using the userId values.
5.
The Presence endpoint contains more details about individual presence events, which are not typically required for historical analysis, but it can be retrieved in 30-day ranges as well if needed and stored in a separate table.

Incremental loading of historical data#

Note: is it recommended to update your warehouse once a week. The data can be loaded daily if needed, but the data is only refreshed nightly so it is not needed to do more often than that
1.
Query users, locations and desks endpoints to get up-to-date information on those entities and store the results in your warehouse tables. This data will slowly change as users are added and removed, and offices are updated. This should be refreshed.
2.
Query the Bookings & Attendance endpoint for the date range since the last update, storing this data in a table.
3.
Join the users table with the Bookings & Attendance table in your warehouse using the userId values.

Querying of future data#

The Bookings & Attendance endpoint can be used to query future booking information. For example, this is useful if you are sharing the booking information on your company intranet.
Note: This is a data-intensive query so care should be taken for the frequency of the query. It is recommended that this is not queried more than every 30 minutes.
1.
Query users to get up-to-date details on the users. This should be done periodically to refresh the user information, typically once a day to once per week.
2.
Query the Bookings & Attendance endpoint for the future date range (typically 1-2 weeks) every 30-60 minutes.

Investigating user's booking details#

To determine the exact flow of a user's booking actions, you can use the User changelog endpoint. This will contain a line for every user action that has been taken related to bookings.
1.
Query users to get up-to-date details on the users. Find the userId of the user in question. Alternatively you can get the userId by looking at the URL of the user's profile on the web app.
2.
Utilize the userId and the date range under investigation to submit a request to the User chanlog endpoint.

Troubleshooting presence#

The Bookings & Attendance endpoint contains details on user attendance including presence, but it does not show each individual presence event. To get a deep level of presence detail, use the Presence endpoint. This will show each presence event, and what source the presence event was reported by.
Modified at 2026-09-01 04:40:13
Previous
Events (Basic auth)
Next
Users
Built with