The Presence events API allows the submission of presence events for specific users to Calven.

A presence event is an indication that a specific user is in a specific location.

Examples of this are:

An access control system detecting that a user has badged into the office, which marks the user as being present in the office

An enhanced-location WiFi system detecting that a user is in a specific zone

A desk reservation panel detecting that a user has sat down at a specific desk

This data can be streamed in real time as the events happen, or it can be bulk loaded later.

Presence Event Example

Multiple presence events can be sent in each API call to facilitate faster processing when a large number of events are being loaded.

{
   "sourceId": "My System",
   "presenceEvents": [
       {
            "timestamp": "2023-05-15T10:22:45Z",
            "sourceUserId": "1341"
            "userEmail": "SomeUser@somedomain.com",
            "locationId":"D0FA9F18-6E7F-449A-8C50-30276AA9B63F",
            "locationType": "location",
            "eventId": "42FA8F0D-DBB6-42AC-8618-1865DD476769"
       },
       {
            "timestamp": "2023-05-15T10:23:45Z",
            "sourceUserId": "1342"
            "userId": "2F6F955E-C1BB-483D-BAE8-56D15233F11B",
            "locationId":"D0FA9F18-6E7F-449A-8C50-30276AA9B63F",
            "locationType": "location",
            "eventId": "71FA8F0D-DBB6-42AC-8618-1865DD476769"
       }
  ] 
}

Specific field descriptions

sourceId is an identifier for your presence source. It is only sent once for each API call. It can be any text string and is not validated. It is useful in troubleshooting presence events when looking at the audit log of presence.

timestamp Each presence event has a timestamp that indicates when the presence was detected (this can be in the past).

eventId is a unique ID value for the presence event. If errors are detected when sending the presence event, the problematic eventId will be returned in the response.

locationId specifies the point in the Calven location hierarchy where the presence is being reported.

locationType specifies the type of location represeneted by locationId - Valid values are level, location, place, space or zone.

userId and userEmail - the user can be identified by their internal Calven userId value userId or by their email/login userEmail. Only one should be used as a time. Note that the userEmail value is case sensitve and must match the value that has been provisioned into Calven.

Programmatically retrieving details

User information can be retrieved via the /v1/users endpoint

locationId can be retieved via the /v1/locations endpoint

If more specific location information is being used, levelId, zoneId and deskId can be retrieved via the /v1/desks endpoint

Handling errors

There are 2 primary types of errors that can occur when sending data via the presence endpoint.

Formatting errors - If the structure of the API call is not formatted correctly, such as missing fields from some events, no data will be loaded from the API call and a 4xx response will be returned.

Data errors - Specific presence events may be rejected by the Calven API if the event cannot be processed correctly. For example, a userName for one of the events may not link to a user in Calven. In these cases, the specific event will be rejected and reported in the response, but all other events will be loaded.

If presence events need to be re-loaded into Calven, it is fine for duplicate events to be sent. These events will be stored in Calven but since presence for a user is calculated as 'being seen once in the day', multiple presence events for users do not have a negative effect.

Presence Overview

Presence Event Example#

Specific field descriptions#

Programmatically retrieving details#

Handling errors#

Presence Event Example

Specific field descriptions

Programmatically retrieving details

Handling errors