LeaveApplications


Overview

URL https://api.xero.com/payroll.xro/1.0/LeaveApplications
Methods Supported POST, GET
Description Allows you to retrieve, add and update Payroll leave applications in a Xero organisation

Elements for LeaveApplications

The following are required to create a new leave application
EmployeeID The Xero identifier for Payroll Employee
LeaveTypeID The Xero identifier for Leave Type
Title The title of the leave (max length = 50)
StartDate Start date of the leave (YYYY-MM-DD)
EndDate End date of the leave (YYYY-MM-DD)
The following are optional elements when creating a new leave application
Description The Description of the Leave (max length = 200)
LeavePeriods The leave period information

Elements for a LeavePeriod

NumberOfUnits The Number of Units for the leave
PayPeriodEndDate The Pay Period End Date (YYYY-MM-DD)
PayPeriodStartDate The Pay Period Start Date (YYYY-MM-DD)
LeavePeriodStatus See LeavePeriodStatus

GET LeaveApplications

Required parameters

Record filter The Xero identifier for an employee i.e.
GET https://…/LeaveApplications/{employeeID}

Optional parameters

Modified After The ModifiedAfter filter is actually an HTTP header: ‘If-Modified-Since‘.
A UTC timestamp (yyyy-mm-ddThh:mm:ss) . Only leave applications created or modified since this timestamp will be returned e.g. 2009-11-12T00:00:00
page By default the number of records returned per call is 100. You can add GET https://…/LeaveApplications?page=2 to get the next set of records.
Where Filter by an any element (see Filters)
order Order by any element returned (see Order By)

Example response for GET LeaveApplications/{employeeID}

<LeaveApplications>
  <LeaveApplication>
    <LeaveApplicationID>e0eb6747-7c17-4075-b804-989f8d4e5d39</LeaveApplicationID>
    <EmployeeID>fb4ebd68-6568-41eb-96ab-628a0f54b4b8</EmployeeID>
    <LeaveTypeID>742998cb-7584-4ecf-aa88-d694f59c50f9</LeaveTypeID>
    <LeavePeriods>
      <LeavePeriod>
        <PayPeriodStartDate>2013-04-29T00:00:00</PayPeriodStartDate>
        <PayPeriodEndDate>2013-05-12T00:00:00</PayPeriodEndDate>
        <LeavePeriodStatus>SCHEDULED</LeavePeriodStatus>
        <NumberOfUnits>22.8000</NumberOfUnits>
      </LeavePeriod>
    </LeavePeriods>
    <Title>Annual Leave</Title>
    <StartDate>2013-05-08T00:00:00</StartDate>
    <EndDate>2013-05-10T00:00:00</EndDate>
    <UpdatedDateUTC>2013-04-01T23:02:36</UpdatedDateUTC>
  </LeaveApplication>
</LeaveApplications>

POST LeaveApplications

Use this method to create and update SCHEDULED leave applications. Note only one employee’s leave application can be processed in each request

Example using minimum required elements to add a new leave application

<LeaveApplications>
  <LeaveApplication>
    <EmployeeID>5abad362-28aa-4c2c-a9cb-0899f7262d62</EmployeeID>
    <LeaveTypeID>dc182d9a-a270-4f4e-acd7-af702d5a4382</LeaveTypeID>
    <Title>My Test Leave</Title>
    <StartDate>2013-04-11</StartDate>
    <EndDate>2013-04-11</EndDate>
  </LeaveApplication>
</LeaveApplications>

In the above example we automatically calculate the number of units for the leave application, but you can also add your own number of units.

Example of specifying the number of units for a leave application

<LeaveApplications>
  <LeaveApplication>
    <EmployeeID>5abad362-28aa-4c2c-a9cb-0899f7262d62</EmployeeID>
    <LeaveTypeID>dc182d9a-a270-4f4e-acd7-af702d5a4382</LeaveTypeID>
    <LeavePeriods>
      <LeavePeriod>
        <PayPeriodEndDate>2013-04-14</PayPeriodEndDate>
        <NumberOfUnits>5.0000</NumberOfUnits>
      </LeavePeriod>
    </LeavePeriods>
    <Title>My Test Leave</Title>
    <StartDate>2013-04-11</StartDate>
    <EndDate>2013-04-11</EndDate>
  </LeaveApplication>
</LeaveApplications>

Note that in above example you need to provide the leave period information with Pay period end date as well as Number of units. You can have many leave period in one leave application. This depends on your pay run calendar type for the employee and leave application Start date and End date.

NOTE: If you want to update the Number of units of an existing leave application you will need at least provide the <PayPeriodEndDate> and NumberOfUnits in the body. If your request includes an incorrect <PayPeriodEndDate> a validation error will be raised.