edays Developer API

Getting Started
Welcome
Available operations
Authentication
Users
Fetch Users
Fetch Groups
Create User
Mark Leaver
Absences
Fetch Absences
Fetch Absence Types
Create Absence
Rota
Fetch Rota for User
Is User at Work
Fetch Public Holidays

Getting started

Welcome

The edays API provides programmatic access to read and write data to the edays system. You may find it useful for getting data imported to another system or performing operations triggered by some other application. You are viewing the documentation for version 1 of our APIs. If you would like to use our new API information on version 2 can be found here. The following operations are available on the edays API:

Available Operations

Fetch a filtered list of users
Create a new user
Mark a user as leaver
Fetch a filtered list of absences
Create a new absence
Find out if a user is at work on a given day
Fetch a list of public holidays within a date range

Authentication

edays API services require you to authenticate using a valid API key. All our APIs run under the context of the user the API key is created with, so you may be able to use an existing user account with appropriate permissions, or you may wish to create an edays user account specifically for your API request.

API Key

To create an API key you must be logged in to your edays system and then access the following URL:


    https://YOUR-SYSTEM.e-days.co.uk/wapi/userdata/generatePublicApiKey

Your API Key will be displayed as follows:


        <string xmlns="...">Z&r3/k4</string>

Please note that it is not possible to recover an API Key so please store it carefully. Also note that each time you generate an API key it will replace any key that had earlier been created. Your edays user privileges will determine what operations you can do and what data you can query.

To authenticate requests, include your "uid" (the login for your API user) and "pak" (API key) in JSON format inside the POST body.


        {
            "uid": "APIUser",
            "pak": "Z&r3/k4",
            ...
        }

Users API

The Users API will allow you to fetch an array of users, create new users in the edays system, or perform operations over users. All text data returned by the User API will be in JSON format.

Fetch Users

Resource URL:


    https://YOUR-SYSTEM.e-days.co.uk/api/users

HTTP Method: POST

Parameters:

page optional	0 based index for the page of users to return. Default is 0.
pageSize optional	Number of users per page. Default is 100 Max. 1000
id optional	id of user to return. Must be a GUID
login optional	login of user to return. Exact match
name optional	searches user full names can be just part of a name
payrollNumber optional	payroll number of user to return. Exact match

RETURNS: Page containing a filtered array of users.

Example Request:


    POST

    https://YOUR-SYSTEM.e-days.co.uk/api/users?name=john

Example Response:


    {
      "PageIndex": 0,
      "PageSize": 100,
      "TotalPages": 1,
      "TotalUsers": 2,
      "Users": [
        {
          "EdaysId": "52b68ded-b2b0-4a5f-b86e-11e4f225260e",
          "Login": "johnWayne",
          "SSOUsername": "johnWayne",
          "PayrollNumber": "123456",
          "FirstName": "John",
          "LastName": "Wayne",
          "Email": "john.wayne@email.co.uk",
          "Roles": [
            "Standard Administrator"
          ],
          "RotaPatterns": [
            "Mon/Tue/Wed/Thur/Fri"
          ],
          "Groups": [
            "United Kingdom",
            "Sales"
          ],
          "TimeUnit": "Days",
          "FTE": 1,
          "HoursPerDay": 7.5,
          "CurrentEntitlement": 12,
          "NextYearEntitlement": 25,
          "AuthoriserIds": [
             "4ad7aa6a-c957-4ef0-b07f-c90896f7cea6"
          ],
          "AlternativeAuthoriserIds": [],
          "EmploymentStartDate": "2015-06-19T00:00:00",
          "DateOfBirth": "1995-05-15T00:00:00",
          "LeftDate": null,
          "IsLeaver": false,
          "AccountStatus": "Active"
        },
        {
          "EdaysId": "e49f4f50-7e88-e511-93f4-72228baf5f68",
          "Login": "mJohnson",
          "SSOUsername": "mJohnson",
          "PayrollNumber": "456789",
          "FirstName": "Mario",
          "LastName": "Johnson",
          "Email": "m.johnson@email.co.uk",
          "Roles": [
            "Standard User",
            "Standard Authoriser",
            "Standard Administrator"
          ],
          "RotaPatterns": [
            "Mon-Thurs part time"
          ],
          "Groups": [
            "United States",
            "IT"
          ],
          "TimeUnit": "Hours",
          "FTE": 1,
          "HoursPerDay": 8,
          "CurrentEntitlement": 22,
          "NextYearEntitlement": 26,
          "AuthoriserIds": [
            "52b68ded-b2b0-4a5f-b86e-11e4f225260e"
          ],
          "AlternativeAuthoriserIds": [
            "edb0b6dd-dbc1-4dbe-8862-bd2dfe55550d"
          ],
          "EmploymentStartDate": "2004-05-15T00:00:00",
          "DateOfBirth": "1983-06-18T00:00:00",
          "LeftDate": null,
          "IsLeaver": false,
          "AccountStatus": "Active"
        }
      ]
    }

Fetch Groups

Resource URL:


    https://YOUR-SYSTEM.e-days.co.uk/api/users/groups

HTTP Method: POST

Parameters: NONE

RETURNS: Array of user groups with Id and Name

Example Request:


    POST

    https://YOUR-SYSTEM.e-days.co.uk/api/groups

Example Response:


    [
      {
        "Id": "521c3811-38cc-e111-833b-00155d000918",
        "Name": "England"
      },
      {
        "Id": "b14dc5b0-8197-e511-93f4-72228baf5f68",
        "Name": "Finland"
      },
      {
        "Id": "f8fd2538-9ca5-e511-93f7-72228baf5f68",
        "Name": "Germany"
      }
    ]

Create User

Resource URL:


    https://YOUR-SYSTEM.e-days.co.uk/api/users

HTTP Method: POST

Parameters:

login required	user's login for the edays system
firstName required	user's first name
lastName required	user's last name
email required	user's e-mail
role required	user's security group. Has to be one of the following: User, Authoriser or Administrator
payrollNumber optional	user's payroll number.
startDate optional	user's employment start date Must be in the following format: yyyy-MM-dd e.g. 2015-08-25

RETURNS: ID of the created user

Example Request:


    POST

    https://YOUR-SYSTEM.e-days.co.uk/api/users?login=jwayne
                                              &firstName=John
                                              &lastName=Wayne
                                              &email=john.wayne@email.com
                                              &role=User
                                              &startDate=2015-12-24

Example Response:


    "c74cc4d1-de02-41e3-9ceb-8d11dba8ee32"

MARK Leaver

Resource URL:


    https://YOUR-SYSTEM.e-days.co.uk/api/users/markLeaver

HTTP Method: POST

Parameters:

id
required

Id of user to mark as leaver
Must be a GUID

RETURNS: Object with leaver and total leaver licenses count

Example Request:


    POST

    https://YOUR-SYSTEM.e-days.co.uk/api/users/markLeaver?id=c74cc4d1-de02-41e3-9ceb-8d11dba8ee32

Example Response:


      {
        "LeaversCount": 15,
        "TotalLeaverLicenses": 80
      }

Absences API

The Absences API will allow you to fetch filtered absences for a user within a time range. It will also allow you to create different types of absences for a particular user.

Fetch Absences

Resource URL:


    https://YOUR-SYSTEM.e-days.co.uk/api/absence

HTTP Method: POST

Parameters:

start required	Start date Must be in the following format: yyyy-MM-dd e.g. 2015-08-25
end required	End date Must be in the following format: yyyy-MM-dd e.g. 2015-08-25
page optional	0 based index for the page of users to return. Default is 0.
pageSize optional	Number of users per page. Default is 100 Max. 1000
user optional	Id of user for which to fetch the absences Must be a GUID
type optional	Absence type to filter by Integer id for the desired absence type See available absence types e.g. 14
status optional	Absence status to filter by Integer id for the desired absence status e.g. 1 = Pending, 2 = Approved, 5 = Cancelled

RETURNS: Page containing an array of filtered absences.

Example Request:


    POST

    https://YOUR-SYSTEM.e-days.co.uk/api/absence?user=c74cc4d1-de02-41e3-9ceb-8d11dba8ee32
                                                &start=2016-01-01
                                                &end=2016-06-01

Example Response:


    {
      "PageIndex": 0,
      "PageSize": 100,
      "TotalPages": 1,
      "TotalAbsences": 5,
      "Absences": [
        {
          "UserId": "c74cc4d1-de02-41e3-9ceb-8d11dba8ee32",
          "AbsenceId": "69c245c4-69fc-4130-97df-f86b9f9cc208",
          "AbsenceTypeId": 14,
          "AbsenceTypeName": "Holiday",
          "Start": "2016-04-21T00:00:00",
          "End": "2016-04-21T23:59:59.9",
          "Days": 1,
          "Minutes": 480,
          "DateRange": "on 2016.04.21",
          "Details": "Spain vacations",
          "StatusId": 1,
          "StatusName": "Pending"
        },
        {
          "UserId": "c74cc4d1-de02-41e3-9ceb-8d11dba8ee32",
          "AbsenceId": "238f5702-4d74-4573-9b9b-683b54930419",
          "AbsenceTypeId": 15,
          "AbsenceTypeName": "Sickness",
          "Start": "2016-04-19T09:00:00",
          "End": "2016-04-19T11:00:00",
          "Days": 0.25,
          "Minutes": 120,
          "DateRange": "from 2016.04.19 09:00 to 2016.04.19 11:00",
          "Details": "Had to go to a doctor's appointment",
          "StatusId": 2,
          "StatusName": "Approved"
        },
        {
          "UserId": "c74cc4d1-de02-41e3-9ceb-8d11dba8ee32",
          "AbsenceId": "ef8b6b8c-e2b6-4f79-a4d9-04d6df9fc281",
          "AbsenceTypeId": 17,
          "AbsenceTypeName": "Training",
          "Start": "2016-04-15T09:00:00",
          "End": "2016-04-15T10:00:00",
          "Days": 0.12,
          "Minutes": 60,
          "DateRange": "from 2016.04.15 09:00 to 2016.04.15 10:00",
          "Details": "Marketing training course.",
          "StatusId": 5,
          "StatusName": "Cancelled"
        }
      ]
    }

Fetch Absence Types

Resource URL:


    https://YOUR-SYSTEM.e-days.co.uk/api/absenceTypes

HTTP Method: POST

Parameters: NONE

RETURNS: Array of absence types with Id and Name

Example Request:


    POST

    https://YOUR-SYSTEM.e-days.co.uk/api/absenceTypes

Example Response:


    [
      {
      "Id": 14,
      "Name": "Holiday"
      },
      {
        "Id": 15,
        "Name": "Sickness"
      },
      {
        "Id": 17,
        "Name": "Training"
      }
    ]

Create Absence

Resource URL:


    https://YOUR-SYSTEM.e-days.co.uk/api/absence

HTTP Method: POST

Parameters:

user required	Id of user for which to create an absence Must be a GUID
type required	Absence type id Must be an integer. See Fetch Absence types method.
timeUnit required	Booking time unit Must be an integer. 0 for HOURS, 1 for DAYS
start required	Start date / time Must be in the following format: yyyy-MM-dd or yyyy-MM-ddThh:mm e.g. 2015-08-25 when booking in DAYS or 2015-08-25T10:00 when booking in HOURS
end required	End date / time Must be in the following format: yyyy-MM-dd or yyyy-MM-ddThh:mm e.g. 2015-08-25 when booking in DAYS or 2015-08-25T10:00 when booking in HOURS
details optional	Absence detail text description Text must be URL Encoded e.g. for "Got the flu": Got%20the%20flu

RETURNS: String that represents the result of the attempted absence creation. Possible values are:

'Created' - Absence successfully created
'OverBooked' - Insufficient absence entitlement remaining
'Conflicted' - Absence period conflicted with existing absence
'NoTimeOff' - Absence period does not cover any user time in work
'ExceedsMinimumStaffLevel' - Minimum staffing levels set up for the users group. This absence would result in the minimum level being breached
'PermissionDenied' - Booking user does not have permission to book absence for the specified user
'Created' - Absence successfully created

Example Request:


    POST

    https://YOUR-SYSTEM.e-days.co.uk/api/absences?user=e49f4f50-7e88-e511-93f4-72228baf5f68
                                                 &type=14
                                                 &timeUnit=0
                                                 &start=2016-06-14T10:00
                                                 &end=2016-06-14T11:00
                                                 &details=Taking%20Marketing%20course

Example Response:


    "Created"

Rota API

The Rota API will allow you to query user schedules to find out if they are scheduled to work at a specific date/time. Also, it will provide schedule details for a particular user.

Fetch Rota for user

Resource URL:


    https://YOUR-SYSTEM.e-days.co.uk/api/rota

HTTP Method: POST

Parameters:

user
required

Id of user for which to fetch the rota schedule(s)
Must be a GUID

RETURNS: Array of strings corresponding to the NAMES of the rotas applied to the user.

Example Request:


    POST

    https://YOUR-SYSTEM.e-days.co.uk/api/rota?user=c74cc4d1-de02-41e3-9ceb-8d11dba8ee32

Example Response:


    [
      "Mon/Tue/Wed/Thur/Fri"
    ]

Is User at Work

Resource URL:


    https://YOUR-SYSTEM.e-days.co.uk/api/rota/isUserAtWork

HTTP Method: POST

Parameters:

user required	Id of user for which to fetch the schedule information Must be a GUID
date required	Date to check Must be in the following format: yyyy-MM-dd e.g. 2015-08-25

RETURNS: True or False depending on whether or not the user is scheduled to work on the provided date.

Example Request:


    POST

    https://YOUR-SYSTEM.e-days.co.uk/api/rota/isUserAtWork?user=c74cc4d1-de02-41e3-9ceb-8d11dba8ee32
                                                          &date=2016-01-01

Example Response:


  "True"

Fetch Public Holidays

Resource URL:


    https://YOUR-SYSTEM.e-days.co.uk/api/rota/publicHolidays

HTTP Method: POST

Parameters:

start required	Start date Must be in the following format: yyyy-MM-dd e.g. 2015-08-25
end required	End date Must be in the following format: yyyy-MM-dd e.g. 2015-08-25

RETURNS: A list of any public holidays setup in your edays system within the specified date range.

Example Request:


    POST

    https://YOUR-SYSTEM.e-days.co.uk/api/rota/publicHolidays?start=2016-01-01
                                                            &end=2016-12-31

Example Response:


    [
      {
        "HolidayGroup": "UK Holidays",
        "Date": "06/04/2016"
      },
      {
        "HolidayGroup": "UK Holidays",
        "Date": "04/05/2016"
      },
      {
        "HolidayGroup": "UK Holidays",
        "Date": "25/05/2016"
      },
      {
        "HolidayGroup": "US Holidays",
        "Date": "30/05/2016"
      },
      {
        "HolidayGroup": "US Holidays",
        "Date": "19/06/2016"
      },
      {
        "HolidayGroup": "US Holidays",
        "Date": "04/07/2016"
      }
    ]