Time Off API

NoahFace enables workers to view their time off balances and requests, and to request time off. To support this, you simply implement our View Time Off and Request Time Off APIs (REST Web Hooks), and configure NoahFace to call them.

View Time Off API

The View Time Off API uses the same endpoint as a the User Synchronization API, with additional query parameters appended.

Query Paramaters

In detail, requests to view time off balances and requests will have the following additional query paramaters:

• type. A type of "leave" indicates that time off information should be returned (instead of a list of users).
• syncguid. The unique identifier of the user.
• from. The start of the date range of time off requests to be returned, in the form: YYYY-MM-DD.
• to. The end of the date range of time off requests to be returned, in the form: YYYY-MM-DD.

‍

So, the logic within your implementation of this endpoint should be as follows:

if (the query parameter type is present) {
    if (type=shift) {
        return shift information for user
    } else if (type=leave) {
        return time off information for user
    } else if (type=addleave) {
        add a time off request for user
    } else ...
else {
    return user information for all users
} 

‍

Returned Data

On success you should return a status code of 200 and JSON data with two top level elements called balances and requests.

The balances element should contain a list of time off balances as at the from date, with each balance containing the following elements:

• name. The name of the balance (eg: Annual Leave, Sick Leave, etc).
• units. The units - either "Days" or "Hours".
• count. The balance eg: 25.

The requests element should contain a list of time off requests in the specified date range, with each request containing the following elements:

• id. The unique identifier of the time off request.
• name. The name of the associated balance (eg: Annual Leave, Sick Leave, etc).
• fromDate. The start of the time off request in the form YYYY-MM-DD.
• toDate. The end of the time off request in the form YYYY-MM-DD.
• count. The number of days in the time off request.
• status. The status of the time off request (eg: "Submitted", "Approved").
• notes. Any notes associated with the time off request.

‍

For example:

{
   "balances": [
     {
         "name": "Annual Leave", 
         "units": "Days", 
         "count": 37
     },
     {
         "name": "Sick Leave", 
         "units": "Days", 
         "count": 4
     }
   ],
   "requests": [
     {
         "id": "25",
         "name": "Annual Leave",
         "fromDate": "2025-01-25",
         "toDate": "2025-01-26",
         "count": 2,
         "notes": ""
     }
   ]
}

‍

On failure you should return a status code other than 200 and any additional error details as follows:

{
    “errorCode”: “X12345”,
    “errorMsg”: “Leave balance not available”
}

‍

Request Time Off API

The Request Time Off API uses the same endpoint as a the User Synchronization API, with additional query parameters appended.

Query Paramaters

In detail, requests to view time off balances and requests will have the following additional query paramaters:

• type. A type of "leave" indicates that time off information should be returned (instead of a list of users).
• syncguid. The unique identifier of the user.
• from. The start of the date range for the time off request, in the form: YYYY-MM-DD.
• to. The end of the date range for the time off request, in the form: YYYY-MM-DD.
• count. The number of days in the time off request.
• notes. Any notes associated with the time off request.

‍

So, the logic within your implementation of this endpoint should be as follows:

if (the query parameter type is present) {
    if (type=shift) {
        return shift information for user
    } else if (type=leave) {
        return time off information for user
    } else if (type=addleave) {
        add a time off request for user
    } else ...
else {
    return user information for all users
} 

‍

Returned Data

On success you should return a status code of 200.

On failure you should return a status code other than 200 and any additional error details as follows:

{
    “errorCode”: “X12345”,
    “errorMsg”: “Leave balance insufficient”
}

‍

Configuration

To learn how to configure NoahFace to allow workers to view their time off balances and requests, and to request time off, see: Self Service.

‍