Sync employee leave

Overview

The Time Off API exposes a single endpoint that allows customers to post time off dates for their users. The endpoint also allows customers to post notifications of cancelled time off.

The time off endpoint accepts an array of time off event objects. Each object specifies:

The time off event type (scheduled or cancelled)
The time off start and end dates
The user email OR the Calven uid for the user
For scheduled time off an optional time off type can be provided

When the document contains scheduled time off, the user’s plan for the relevant day(s) will be changed to a - away as long as the date is not in the past. Transactions for scheduled time off in the past are ignored.

When the document contains canceled time off, the user’s plan will be modified according to the cancelled time off date:

If the date is in the past, no action is taken
If the date is within the booking horizon, the user’s plan is changed according to their week plan
If the date is beyond the booking horizon, the user’s plan is deleted. It will be recreated by the horizon booking engine at a later date.

In the case where a user has made a different plan to the week plan and subsequently has approved time off that is cancelled for that day, the day plan will still be reset according to their week plan. ie. Their original plan variation for that day is lost.

Note that the API does not support partial time off days.

API

Authentication

Connections to the integration are authenticated using a bearer token obtained from the https://api.calven.com/v1/auth endpoint.

API endpoint

Time off data is POSTed to the https://api.calven.com/v1/timeoff endpoint.

Input documents

The time off event endpoint accepts an array of timeOffEvent.

The input data takes the following form:

{
  "timeOffEvents": [
    {
      "email": "Mary.Smith@emaildomain.com",
      "eventType": "scheduled",
      "startDate":"2022-08-08",
      "endDate":"2022-08-08"
    },
    {
      "email": "John.Jones@emaildomain.com",
      "eventType": "cancelled",
      "startDate":"2022-08-08",
      "endDate":"2022-08-08"
    },
    {
      "uid": "ABC123HGbghdhdI",
      "eventType": "scheduled",
      "startDate":"2023-01-01",
      "endDate":"2023-01-01",
      "timeOffType":"holiday"
    },
    {
      "uid": "ABC123HGbghdhdI",
      "eventType": "scheduled",
      "startDate":"2023-01-02",
      "endDate":"2023-01-23",
    }
    ]
}

Field	Type	Description
`timeOffEvents`	Array	The array of time off events
`email`	String	The user’s email address. This will be used to search for the user in both the Calven `email` and `username` fields.
`eventId`	String	An identifier for this time off event. It must be unique within the set of events POSTed in a given call to the `timeoff` endpoint (see below) and is ideally globally unique (e.g. a UUID).
`uid`	String	The user’s Calven UID. One of `email` or `uid` MUST be provided. If both are provided, `uid` will be used to identify the user.
`eventType`	String	Time off event type, either `scheduled` or `cancelled`
`startDate`	String	Start of time off period, date in ISO 8601 format, inclusive.
`endDate`	String	End of time off period, date in ISO 8601 format, inclusive
`timeOffType`	String	Optional time off type - One of `leave`, `holiday` or `sick`. If not specified, `leave` is used.

Responses

The server will respond as follows:

Resonse code	Meaning	Body
200	Input was processed successfully	Success response document (see below)
400	Bad request - Input document was not valid. e.g. approval status other than scheduled or cancelled, dates were not valid, time off type is invalid	Error Response document (see below)
401	Authentication data was not provided	Error Response document (see below)
403	Authentication data was invalid	Error Response document (see below)

Success response document

{
  "timestamp": "2023-05-15T10:23:45Z",
  "results": [
      {
        "eventId":"71FA8F0D-DBB6-42AC-8618-1865DD476769"
        "resultCode": 0,
        "message": "OK"
      },
      {
        "eventId":"4A480792-F730-458D-BAC8-65FFE1EAC666"
        "resultCode": 1,
        "message": "user not found"
      }
  ]
}

Property	Type	Description
`timestamp`	String	Timestamp when the response was generated.
`results`	Array	The results for the time off events that were submitted
`eventId`	String	The event identifier to which this result corresponds.
`resultCode`	number	The result code for this occupancy event: 0 = OK 1 = User not found
`message`	String	Additional text associated with the `resultCode`

Error response document

{
  "message": "Invalid time off type 'party'"
}

Property	Type	Description
`message`	String	Additional text associated with the error