Calven
  1. Warehouse - Basic Auth
Calven
  • Overview
  • Key Access Levels
  • Basic Authentication Overview
  • HMAC Authentication Overview
  • SDKs
  • Calven Data Models
  • HMAC 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 with BASIC auth
      POST
    • Submit presence events
      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 Overview
    • Users
      GET
    • Locations
      GET
    • Desks
      GET
    • Bookings & Attendance
      GET
    • Presence Details
      GET
    • User Actions Log
      GET
  • Warehouse - HMAC Auth
    • Warehouse Overview
    • Users
      GET
    • Locations
      GET
    • Desks
      GET
    • Bookings & Attendance
      GET
    • Presence
      GET
    • User Actions Log
      GET
  1. Warehouse - Basic Auth

Warehouse Overview

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/basic/
GET /v1/analytics/locations/basic
GET /v1/analytics/desks/basic
GET /v1/analytics/change-log/user/basic
GET /v1/analytics/user-booking-attendance/basic
GET /v1/analytics/presence/basic

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 Basic 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.

Getting Started#

Generally it is best to start testing with cURL to verify access and then move to more sophisticated tools to interact with the APIs. To begin, request an API key with Basic Auth enabled from Calven support via support@calven.com.
Copy the below script into your terminal, replacing apiKeyId and apiSecret with your values. It is best to pipe the output into a file rather than the terminal, especially when extracting large datasets.
The call will return the location information from Calven and store it in locations.json. Open that file and you will see information similar to the below:
[
    {
        "locationId": "28992537-ed23-41bc-a322-635445445644",
        "locationName": "Headquarters Office",
        "address": "San Francisco, California, USA",
        "status": "active"
    },
    {
        "locationId": "e9347c3d-9ee5-4aaa-8a75-e8132f150bac",
        "locationName": "Melbourne",
        "address": "500 South Street, Melbourne, Australia",
        "status": "active"
    }
]
Once you have done the above, you can make subsequent calls to the other APIs utilizing the same pattern, or switch over to your tool of choice.

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 2025-04-03 13:54:25
Previous
Submit access credentials
Next
Users
Built with