API Reference
The iPayroll REST API allows you to query and manipulate data held by iPayroll about organisations and their employees. It uses predictable, resource-oriented URLs, and communicates API errors using HTTP response codes.
The iPayroll API uses standard HTTP Verbs, JSON and Oauth2.
The API can be used directly by clients developing their own applications. Third party applications can also be authorised by clients to access information on their behalf.
Base URL
All URLs referenced in the documentation have the following base:
https://secure2.ipayroll.co.nz/api/v1
The iPayroll REST API is served over HTTPS. Plain HTTP is not supported.
Functionality
The iPayroll API supports the following actions:
- Get employees
- Create employees
- Get pay rates for an employee
- Get custom fields for an employee
- Get payslips
- Get leave balances for an employee
- Get leave requests
- Get timesheets associated with the latest payroll
- Get cost centres
- Create cost centres
- Get pay elements
- Get List of Payrolls
- Get leave balance types
Scopes
Data available via the iPayroll API is grouped into scopes.
Scopes allow an organisation to expose only a particular section of their data to a third-party application. For example, permission can be granted only to access employee details, but not their timesheets.
The iPayroll API supports the following scopes:
- Employees (employees)
- Timesheets (timesheets)
- Pay Rates (payrates)
- Custom Fields (customfields)
- Cost Centres (costcentres)
- Leave Balances (leavebalances)
- Leave Requests (leaverequests)
- Payslips (payslips)
- Pay Elements (payelements)
- Payrolls (payrolls)
Your application will have to request access for the scopes it is interested in, and the user will have to grant that access.
Getting Started
To begin using the API, you first need to register a developer account by emailing api@ipayroll.co.nz with your request. We will then provide you with the following on our sandbox:
application-account: This is the account your application can use to make API calls.
developer-account: You may use this account to login to your application's dashboard where you can obtain your client id and secret, and also configure your application.
organisation-account (client): The developer and application accounts are not associated with a specific organisation, therefore, you can not access any data that belongs to a particular organisation if you login with your developer account.
In order to make any productive API calls, you'll need access to an organisation in the system. So you can use one of the organisation's user accounts to grant permission to your application to access organisation's data.
Whether you are an existing iPayroll customer or a third party developer who wants to integrate with iPayroll, a new organisation would be created in the demo environment, along with a user account with full access rights to the organisation. You can use this account to set data up for your organisation to test API calls or verify information uploaded through the API.
Developer Overview
Technologies used
The iPayroll API comprises a set of REST services. It accepts JSON formatted payloads where applicable, and always returns JSON data along with HATEOAS style links indicating further actions that can be performed on data elements. OAuth 2 is used for authorisation.
Environments
iPayroll provides two API environments.
https://sandbox.ipayroll.co.nz - This is the test environement used when developing and testing your applications.
https://secure2.ipayroll.co.nz - This is the live production system.
Remember: Those environments require use of HTTPS.
Requests
All requests to iPayroll API end-points require your application to authenticate. Authentication is token based. This means that a valid access token must be attached to every API request, either as a HTTP header or as a request parameter.
We provide a detailed authentication and authorisation guide in the Authorisation How to.
The parameter types in the document are described in the following table:
| Type | Description | Examples |
|---|---|---|
| String | A sequence of characters | "This is a String" |
| Integer | Whole number, with no fractional part | 1000 |
| Number | A number which may contain a fractional part of up to 4 digits | 1.1234 |
| JSON Object | JavaScript Object Notation | {"foo" : "bar"} |
Retrieving Resources with HTTP GET
Your application may retrieve a representation of a resource by GETting the correct URLs. Successful GET requests return HTTP code 200.
Response Format
All of the responses from iPayroll's API are in JSON format.
Date Formats
Definition of letters used:
| Letter | Represented component | Examples |
|---|---|---|
| d | Day in month | 10 |
| M | Month in year | Jul when MMM; 07 when MM |
| y | Year | 1996 when yyyy; 96 when yy |
When posting data, you may use any of the following formats:
- dd-MM-yyyy
- dd-MMM-yyyy
- yyyy-MM-dd
- yyyy-MMM-dd
- dd/MM/yy
- dd/MM/yyyy
- dd/MMM/yy
- dd/MMM/yyyy
- MM/dd/yy
- MM/dd/yyyy
- dd/MM
- dd/MMM
Links
Elements in the response may contain HATEOAS style links indicating further, related actions.
For example, a response containing an employee element, may contain links for the employee's payrate and timeshseet endpoints.
{
"links": [
{
"rel": "self",
"href": "https://sandbox.ipayroll.co.nz/api/v1/employees/1"
},
{
"rel": "payrate",
"href": "https://sandbox.ipayroll.co.nz/api/v1/employees/1/payrates"
},
{
"rel": "timesheet",
"href": "https://sandbox.ipayroll.co.nz/api/v1/timesheets/1"
}
],
"surname": "White",
"firstNames": "Jason",
"employeeId": "1",
...rest of the properties...
}
Pagination
Some of the end points provided by the iPayroll API return multiple elements. These would typically be 'get all' requests such as 'list employees' or 'list cost centres'.
To avoid large payloads, the iPayroll API supports pagination for this type of requests, and will default to returning maximum 20 elements.
{
"content": [
{element 1},
{element 2},
{element 3},
{element 4},
],
"page": {
"size": 20,
"totalElements": 4,
"totalPages": 1,
"number": 0
}
}
The iPayroll API lets you control page data by using the page and size request parameters:
https://sandbox.ipayroll.co.nz/api/v1/employees?size=5 https://sandbox.ipayroll.co.nz/api/v1/employees?size=5&page=2
- size: an integer denoting how many elements to return per page
- page: an integer denoting the page number (zero based) required.
When paging is applicable, the response will contain links to navigate through pages:
{
"content": [
...elements of this page...
],
"page": {
"size": 5,
"totalElements": 23,
"totalPages": 5,
"number": 0
},
"links": [
{
"rel": "first",
"href": "https://sandbox.ipayroll.co.nz/api/v1/employees?page=0&size=5"
},
{
"rel": "self",
"href": "https://sandbox.ipayroll.co.nz/api/v1/employees?size=5"
},
{
"rel": "next",
"href": "https://sandbox.ipayroll.co.nz/api/v1/employees?page=1&size=5"
},
{
"rel": "last",
"href": "https://sandbox.ipayroll.co.nz/api/v1/employees?page=4&size=5"
}
]
}
Error handling
When an error occurs, The iPayroll API returns an error response formatted as a JSON object. The HTTP status code of the response is set as well.
| Status code | Status description | Reason |
|---|---|---|
| 400 | BAD_REQUEST | Invalid request or request syntax |
| 401 | UNAUTHORIZED | User is not authenticated |
| 403 | FORBIDDEN | User is authenticated but not authorized to view the data |
| 404 | NOT_FOUND | Invalid URL |
| 412 | PRECONDITION_FAILED | Expected condition did not match |
| 422 | UNPROCESSABLE_ENTITY | Failed to process the request |
| 423 | LOCKED | Resource is in read-only state or access/update is disabled |
| 500 | INTERNAL_SERVER_ERROR | Server error |
Resources
Cost Centres
Cost Centres are disabled by default for an organisation. Make sure to enable through the UI before making API calls related to cost centres. Any call to cost centres would return an error with HTTP code 423 if disabled.
Attributes
| Name | Type | Description |
|---|---|---|
| id | Integer | Unique ID to identify a cost centre |
| code | String | The name of the cost centre. Unique within an organisation |
| description | String | Cost centre description |
GET /api/v1/costcentres
Retrieve All Cost Centres
Returns all the cost centres of an organisation.
POST /api/v1/costcentres
Create One Or More Cost Centres
Create one or more cost centres in an organisation.
Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| costCentres arrow_drop_downarrow_drop_up | Yes | JSON Object | A list of costCentres to be created. This end point takes a single cost centre or an array of cost centres |
GET /api/v1/costcentres/{costcentreId}
Retrieve A Cost Centre
Returns a particular cost centre of the organisation, identified by cost centre id.
Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| costcentreId | Yes | Integer | Unique ID to identify an employee within an organisation |
Employees
Attributes
| Name | Type | Description | ||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| id | String | Unique ID to identify an employee within an organisation | ||||||||||||||||||||||||||||||||||||
| birthDate | String | Date of birth (multiple date formats supported, dd/mm/yyyy preferred) | ||||||||||||||||||||||||||||||||||||
| defaultCostCentre | String | Default cost centre for the employee - value expected is one of the cost centre codes defined for the organisation | ||||||||||||||||||||||||||||||||||||
| String | Email address | |||||||||||||||||||||||||||||||||||||
| firstNames | String | All first names | ||||||||||||||||||||||||||||||||||||
| fullTimeHoursWeek | Number | Describes the number of hours the person would work in a week for their position, if they were employed full time. Is used to help convert salary into hourly rate | ||||||||||||||||||||||||||||||||||||
| gender | String | Male or Female or Gender Diverse | ||||||||||||||||||||||||||||||||||||
| organisation | Integer | Unique identification of the organisation that the employee belongs to | ||||||||||||||||||||||||||||||||||||
| paidToDate | String | Date up to which the employee has been paid (multiple date formats supported, dd/mm/yyyy preferred) | ||||||||||||||||||||||||||||||||||||
| payFrequency | String | Frequency of payroll - pay frequency name, code and description are supported:
|
||||||||||||||||||||||||||||||||||||
| phone | String | Phone number | ||||||||||||||||||||||||||||||||||||
| startDate | String | Date on which the employee joined the organisation (multiple date formats supported, dd/mm/yyyy preferred) | ||||||||||||||||||||||||||||||||||||
| workState | String | State in which the employee works - only applicable to Australian organisations (refer address state for possible values), Code is supported.
|
||||||||||||||||||||||||||||||||||||
| surname | String | Surname of the employee | ||||||||||||||||||||||||||||||||||||
| title | String | Job title | ||||||||||||||||||||||||||||||||||||
| preferredName | String | Prefered Name of the employee | ||||||||||||||||||||||||||||||||||||
| userDefinedGroup | String | User Defined Group of the employee | ||||||||||||||||||||||||||||||||||||
| paymentMethod | String | Method of the employee is being paid. Code and Description are supported.
|
||||||||||||||||||||||||||||||||||||
| bankAccountNumber | String | Bank account number of the employee | ||||||||||||||||||||||||||||||||||||
| taxNumber | String | Tax number of the employee | ||||||||||||||||||||||||||||||||||||
| finishDate | String | Final Pay day of the employee | ||||||||||||||||||||||||||||||||||||
| terminationReason | String | Termination reason of the employee | ||||||||||||||||||||||||||||||||||||
| deathBenefitSurname | String | Death beneficiaries Surname | ||||||||||||||||||||||||||||||||||||
| deathBenefitFirstName | String | Death beneficiaries First Name | ||||||||||||||||||||||||||||||||||||
| deathBenefitRecipient | String | Death benefit recipient | ||||||||||||||||||||||||||||||||||||
| taxCode | String | New Zealand Tax Code of the employee | ||||||||||||||||||||||||||||||||||||
| taxScale | String | Australian Tax scale of the employee | ||||||||||||||||||||||||||||||||||||
| kiwiSaverRate | Number | Kiwisaver Employee Contribution rate of the employee | ||||||||||||||||||||||||||||||||||||
| employerSubsidy | Number | Employer's subsidy rate for Kiwisaver | ||||||||||||||||||||||||||||||||||||
| esctRate | Number | Tax rate that will be deducted from Superannuation Employer Contribution | ||||||||||||||||||||||||||||||||||||
| kiwiSaverOptOutDate | String | Opt out date of employee from Kiwisaver Mandatory if kiwiSaverStatus is Opted Out Address Line 1, City and Post Code are mandatory if an Opt Out Date exists |
||||||||||||||||||||||||||||||||||||
| existingKiwiSaverMember | Boolean | Indication of whether employee is existing KiwiSaver member. This attribute is legacy as of 21-Nov-2018. | ||||||||||||||||||||||||||||||||||||
| specialTax | Number | Special tax rate of the emploee | ||||||||||||||||||||||||||||||||||||
| specialStudentLoan | Number | Special Student Loan rates of the employee | ||||||||||||||||||||||||||||||||||||
| specialEarnerLevy | Number | Special Earner Levy rate of the employee | ||||||||||||||||||||||||||||||||||||
| specialExtraPayRate | Number | Special Extra Pay Rate of the employee | ||||||||||||||||||||||||||||||||||||
| helpDebt | Boolean | HELP Debt | ||||||||||||||||||||||||||||||||||||
| sfssDebt | Boolean | SFSS Debt | ||||||||||||||||||||||||||||||||||||
| medicareLevyVariationDeclaration | Boolean | Has the employee filled a Medicare levy variation declaration | ||||||||||||||||||||||||||||||||||||
| hasSpouse | Boolean | Spouse | ||||||||||||||||||||||||||||||||||||
| incomeLessThanRelevantAmount | Boolean | Is the combined weekly income of payee and payee's spouse, or the payee's income as a sole parent, less than the relevant amount in table A | ||||||||||||||||||||||||||||||||||||
| payrollTaxExempt | Boolean | Payroll Tax Exempt | ||||||||||||||||||||||||||||||||||||
| dependentChildren | Number | Number of dependent children of the employee | ||||||||||||||||||||||||||||||||||||
| surchargeIncrease | Number | Surcharge increase | ||||||||||||||||||||||||||||||||||||
| proprietorStatus | String | Proprietor Status of the employee. Description is supported.
|
||||||||||||||||||||||||||||||||||||
| contractorsAbn | String | Contractors ABN | ||||||||||||||||||||||||||||||||||||
| address arrow_drop_downarrow_drop_up | JSON Object | A JSON object representing the address. | ||||||||||||||||||||||||||||||||||||
| daysPerPeriod | Number | Permanent days per period that the Person is expected to work, when Average Daily Pay is enabled | ||||||||||||||||||||||||||||||||||||
| dailyPayType | String | Daily pay type, when Average Daily Pay is enabled. Code is supported
|
||||||||||||||||||||||||||||||||||||
| holidayCalendar | String | Applicable public holiday calendar | ||||||||||||||||||||||||||||||||||||
| defineSetHoursPerDay | Boolean | Define set hours per day True if standard hours exist for any day | ||||||||||||||||||||||||||||||||||||
| kiwiSaverHolidayEndDate | String | New Zealand only. Date on which the KiwiSaver Contributions Holiday will end (multiple date formats supported, dd/mm/yyyy preferred) |
||||||||||||||||||||||||||||||||||||
| notSuppliedAddress | Boolean | New Zealand only. Mandatory. True if employee has not supplied an address. Must be True if any of addressLine1, city and postCode are empty strings. |
||||||||||||||||||||||||||||||||||||
| notSuppliedDateOfBirth | Boolean | New Zealand only. Mandatory. True if employee has not supplied a date of birth. Must be True if birthDate is an empty string. |
||||||||||||||||||||||||||||||||||||
| kiwiSaverStatus | String | New Zealand only. KiwiSaver status
|
||||||||||||||||||||||||||||||||||||
| timecardEmployeeSettingsarrow_drop_downarrow_drop_up | JSON Object | A JSON object representing the standard hours worked each day |
GET /api/v1/employees
Retrieve All Employees
Returns all the active employees of an organisation
POST /api/v1/employees
Create one or more employees
Create one or more employees in an organisation. This cannot be used to update details of an existing employee.
Parameters
| Name | Required | Type | Description | ||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| id | No | String | Unique ID to identify an employee within an organisation | ||||||||||||||||||||||||||||||||||||
| birthDate | No | String | Date of birth (multiple date formats supported, dd/mm/yyyy preferred) | ||||||||||||||||||||||||||||||||||||
| defaultCostCentre | No | String | Default cost centre for the employee - value expected is one of the cost centre codes defined for the organisation | ||||||||||||||||||||||||||||||||||||
| No | String | Email address | |||||||||||||||||||||||||||||||||||||
| firstNames | No | String | All first names | ||||||||||||||||||||||||||||||||||||
| fullTimeHoursWeek | No | Number | Describes the number of hours the person would work in a week for their position, if they were employed full time. Is used to help convert salary into hourly rate | ||||||||||||||||||||||||||||||||||||
| gender | No | String | Male or Female or Gender Diverse | ||||||||||||||||||||||||||||||||||||
| paidToDate | No | String | Date up to which the employee has been paid (multiple date formats supported, dd/mm/yyyy preferred) | ||||||||||||||||||||||||||||||||||||
| payFrequency | No | String | Frequency of payroll - pay frequency name, code and description are supported:
|
||||||||||||||||||||||||||||||||||||
| phone | No | String | Phone number | ||||||||||||||||||||||||||||||||||||
| startDate | No | String | Date on which the employee joined the organisation (multiple date formats supported, dd/mm/yyyy preferred) | ||||||||||||||||||||||||||||||||||||
| workState | No | String | State in which the employee works - only applicable to Australian organisations (refer address state for possible values), Code is supported.
|
||||||||||||||||||||||||||||||||||||
| surname | Yes | String | Surname of the employee | ||||||||||||||||||||||||||||||||||||
| title | No | String | Job Title of the employee | ||||||||||||||||||||||||||||||||||||
| preferredName | No | String | Prefered Name of the employee | ||||||||||||||||||||||||||||||||||||
| userDefinedGroup | No | String | User Defined Group of the employee | ||||||||||||||||||||||||||||||||||||
| paymentMethod | No | String | Method of the employee is being paid. Code and Description are supported.
|
||||||||||||||||||||||||||||||||||||
| bankAccountNumber | No | String | Bank account number of the employee | ||||||||||||||||||||||||||||||||||||
| taxNumber | No | String | Tax number of the employee | ||||||||||||||||||||||||||||||||||||
| finishDate | No | String | Final Pay day of the employee | ||||||||||||||||||||||||||||||||||||
| terminationReason | No | String | Termination reason of the employee | ||||||||||||||||||||||||||||||||||||
| deathBenefitSurname | No | String | Death beneficiaries Surname | ||||||||||||||||||||||||||||||||||||
| deathBenefitFirstName | No | String | Death beneficiaries First Name | ||||||||||||||||||||||||||||||||||||
| deathBenefitRecipient | No | String | Death benefit recipient | ||||||||||||||||||||||||||||||||||||
| taxCode | No | String | New Zealand Tax Code of the employee | ||||||||||||||||||||||||||||||||||||
| taxScale | No | String | Australian Tax scale of the employee | ||||||||||||||||||||||||||||||||||||
| kiwiSaverRate | No | Number | Kiwisaver Employee Contribution rate of the employee | ||||||||||||||||||||||||||||||||||||
| employerSubsidy | No | Number | Employer's subsidy rate for Kiwisaver | ||||||||||||||||||||||||||||||||||||
| esctRate | No | Number | Tax rate that will be deducted from Superannuation Employer Contribution | ||||||||||||||||||||||||||||||||||||
| kiwiSaverOptOutDate | No | String | Opt out date of employee from Kiwisaver Mandatory if kiwiSaverStatus is Opted Out Address Line 1, City and Post Code are mandatory if an Opt Out Date exists |
||||||||||||||||||||||||||||||||||||
| existingKiwiSaverMember | No | Boolean | Indication of whether employee is existing KiwiSaver member. This attribute is legacy as of 21-Nov-2018. | ||||||||||||||||||||||||||||||||||||
| specialTax | No | Number | Special tax rate of the emploee | ||||||||||||||||||||||||||||||||||||
| specialStudentLoan | No | Number | Special Student Loan rates of the employee | ||||||||||||||||||||||||||||||||||||
| specialEarnerLevy | No | Number | Special Earner Levy rate of the employee | ||||||||||||||||||||||||||||||||||||
| specialExtraPayRate | No | Number | Special Extra Pay Rate of the employee | ||||||||||||||||||||||||||||||||||||
| helpDebt | No | Boolean | HELP Debt | ||||||||||||||||||||||||||||||||||||
| sfssDebt | No | Boolean | SFSS Debt | ||||||||||||||||||||||||||||||||||||
| medicareLevyVariationDeclaration | No | Boolean | Has the employee filled a Medicare levy variation declaration | ||||||||||||||||||||||||||||||||||||
| hasSpouse | No | Boolean | Spouse | ||||||||||||||||||||||||||||||||||||
| incomeLessThanRelevantAmount | No | Boolean | Is the combined weekly income of payee and payee's spouse, or the payee's income as a sole parent, less than the relevant amount in table A | ||||||||||||||||||||||||||||||||||||
| payrollTaxExempt | No | Boolean | Payroll Tax Exempt | ||||||||||||||||||||||||||||||||||||
| dependentChildren | No | Number | Number of dependent children of the employee | ||||||||||||||||||||||||||||||||||||
| surchargeIncrease | No | Number | Surcharge increase | ||||||||||||||||||||||||||||||||||||
| proprietorStatus | No | String | Proprietor Status of the employee. Description is supported.
|
||||||||||||||||||||||||||||||||||||
| contractorsAbn | No | String | Contractors ABN | ||||||||||||||||||||||||||||||||||||
| address arrow_drop_downarrow_drop_up | No | JSON Object | A JSON object representing the address. | ||||||||||||||||||||||||||||||||||||
| daysPerPeriod | No | Number | Permanent days per period that the Person is expected to work, when Average Daily Pay is enabled | ||||||||||||||||||||||||||||||||||||
| dailyPayType | No | String | Daily pay type, when Average Daily Pay is enabled. Code is supported
|
||||||||||||||||||||||||||||||||||||
| holidayCalendar | No | String | Applicable public holiday calendar | ||||||||||||||||||||||||||||||||||||
| defineSetHoursPerDay | No | Boolean | Define set hours per day True if standard hours exist for any day | ||||||||||||||||||||||||||||||||||||
| kiwiSaverHolidayEndDate | No | String | New Zealand only. Date on which the KiwiSaver Contributions Holiday will end (multiple date formats supported, dd/mm/yyyy preferred) |
||||||||||||||||||||||||||||||||||||
| notSuppliedAddress | No | Boolean | New Zealand only. Mandatory. True if employee has not supplied an address. Must be True if any of addressLine1, city and postCode are empty strings. |
||||||||||||||||||||||||||||||||||||
| notSuppliedDateOfBirth | No | Boolean | New Zealand only. Mandatory. True if employee has not supplied a date of birth. Must be True if birthDate is an empty string. |
||||||||||||||||||||||||||||||||||||
| kiwiSaverStatus | No | String | New Zealand only. KiwiSaver status
|
||||||||||||||||||||||||||||||||||||
| timecardEmployeeSettingsarrow_drop_downarrow_drop_up | No | JSON Object | A JSON object representing the standard hours worked each day |
POST /api/v1/employees
Request Body Example
[
{
"id":"myCustomId",
"surname":"iPayroll",
"firstNames":"Jackie",
"address":{
"country":"New Zealand"
},
"startDate":"1-May-2014",
"email":"email@email.com",
"gender":"Female",
"payFrequency":"Fortnightly",
"fullTimeHoursWeek":33
}
...
]
Response Example
[
{
"id":"myCustomId",
"firstNames":"Jackie",
"address":{
"country":"New Zealand"
},
"startDate":"1-May-2014",
"email":"email@email.com",
"gender":"Female",
"payFrequency":"Fortnightly",
"fullTimeHoursWeek":33,
"organisation":10000,
"links":[
{
"rel":"self",
"href":"https://secure2.ipayroll.co.nz/api/v1/employees/1111"
},
{
"rel":"payrate",
"href":"https://secure2.ipayroll.co.nz/api/v1/employees/1111/payrates"
},
{
"rel":"timesheet",
"href":"https://secure2.ipayroll.co.nz/api/v1/timesheets/1111"
},
{
"rel":"customField",
"href":"https://secure2.ipayroll.co.nz/api/v1/employees/1111/customfields"
}
]
}
]
PUT /api/v1/employees/{employeeId}
Update an employee
Update one employee in an organisation.
Parameters
| Name | Required | Type | Description | ||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| id | No | String | Unique ID to identify an employee within an organisation | ||||||||||||||||||||||||||||||||||||
| birthDate | No | String | Date of birth (multiple date formats supported, dd/mm/yyyy preferred) | ||||||||||||||||||||||||||||||||||||
| defaultCostCentre | No | String | Default cost centre for the employee - value expected is one of the cost centre codes defined for the organisation | ||||||||||||||||||||||||||||||||||||
| No | String | Email address | |||||||||||||||||||||||||||||||||||||
| firstNames | No | String | All first names | ||||||||||||||||||||||||||||||||||||
| fullTimeHoursWeek | No | Number | Describes the number of hours the person would work in a week for their position, if they were employed full time. Is used to help convert salary into hourly rate | ||||||||||||||||||||||||||||||||||||
| gender | No | String | Male or Female or Gender Diverse | ||||||||||||||||||||||||||||||||||||
| paidToDate | No | String | Date up to which the employee has been paid (multiple date formats supported, dd/mm/yyyy preferred) | ||||||||||||||||||||||||||||||||||||
| payFrequency | No | String | Frequency of payroll - pay frequency name, code and description are supported:
|
||||||||||||||||||||||||||||||||||||
| phone | No | String | Phone number | ||||||||||||||||||||||||||||||||||||
| startDate | No | String | Date on which the employee joined the organisation (multiple date formats supported, dd/mm/yyyy preferred) | ||||||||||||||||||||||||||||||||||||
| workState | No | String | State in which the employee works - only applicable to Australian organisations (refer address state for possible values), Code is supported.
|
||||||||||||||||||||||||||||||||||||
| surname | Yes | String | Surname of the employee | ||||||||||||||||||||||||||||||||||||
| title | No | String | Job Title of the employee | ||||||||||||||||||||||||||||||||||||
| preferredName | No | String | Prefered Name of the employee | ||||||||||||||||||||||||||||||||||||
| userDefinedGroup | No | String | User Defined Group of the employee | ||||||||||||||||||||||||||||||||||||
| paymentMethod | No | String | Method of the employee is being paid. Code and Description are supported.
|
||||||||||||||||||||||||||||||||||||
| bankAccountNumber | No | String | Bank account number of the employee | ||||||||||||||||||||||||||||||||||||
| taxNumber | No | String | Tax number of the employee | ||||||||||||||||||||||||||||||||||||
| finishDate | No | String | Final Pay day of the employee | ||||||||||||||||||||||||||||||||||||
| terminationReason | No | String | Termination reason of the employee | ||||||||||||||||||||||||||||||||||||
| deathBenefitSurname | No | String | Death beneficiaries Surname | ||||||||||||||||||||||||||||||||||||
| deathBenefitFirstName | No | String | Death beneficiaries First Name | ||||||||||||||||||||||||||||||||||||
| deathBenefitRecipient | No | String | Death benefit recipient | ||||||||||||||||||||||||||||||||||||
| taxCode | No | String | New Zealand Tax Code of the employee | ||||||||||||||||||||||||||||||||||||
| taxScale | No | String | Australian Tax scale of the employee | ||||||||||||||||||||||||||||||||||||
| kiwiSaverRate | No | Number | Kiwisaver Employee Contribution rate of the employee | ||||||||||||||||||||||||||||||||||||
| employerSubsidy | No | Number | Employer's subsidy rate for Kiwisaver | ||||||||||||||||||||||||||||||||||||
| esctRate | No | Number | Tax rate that will be deducted from Superannuation Employer Contribution | ||||||||||||||||||||||||||||||||||||
| kiwiSaverOptOutDate | No | String | Opt out date of employee from Kiwisaver Mandatory if kiwiSaverStatus is Opted Out Address Line 1, City and Post Code are mandatory if an Opt Out Date exists |
||||||||||||||||||||||||||||||||||||
| existingKiwiSaverMember | No | Boolean | Indication of whether employee is existing KiwiSaver member. This attribute is legacy as of 21-Nov-2018. | ||||||||||||||||||||||||||||||||||||
| specialTax | No | Number | Special tax rate of the emploee | ||||||||||||||||||||||||||||||||||||
| specialStudentLoan | No | Number | Special Student Loan rates of the employee | ||||||||||||||||||||||||||||||||||||
| specialEarnerLevy | No | Number | Special Earner Levy rate of the employee | ||||||||||||||||||||||||||||||||||||
| specialExtraPayRate | No | Number | Special Extra Pay Rate of the employee | ||||||||||||||||||||||||||||||||||||
| helpDebt | No | Boolean | HELP Debt | ||||||||||||||||||||||||||||||||||||
| sfssDebt | No | Boolean | SFSS Debt | ||||||||||||||||||||||||||||||||||||
| medicareLevyVariationDeclaration | No | Boolean | Has the employee filled a Medicare levy variation declaration | ||||||||||||||||||||||||||||||||||||
| hasSpouse | No | Boolean | Spouse | ||||||||||||||||||||||||||||||||||||
| incomeLessThanRelevantAmount | No | Boolean | Is the combined weekly income of payee and payee's spouse, or the payee's income as a sole parent, less than the relevant amount in table A | ||||||||||||||||||||||||||||||||||||
| payrollTaxExempt | No | Boolean | Payroll Tax Exempt | ||||||||||||||||||||||||||||||||||||
| dependentChildren | No | Number | Number of dependent children of the employee | ||||||||||||||||||||||||||||||||||||
| surchargeIncrease | No | Number | Surcharge increase | ||||||||||||||||||||||||||||||||||||
| proprietorStatus | No | String | Proprietor Status of the employee. Description is supported.
|
||||||||||||||||||||||||||||||||||||
| contractorsAbn | No | String | Contractors ABN | ||||||||||||||||||||||||||||||||||||
| address arrow_drop_downarrow_drop_up | No | JSON Object | A JSON object representing the address. | ||||||||||||||||||||||||||||||||||||
| daysPerPeriod | No | Number | Permanent days per period that the Person is expected to work, when Average Daily Pay is enabled | ||||||||||||||||||||||||||||||||||||
| dailyPayType | No | String | Daily pay type, when Average Daily Pay is enabled. Code is supported
|
||||||||||||||||||||||||||||||||||||
| holidayCalendar | No | String | Applicable public holiday calendar | ||||||||||||||||||||||||||||||||||||
| defineSetHoursPerDay | No | Boolean | Define set hours per day True if standard hours exist for any day | ||||||||||||||||||||||||||||||||||||
| kiwiSaverHolidayEndDate | No | String | New Zealand only. Date on which the KiwiSaver Contributions Holiday will end (multiple date formats supported, dd/mm/yyyy preferred) |
||||||||||||||||||||||||||||||||||||
| notSuppliedAddress | No | Boolean | New Zealand only. Mandatory. True if employee has not supplied an address. Must be True if any of addressLine1, city and postCode are empty strings. |
||||||||||||||||||||||||||||||||||||
| notSuppliedDateOfBirth | No | Boolean | New Zealand only. Mandatory. True if employee has not supplied a date of birth. Must be True if birthDate is an empty string. |
||||||||||||||||||||||||||||||||||||
| kiwiSaverStatus | No | String | New Zealand only. KiwiSaver status
|
||||||||||||||||||||||||||||||||||||
| timecardEmployeeSettingsarrow_drop_downarrow_drop_up | No | JSON Object | A JSON object representing the standard hours worked each day |
PUT /api/v1/employees/{employeeId}
Request Body Example
{
"id":"newCustomId",
"surname":"Caroline",
"firstNames":"Jackie",
"preferredName":"Jackie",
"address":{
"addressLine1":"10 Leinster St",
"addressLine2":"abc",
"suburb":"suburb",
"city":"Wellington",
"postCode":"6611",
"country":"New Zealand"
},
"startDate":"18-Jul-2017",
"birthDate":"03-Jul-1992",
"paidToDate":"31-Dec-2017",
"defaultCostCentre":"CostCenter",
"userDefinedGroup":"AAAA",
"email":"email@gmail.com",
"phone":"0123456786",
"title":"SSE",
"gender":"Male",
"payFrequency":"Weekly",
"fullTimeHoursWeek":10,
"paymentMethod":"Bank",
"bankAccountNumber":"123456789",
"taxNumber":"00-000-000",
"taxCode":"A",
"kiwiSaverRate":4,
"employerSubsidy":4.2,
"esctRate":17.5,
"kiwiSaverOptOutDate":"26-Dec-2017",
"existingKiwiSaverMember":false,
"specialTax":2.7,
"specialStudentLoan":1.2,
"specialEarnerLevy":0.3,
"specialExtraPayRate":"HIGH",
"proprietorStatus":"Yes",
"holidayCalendar":"Wellington",
"defineSetHoursPerDay":true,
"kiwiSaverHolidayEndDate":"28-Jan-2018",
"notSuppliedAddress":true,
"notSuppliedDateOfBirth":true,
"kiwiSaverStatus":"Pre-existing member",
"timecardEmployeeSettings":{
"monStandardHours":7,
"tueStandardHours":7,
"wedStandardHours":3,
"thuStandardHours":8,
"friStandardHours":6,
"satStandardHours":0,
"sunStandardHours":0
}
}
Response Example
{
"id":"newCustomId",
"surname":"Caroline",
"firstNames":"Jackie",
"preferredName":"Jackie",
"address":{
"addressLine1":"10 Leinster St",
"addressLine2":"abc",
"suburb":"suburb",
"city":"Wellington",
"postCode":"6611",
"country":"New Zealand"
},
"startDate":"18-Jul-2017",
"birthDate":"03-Jul-1992",
"paidToDate":"31-Dec-2017",
"defaultCostCentre":"CostCenter",
"userDefinedGroup":"AAAA",
"email":"email@gmail.com",
"phone":"0123456786",
"title":"SSE",
"gender":"Male",
"payFrequency":"Weekly",
"fullTimeHoursWeek":10,
"organisation":40000,
"paymentMethod":"Bank",
"bankAccountNumber":"123456789",
"taxNumber":"00-000-000",
"taxCode":"A",
"kiwiSaverRate":4,
"employerSubsidy":4.2,
"esctRate":17.5,
"kiwiSaverOptOutDate":"26-Dec-2017",
"existingKiwiSaverMember":false,
"specialTax":2.7,
"specialStudentLoan":1.2,
"specialEarnerLevy":0.3,
"specialExtraPayRate":"HIGH",
"proprietorStatus":"Yes",
"holidayCalendar":"Wellington",
"defineSetHoursPerDay":true,
"kiwiSaverHolidayEndDate":"28-Jan-2018",
"notSuppliedAddress":true,
"notSuppliedDateOfBirth":true,
"kiwiSaverStatus":"Pre-existing member",
"timecardEmployeeSettings":{
"monStandardHours":7,
"tueStandardHours":7,
"wedStandardHours":3,
"thuStandardHours":8,
"friStandardHours":6,
"satStandardHours":0,
"sunStandardHours":0
},
"links":[
{
"rel":"self",
"href":"https://secure2.ipayroll.co.nz/api/v1/employees/12345"
},
{
"rel":"payrate",
"href":"https://secure2.ipayroll.co.nz/api/v1/employees/12345/payrates"
},
{
"rel":"timesheet",
"href":"https://secure2.ipayroll.co.nz/api/v1/timesheets/12345"
},
{
"rel":"customField",
"href":"https://secure2.ipayroll.co.nz/api/v1/employees/12345/customfields"
}
]
}
GET /api/v1/employees/{employeeId}
Retrieve an employee's details
Returns an employee.
Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| employeeId | Yes | String | Unique ID to identify an employee within an organisation |
GET /api/v1/employees/{employeeId}
Response Example
{
"id":"12345",
"surname":"Caroline",
"firstNames":"Jackie",
"preferredName":"Jackie",
"address":{
"addressLine1":"10 Leinster St",
"addressLine2":"abc",
"suburb":"suburb",
"city":"Wellington",
"state": "",
"stateName": ""
"postCode":"6611",
"country":"New Zealand"
},
"startDate":"18-Jul-2017",
"birthDate":"03-Jul-1992",
"paidToDate":"31-Dec-2017",
"defaultCostCentre":"CostCenter",
"userDefinedGroup":"AAAA",
"email":"email@gmail.com",
"phone":"0123456786",
"title":"SSE",
"gender":"Male",
"payFrequency":"Weekly",
"fullTimeHoursWeek":10,
"organisation":40000,
"paymentMethod":"Bank",
"bankAccountNumber":"123456789",
"taxNumber":"00-000-000",
"taxCode":"A",
"kiwiSaverRate":4,
"employerSubsidy":4.2,
"esctRate":17.5,
"kiwiSaverOptOutDate":"26-Dec-2017",
"existingKiwiSaverMember":false,
"specialTax":2.7,
"specialStudentLoan":1.2,
"specialEarnerLevy":0.3,
"specialExtraPayRate":"HIGH",
"proprietorStatus":"Yes",
"daysPerPeriod": 5,
"dailyPayType": "ADP",
"holidayCalendar":"Wellington",
"defineSetHoursPerDay":true,
"kiwiSaverHolidayEndDate":"28-Jan-2018",
"notSuppliedAddress":true,
"notSuppliedDateOfBirth":true,
"kiwiSaverStatus":"Pre-existing member",
"timecardEmployeeSettings":{
"monStandardHours":7,
"tueStandardHours":7,
"wedStandardHours":3,
"thuStandardHours":8,
"friStandardHours":6,
"satStandardHours":0,
"sunStandardHours":0
},
"links":[
{
"rel":"self",
"href":"https://secure2.ipayroll.co.nz/api/v1/employees/12345"
},
{
"rel":"payrate",
"href":"https://secure2.ipayroll.co.nz/api/v1/employees/12345/payrates"
},
{
"rel":"timesheet",
"href":"https://secure2.ipayroll.co.nz/api/v1/timesheets/12345"
},
{
"rel":"customField",
"href":"https://secure2.ipayroll.co.nz/api/v1/employees/12345/customfields"
}
]
}
Pay Rates
Pay rates define the expected base rate that will be used in paying a Person. A divisor is used to identify whether the rate is an hourly or annual type, and holds the formula to convert the rate between hourly and annual as required.
Attributes
| Name | Type | Description |
|---|---|---|
| id | String | Unique ID to identify a payrate |
| code | String | Indicates the position of the rate on Personal Details |
| rate | Number | Value of pay rate as entered in iPayroll |
| divisor | String | If an organisation specific divisor is associated, this field would contain the name of it. If not, a global divisor's name, e.g. "per hour", "per annum", "pa (Govt: 14/365th's)" or "pa (Aust: 12/313th's)". |
| payScale | String | Pay Scales are designed to allow pay rates to be set up under a code that can then be used for multiple people. Displayed if Pay Scales are used and a Pay Scale is selected for employee, e.g. K1P107. |
| annualRate | Number | Conversion of “rate” to an annualised rate using rules in divisor, e.g. 25 * 2080 = 52,000 |
| hourlyRate | Number | Conversion of “rate” to an hourly rate using rules in divisor e.g. 52,000 / 2080 = $25 |
GET /api/v1/employees/{employeeId}/payrates
Retrieve all of an employee’s pay rates
Returns details of all pay rates associated with an employee.
Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| employeeId | Yes | String | Unique ID to identify an employee within an organisation |
GET /api/v1/employees/{employeeId}/payrates/{payrateId}
Retrieve a specific payrate for an employee
Returns details of a particular payrate of an employee.
Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| employeeId | Yes | String | Unique ID to identify an employee within an organisation |
| payrateId | Yes | String | Unique ID to identify a payrate |
PUT /api/v1/employees/{employeeId}/payrates/{code}
Update a specific payrate for an employee
Update a particular payrate of an employee.
Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| divisor | Yes * | String | If an organisation specific divisor is associated, this field should contain the description of it. If not, a global divisor's name, e.g. "per hour", "per annum", "pa (Govt: 14/365th's)" or "pa (Aust: 12/313th's)". * divisor is mandatory when updating a organisation specific or global divisor. |
| rate | Yes * | String | Value of pay rate as entered in iPayroll. * rate is mandatory when updating a organisation specific or global divisor. |
| payScale | Yes ** | String | Pay Scales are designed to allow pay rates to be set up under a code that can then be used for multiple people. Displayed if Pay Scales are used and a Pay Scale is selected for employee, e.g. K1P107. ** payScale is mandatory when employee pay rate is associate with pay scales. |
Timesheets
A timesheet is a collection of all payments and deductions for a person paid in a single pay.
Attributes
| Name | Type | Description |
|---|---|---|
| id | String | Unique ID to identify a timesheet. This id is the same than the employeeId |
| employeeId | String | Unique ID to identify an employee within an organisation |
| daysInPeriod | Number | Number of days an employee has worked within the period of the timsheet. May be omitted, it is only relevant for organisations that have "record day on timesheet" option on |
| totalHours | Number | Total hours inside a timesheet |
| paidFromDate | Date | The start date of the pay period |
| paidToDate | Date | The end date of the pay period |
| message | String | A message to be appended to the employee payslip |
| transactions arrow_drop_downarrow_drop_up | JSON Object | List of timesheet transactions for the employee |
GET /api/v1/timesheets
Retrieve all of timesheets in the latest payroll
Returns all timesheets associated with the latest payroll of an organisation.
GET /api/v1/timesheets
Response Example
{
"content":[
{
"links": [
{
"rel": "self",
"href": "https://secure2.ipayroll.co.nz/api/v1/timesheets/123456"
}
],
"id": "123456",
"employeeId": "123456",
"totalHours": 40,
"paidToDate": "12-Nov-2016",
"paidFromDate": "04-Aug-2015",
"transactions": [
{
"links": [],
"timesheetTransactionId": 993590,
"amount": 0,
"quantity": 1,
"rate": 0,
"description": "BANK - Take Home Pay to BANK_NUMBER",
"costCentre": "",
"payElement": "BANK"
},
{
"links": [],
"timesheetTransactionId": 993589,
"amount": 0,
"quantity": 1,
"rate": 0,
"description": "WT - Withholding Tax to TAX_NUMBER",
"costCentre": "",
"payElement": "WT"
},
...
]
}
],
"links": [
{
"rel": "first",
"href": "https://secure2.ipayroll.co.nz/api/v1/timesheets?page=0&size=20"
},
{
"rel": "self",
"href": "https://secure2.ipayroll.co.nz/api/v1/timesheets"
},
{
"rel": "next",
"href": "https://secure2.ipayroll.co.nz/api/v1/timesheets?page=1&size=20"
},
{
"rel": "last",
"href": "https://secure2.ipayroll.co.nz/api/v1/timesheets?page=3&size=20"
}
],
"page": {
"size": 20,
"totalElements": 75,
"totalPages": 4,
"number": 0
}
}
GET /api/v1/timesheets/{timesheetId}
Retrieve an employee's latest timesheet
Returns the latest timesheet of an employee.
Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| timesheetId | Yes | String | Unique ID to identify a timesheet. employeeId can be used. |
GET /api/v1/timesheets/{timesheetId}
Response Example
{
{
"id": "123456",
"employeeId": "123456",
"totalHours": 40,
"paidToDate": "12-Nov-2016",
"paidFromDate": "04-Aug-2015",
"transactions": [
{
"links": [],
"timesheetTransactionId": 993590,
"amount": 0,
"quantity": 1,
"rate": 0,
"description": "BANK - Take Home Pay to BANK_NUMBER",
"costCentre": "",
"payElement": "BANK"
},
{
"links": [],
"timesheetTransactionId": 993589,
"amount": 0,
"quantity": 1,
"rate": 0,
"description": "WT - Withholding Tax to TAX_NUMBER",
"costCentre": "",
"payElement": "WT"
}
],
"links": [
{
"rel": "self",
"href": "https://secure2.ipayroll.co.nz/api/v1/timesheets/123456"
},
{
"rel": "employee",
"href": "https://secure2.ipayroll.co.nz/api/v1/employees/123456"
}
]
}
...
}
GET /api/v1/payrolls/{payrollId}/timesheets
Retrieve all of timesheets in the given payroll
Returns all timesheets associated with the given payroll of an organisation.
Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| payrollId | Yes | String | Unique ID to identify a payroll within an organisation |
GET /api/v1/payrolls/{payrollId}/timesheets
Response Example
{
"content":[
{
"links": [
{
"rel": "self",
"href": "https://secure2.ipayroll.co.nz/api/v1/payrolls/0030/timesheets"
}
],
"id": "123456",
"employeeId": "123456",
"totalHours": 40,
"paidToDate": "12-Nov-2016",
"paidFromDate": "04-Aug-2015",
"transactions": [
{
"links": [],
"timesheetTransactionId": 993590,
"amount": 0,
"quantity": 1,
"rate": 0,
"description": "BANK - Take Home Pay to BANK_NUMBER",
"costCentre": "",
"payElement": "BANK"
},
{
"links": [],
"timesheetTransactionId": 993589,
"amount": 0,
"quantity": 1,
"rate": 0,
"description": "WT - Withholding Tax to TAX_NUMBER",
"costCentre": "",
"payElement": "WT"
},
...
]
}
],
"links": [
{
"rel": "first",
"href": "https://secure2.ipayroll.co.nz/api/v1/payrolls/0030/timesheets?page=0&size=20"
},
{
"rel": "self",
"href": "https://secure2.ipayroll.co.nz/api/v1/payrolls/0030/timesheets"
},
{
"rel": "next",
"href": "https://secure2.ipayroll.co.nz/api/v1/payrolls/0030/timesheets?page=1&size=20"
},
{
"rel": "last",
"href": "https://secure2.ipayroll.co.nz/api/v1/payrolls/0030/timesheets?page=3&size=20"
}
],
"page": {
"size": 20,
"totalElements": 75,
"totalPages": 4,
"number": 0
}
}
GET /api/v1/payrolls/current/timesheets
Retrieve all of timesheets in the current payroll
Returns all timesheets associated with the current payroll of an organisation.
GET /api/v1/payrolls/current/timesheets
Response Example
{
"content":[
{
"links": [
{
"rel": "self",
"href": "https://secure2.ipayroll.co.nz/api/v1/payrolls/0030/timesheets"
}
],
"id": "123456",
"employeeId": "123456",
"totalHours": 40,
"paidToDate": "12-Nov-2016",
"paidFromDate": "04-Aug-2015",
"transactions": [
{
"links": [],
"timesheetTransactionId": 993590,
"amount": 0,
"quantity": 1,
"rate": 0,
"description": "BANK - Take Home Pay to BANK_NUMBER",
"costCentre": "",
"payElement": "BANK"
},
{
"links": [],
"timesheetTransactionId": 993589,
"amount": 0,
"quantity": 1,
"rate": 0,
"description": "WT - Withholding Tax to TAX_NUMBER",
"costCentre": "",
"payElement": "WT"
},
...
]
}
],
"links": [
{
"rel": "first",
"href": "https://secure2.ipayroll.co.nz/api/v1/payrolls/0030/timesheets?page=0&size=20"
},
{
"rel": "self",
"href": "https://secure2.ipayroll.co.nz/api/v1/payrolls/0030/timesheets"
},
{
"rel": "next",
"href": "https://secure2.ipayroll.co.nz/api/v1/payrolls/0030/timesheets?page=1&size=20"
},
{
"rel": "last",
"href": "https://secure2.ipayroll.co.nz/api/v1/payrolls/0030/timesheets?page=3&size=20"
}
],
"page": {
"size": 20,
"totalElements": 75,
"totalPages": 4,
"number": 0
}
}
GET /api/v1/payrolls/{payrollId}/timesheets/{timesheetId}
Retrieve an employee's timesheet in the given payroll
Returns employee's timesheet associated with the given payroll of an organisation.
Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| payrollId | Yes | String | Unique ID to identify a payroll within an organisation |
| timesheetId | Yes | String | Unique ID to identify a timesheet. employeeId can be used. |
GET /api/v1/payrolls/{payrollId}/timesheets/{timesheetId}
Response Example
{
{
"id": "123456",
"employeeId": "123456",
"totalHours": 40,
"paidToDate": "12-Nov-2016",
"paidFromDate": "04-Aug-2015",
"transactions": [
{
"links": [],
"timesheetTransactionId": 993590,
"amount": 0,
"quantity": 1,
"rate": 0,
"description": "BANK - Take Home Pay to BANK_NUMBER",
"costCentre": "",
"payElement": "BANK"
},
{
"links": [],
"timesheetTransactionId": 993589,
"amount": 0,
"quantity": 1,
"rate": 0,
"description": "WT - Withholding Tax to TAX_NUMBER",
"costCentre": "",
"payElement": "WT"
}
],
"links": [
{
"rel": "self",
"href": "https://secure2.ipayroll.co.nz/api/v1/payrolls/0014/timesheets/123456"
},
{
"rel": "employee",
"href": "https://secure2.ipayroll.co.nz/api/v1/payrolls/0014/timesheets/123456"
}
]
}
...
}
GET /api/v1/payrolls/current/timesheets/{timesheetId}
Retrieve an employee's timesheet in the current payroll
Returns employee's timesheet associated with the current payroll of an organisation.
Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| timesheetId | Yes | String | Unique ID to identify a timesheet. employeeId can be used. |
GET /api/v1/payrolls/current/timesheets/{timesheetId}
Response Example
{
{
"id": "123456",
"employeeId": "123456",
"totalHours": 40,
"paidToDate": "12-Nov-2016",
"paidFromDate": "04-Aug-2015",
"transactions": [
{
"links": [],
"timesheetTransactionId": 993590,
"amount": 0,
"quantity": 1,
"rate": 0,
"description": "BANK - Take Home Pay to BANK_NUMBER",
"costCentre": "",
"payElement": "BANK"
},
{
"links": [],
"timesheetTransactionId": 993589,
"amount": 0,
"quantity": 1,
"rate": 0,
"description": "WT - Withholding Tax to TAX_NUMBER",
"costCentre": "",
"payElement": "WT"
}
],
"links": [
{
"rel": "self",
"href": "https://secure2.ipayroll.co.nz/api/v1/payrolls/0014/timesheets/123456"
},
{
"rel": "employee",
"href": "https://secure2.ipayroll.co.nz/api/v1/payrolls/0014/timesheets/123456"
}
]
}
...
}
POST /api/v1/timesheets
Create one or more timesheets
Create one or more timesheets in the current payroll of an organisation. If there's no open payroll found for the organisation, system will open a new payroll provided that all pre-conditiions for opening a payroll are met.
Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| timesheets arrow_drop_downarrow_drop_up | Yes | JSON Object | List of timesheets to be created |
POST /api/v1/timesheets
Request Body Example
[
{
"employeeId": "123456",
"transactions": [
{
"links": [],
"timesheetTransactionId": 993590,
"amount": 0,
"quantity": 1,
"rate": 0,
"description": "BANK - Take Home Pay to BANK_NUMBER",
"costCentre": "",
"payElement": "BANK"
},
{
"links": [],
"timesheetTransactionId": 993589,
"amount": 0,
"quantity": 1,
"rate": 0,
"description": "WT - Withholding Tax to TAX_NUMBER",
"costCentre": "",
"payElement": "WT"
},
...
],
"links": [
{
"rel": "self",
"href": "https://secure2.ipayroll.co.nz/api/v1/timesheets/123456"
},
{
"rel": "employee",
"href": "https://secure2.ipayroll.co.nz/api/v1/employees/123456"
}
]
}
...
]
Response Example
[
{
"id": "123456",
"employeeId": "123456",
"totalHours": 40,
"paidToDate": "12-Nov-2016",
"paidFromDate": "04-Aug-2015",
"transactions": [
{
"links": [],
"timesheetTransactionId": 993590,
"amount": 0,
"quantity": 1,
"rate": 0,
"description": "BANK - Take Home Pay to BANK_NUMBER",
"costCentre": "",
"payElement": "BANK"
},
{
"links": [],
"timesheetTransactionId": 993589,
"amount": 0,
"quantity": 1,
"rate": 0,
"description": "WT - Withholding Tax to TAX_NUMBER",
"costCentre": "",
"payElement": "WT"
},
...
],
"links": [
{
"rel": "self",
"href": "https://secure2.ipayroll.co.nz/api/v1/timesheets/123456"
},
{
"rel": "employee",
"href": "https://secure2.ipayroll.co.nz/api/v1/employees/123456"
}
]
}
...
]
DELETE /api/v1/timesheets/{timesheetId}/transactions/{timesheetTransactionId}
Delete a timesheet transaction in the current payroll of an organisation
The current payroll must be open.
Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| timesheetId | Yes | String | Unique ID to identify a timesheet. employeeId can be used. |
| timesheetTransactionId | Yes | Long | Unique ID to identify a timesheet transaction |
DELETE /api/v1/timesheets/{employeeId}/transactions/{timesheetTransactionId}
Empty response.
Leave Balances
Attributes
| Name | Type | Description |
|---|---|---|
| id | String | Unique ID to identify a leave balance |
| employeeId | String | Unique ID to identify an employee within an organisation |
| entitled | Number | The number of units given since records started |
| accrued | Number | Number of units accrued since last anniversary |
| taken | Number | The total number of units taken from the leave balance |
| balance | Number | The number of leave units remaining for an employee based on the following equation: Entitled + Accrued - Taken |
| nextAnniversaryDate | String | Next anniversary date |
| lastAnniversaryDate | String | Last anniversary date |
| leaveBalanceType arrow_drop_downarrow_drop_up | JSON Object | Leave Balance Type |
| approvedQuantity | Number | The number of outstanding leave request units already approved for an employee |
GET /api/v1/employees/{employeeId}/leaves/balances
Retrieve all of an employee's leave balances
Returns details of all leave balances associated with an employee.
Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| employeeId | Yes | String | Unique ID to identify an employee within an organisation |
GET /api/v1/employees/{employeeId}/leaves/balances
Response Example
{
"links": [
{
"rel": "self",
"href": "https://secure2.ipayroll.co.nz/api/v1/employees/1/leaves/balances"
}
],
"content": [
{
"links": [
{
"rel": "self",
"href": "https://secure2.ipayroll.co.nz/api/v1/employees/1/leaves/balances/ACC%20Leave"
},
{
"rel": "employee",
"href": "https://secure2.ipayroll.co.nz/api/v1/employees/1"
}
],
"id": "ACC Leave",
"employeeId": "1",
"entitled": 0,
"accrued": 0,
"taken": 8,
"balance": -8,
"leaveBalanceType": {
"leaveType": "ACC First Week",
"name": "ACC Leave",
"unit": "hours",
"organisationSpecific":false
},
"nextAnniversaryDate": "31-May-2017",
"lastAnniversaryDate": "31-May-2016",
"approvedQuantity": 1
},
...
],
"page": {
"size": 5,
"totalElements": 5,
"totalPages": 1,
"number": 0
}
}
GET /api/v1/employees/{employeeId}/leaves/balances/{leaveBalanceId}
Retrieve a specific leave balance for an employee
Returns details of a particular leave balance of an employee.
Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| employeeId | Yes | String | Unique ID to identify an employee within an organisation |
| leaveBalanceId | Yes | String | Unique ID to identify a leave balance |
GET /api/v1/employees/{employeeId}/leaves/balances/{leaveBalanceId}
Response Example
{
"links": [
{
"rel": "self",
"href": "secure2.ipayroll.co.nz/api/v1/employees/12345/leaves/ACC%20Leave"
},
{
"rel": "employee",
"href": "secure2.ipayroll.co.nz/api/v1/employees/12345"
}
],
"id": "ACC Leave",
"employeeId": "12345",
"entitled": 0,
"accrued": 0,
"taken": 8,
"balance": -8,
"leaveBalanceType": {
"leaveType": "ACC First Week",
"name": "ACC Leave",
"unit": "hours",
"organisationSpecific":false
},
"nextAnniversaryDate": "31-May-2017",
"lastAnniversaryDate": "31-May-2016",
"approvedQuantity": 1
}
Leave Requests
Attributes
| Name | Type | Description |
|---|---|---|
| id | Number | Unique ID to identify a request |
| employeeId | String | Unique ID to identify an employee within an organisation |
| hours | Number | Total number of hours of requested leave |
| days | Number | Total number of days of requested leave (applies if a leave balance is stored in days) |
| leaveFromDate | Date | First day of leave |
| leaveToDate | Date | Last day of leave |
| reason | String | Reason for leave |
| status | String |
Processing status of a leave request. The status can be one of the following:
|
| payElement | String | Code of pay element that is used to process the request in a payroll |
| payElementId | Number | Id of pay element |
| leaveBalanceType arrow_drop_downarrow_drop_up | JSON Object | Leave Balance Type |
| daysConsumed | Number | Days of leave request in closed, or closed in advance, payrolls |
| daysCurrent | Number | Days of leave request in open, debiting, or paid payrolls |
| daysRemaining | Number | Days of leave request not yet included in payroll |
| quantityConsumed | Number | Hours of leave request in closed, or closed in advance, payrolls |
| quantityCurrent | Number | Hours of leave request in open, debiting, or paid payrolls |
| quantityRemaining | Number | Hours of leave request not yet included in payroll |
| leaveInDays | Boolean | Is leave request in days |
GET /api/v1/leaves/requests
Retrieve All Leave Requests
Returns details of all leave requests associated with an organisation.
Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| status | No | String |
Processing status of a leave request. The status can be one of the following:
|
| leaveBalanceType | No | String | Name of a leave balance type, for example, "Annual Leave", "Sick Leave", "Alternative Holiday" |
Sample requests
GET /api/v1/leaves/requests?status=Pending&leaveBalanceType=Annual%20Leave
GET /api/v1/leaves/requests
GET /api/v1/leaves/requests?status=Approved
GET /api/v1/leaves/requests?status={status}&leaveBalanceType={leaveBalanceType}
Response Example
{
"links":[
{
"rel":"self",
"href":"https://secure2.ipayroll.co.nz/api/v1/leaves/requests?status=Approved&leaveBalanceType=Annual%20Leave"
}
],
"content":[
{
"links":[
{
"rel":"self",
"href":"https://secure2.ipayroll.co.nz/api/v1/leaves/requests/255"
},
{
"rel":"employee",
"href":"https://secure2.ipayroll.co.nz/api/v1/employees/1"
},
{
"rel":"pay element",
"href":"https://secure2.ipayroll.co.nz/api/v1/payelements/AALL"
}
],
"id":255,
"employeeId":"1",
"hours":32,
"leaveFromDate":"07-Mar-2017",
"leaveToDate":"10-Mar-2017",
"reason":"Annual Holidays Break",
"status":"Approved",
"payElement":"AALL",
"leaveBalanceType":{
"leaveType":"Annual",
"name":"Annual Leave",
"unit":"hours",
"organisationSpecific":false
},
"payElementId":777,
"daysConsumed":0,
"daysCurrent":0,
"daysRemaining":0,
"quantityConsumed":8,
"quantityCurrent":0,
"quantityRemaining":0,
"leaveInDays":false
}
],
"page":{
"size":20,
"totalElements":1,
"totalPages":1,
"number":0
}
}
GET /api/v1/leaves/requests/{leaveRequestId}
Retrieve details of a leave request
Returns a leave request.
Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| leaveRequestId | Yes | Number | Unique ID to identify a leave request |
GET /api/v1/leaves/requests/{leaveRequestId}
Response Example
{
"links":[
{
"rel":"self",
"href":"https://secure2.ipayroll.co.nz/api/v1/leaves/requests/255"
},
{
"rel":"employee",
"href":"https://secure2.ipayroll.co.nz/api/v1/employees/1"
},
{
"rel":"pay element",
"href":"https://secure2.ipayroll.co.nz/api/v1/payelements/AALL"
}
],
"id":255,
"employeeId":"1",
"hours":32,
"leaveFromDate":"02-Mar-2017",
"leaveToDate":"10-Mar-2017",
"reason":"Annual Holidays Break",
"status":"Approved",
"payElement":"AALL",
"leaveBalanceType":{
"leaveType":"Annual",
"name":"Annual Leave",
"unit":"hours",
"organisationSpecific":false
},
"payElementId":777,
"daysConsumed": 0,
"daysCurrent": 0,
"daysRemaining": 0,
"quantityConsumed": 8,
"quantityCurrent": 0,
"quantityRemaining": 0,
"leaveInDays": false
}
GET /api/v1/leaves/requests/current
Retrieve current leave requests
Returns details of current leave requests (with status ‘Pending’ or ‘Approved’) associated with an organisation.
GET /api/v1/leaves/requests/current
Response Example
{
"links":[
{
"rel":"self",
"href":"https://secure2.ipayroll.co.nz/api/v1/employees/1/leaves/requests/current"
}
],
"content":[
{
"links":[
{
"rel":"self",
"href":"https://secure2.ipayroll.co.nz/api/v1/leaves/requests/254"
},
{
"rel":"employee",
"href":"https://secure2.ipayroll.co.nz/api/v1/employees/1"
},
{
"rel":"pay element",
"href":"https://secure2.ipayroll.co.nz/api/v1/payelements/AAHH"
}
],
"id":254,
"employeeId":"1",
"hours":12,
"days":3,
"leaveFromDate":"09-Mar-2017",
"leaveToDate":"13-Mar-2017",
"reason":"Holidays",
"status":"Pending",
"payElement":"AAHH",
"leaveBalanceType":{
"leaveType":"Alternative Holiday",
"name":"Alternative Holiday",
"unit":"days",
"organisationSpecific":false
},
"payElementId":888,
"daysConsumed":0,
"daysCurrent":1,
"daysRemaining":0,
"quantityConsumed":0,
"quantityCurrent":0,
"quantityRemaining":0,
"leaveInDays":true
},
{
"links":[
{
"rel":"self",
"href":"https://secure2.ipayroll.co.nz/api/v1/leaves/requests/255"
},
{
"rel":"employee",
"href":"https://secure2.ipayroll.co.nz/api/v1/employees/1"
},
{
"rel":"pay element",
"href":"https://secure2.ipayroll.co.nz/api/v1/payelements/AALL"
}
],
"id":255,
"employeeId":"2",
"hours":24,
"leaveFromDate":"01-Feb-2017",
"leaveToDate":"03-Feb-2017",
"reason":"Annual Holidays Break",
"status":"Approved",
"payElement":"AALL",
"leaveBalanceType":{
"leaveType":"Annual",
"name":"Annual Leave",
"unit":"hours",
"organisationSpecific":false
},
"payElementId":777,
"daysConsumed":0,
"daysCurrent":0,
"daysRemaining":0,
"quantityConsumed":8,
"quantityCurrent":0,
"quantityRemaining":0,
"leaveInDays":false
}
],
"page":{
"size":20,
"totalElements":2,
"totalPages":1,
"number":0
}
}
GET /api/v1/employees/{employeeId}/leaves/requests
Retrieve all of an employee's leave requests
Returns details of all leave requests associated with an employee.
Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| employeeId | Yes | String | Unique ID to identify an employee within an organisation |
| status | No | String |
Processing status of a leave request. The status can be one of the following:
|
GET /api/v1/employees/{employeeId}/leaves/requests?status={status}
Response Example
{
"links":[
{
"rel":"self",
"href":"https://secure2.ipayroll.co.nz/api/v1/employees/1/leaves/requests?status=Pending"
}
],
"content":[
{
"links":[
{
"rel":"self",
"href":"https://secure2.ipayroll.co.nz/api/v1/leaves/requests/254"
},
{
"rel":"employee",
"href":"https://secure2.ipayroll.co.nz/api/v1/employees/1"
},
{
"rel":"pay element",
"href":"https://secure2.ipayroll.co.nz/api/v1/payelements/AAHH"
}
],
"id":254,
"employeeId":"1",
"hours":12,
"days":3,
"leaveFromDate":"09-Mar-2017",
"leaveToDate":"13-Mar-2017",
"reason":"Holidays",
"status":"Pending",
"payElement":"AAHH",
"leaveBalanceType":{
"leaveType":"Alternative Holiday",
"name":"Alternative Holiday",
"unit":"days",
"organisationSpecific":false
},
"payElementId":888,
"daysConsumed":0,
"daysCurrent":1,
"daysRemaining":0,
"quantityConsumed":0,
"quantityCurrent":0,
"quantityRemaining":0,
"leaveInDays":true
}
],
"page":{
"size":20,
"totalElements":1,
"totalPages":1,
"number":0
}
}
GET /api/v1/employees/{employeeId}/leaves/requests/current
Retrieve current leave requests of an employee
Returns details of current leave requests (with status ‘Pending’ or ‘Approved’) associated with an employee.
Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| employeeId | Yes | String | Unique ID to identify an employee within an organisation |
GET /api/v1/employees/{employeeId}/leaves/requests/current
Response Example
{
"links":[
{
"rel":"self",
"href":"https://secure2.ipayroll.co.nz/api/v1/employees/1/leaves/requests/current"
}
],
"content":[
{
"links":[
{
"rel":"self",
"href":"https://secure2.ipayroll.co.nz/api/v1/leaves/requests/254"
},
{
"rel":"employee",
"href":"https://secure2.ipayroll.co.nz/api/v1/employees/1"
},
{
"rel":"pay element",
"href":"https://secure2.ipayroll.co.nz/api/v1/payelements/AAHH"
}
],
"id":254,
"employeeId":"1",
"hours":12,
"days":3,
"leaveFromDate":"09-Mar-2017",
"leaveToDate":"13-Mar-2017",
"reason":"Holidays",
"status":"Pending",
"payElement":"AAHH",
"leaveBalanceType":{
"leaveType":"Alternative Holiday",
"name":"Alternative Holiday",
"unit":"days",
"organisationSpecific":false
},
"payElementId":888,
"daysConsumed":0,
"daysCurrent":1,
"daysRemaining":0,
"quantityConsumed":0,
"quantityCurrent":0,
"quantityRemaining":0,
"leaveInDays":true
},
{
"links":[
{
"rel":"self",
"href":"https://secure2.ipayroll.co.nz/api/v1/leaves/requests/255"
},
{
"rel":"employee",
"href":"https://secure2.ipayroll.co.nz/api/v1/employees/1"
},
{
"rel":"pay element",
"href":"https://secure2.ipayroll.co.nz/api/v1/payelements/AALL"
}
],
"id":255,
"employeeId":"1",
"hours":32,
"leaveFromDate":"02-Mar-2017",
"leaveToDate":"10-Mar-2017",
"reason":"Annual Holidays Break",
"status":"Approved",
"payElement":"AALL",
"leaveBalanceType":{
"leaveType":"Annual",
"name":"Annual Leave",
"unit":"hours",
"organisationSpecific":false
},
"payElementId":777,
"daysConsumed":0,
"daysCurrent":0,
"daysRemaining":0,
"quantityConsumed":8,
"quantityCurrent":0,
"quantityRemaining":0,
"leaveInDays":false
}
],
"page":{
"size":20,
"totalElements":2,
"totalPages":1,
"number":0
}
}
GET /api/v1/employees/{employeeId}/leaves/requests/{requestId}
Retrieve details of a leave request associated with an employee.
Returns a leave request.
Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| employeeId | Yes | String | Unique ID to identify an employee within an organisation |
| requestId | Yes | Number | Unique ID to identify a leave request |
GET /api/v1/employees/{employeeId}/leaves/requests/{requestId}
Response Example
{
"links":[
{
"rel":"self",
"href":"http://secure2.ipayroll.co.nz/api/v1/employees/1/leaves/requests/255"
},
{
"rel":"employee",
"href":"http://secure2.ipayroll.co.nz/api/v1/employees/1"
}
],
"id": 255,
"employeeId":"1",
"hours":32,
"leaveFromDate":"02-Mar-2017",
"leaveToDate":"10-Mar-2017",
"reason":"Annual Holidays Break",
"status":"Approved",
"payElement":"Annual Leave",
"leaveBalanceType":{
"leaveType":"Annual",
"name":"Annual Leave",
"unit":"hours",
"organisationSpecific":false
},
"payElementId":50,
"daysConsumed":0,
"daysCurrent":0,
"daysRemaining":0,
"quantityConsumed":8,
"quantityCurrent":0,
"quantityRemaining":0,
"leaveInDays":false
}
POST /api/v1/leaves/requests
Create a Leave Request
Create a Leave Request for an employee.
Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| employeeId | Yes | String | Unique ID to identify an employee within an organisation |
| hours | Yes * | Number | Total number of hours of requested leave. * hours is not mandatory in case that the employee is defined as ADP and the payElement's Leave Balance saved in days e.g Sick, Bereavement |
| days | Yes ** | Number | Total number of days of requested leave (applies if a leave balance is stored in days) ** days is not mandatory for payElement whose Leave Balance saved in hours e.g Annual, Lieu |
| leaveFromDate | Yes | Date | First day of leave |
| leaveToDate | Yes | Date | Last day of leave |
| reason | No | String | Reason for leave |
| status | Yes | String |
Processing status of a leave request. The status can be one of the following:
|
| payElement | Yes | String | Code of pay element that is used to process the request in a payroll |
In case of ADP hours or days will be considered based on the payElement's Leave Balance
POST /api/v1/leaves/requests
Request Body Example
{
"employeeId":"5111",
"hours":"7",
"days":"1",
"leaveFromDate":"02-Aug-2017",
"leaveToDate":"02-Aug-2017",
"reason":"My Birthday",
"status":"Approved",
"payElement":"AALL"
}
Response Example
{
"id":9010,
"employeeId":"5111",
"hours":7,
"leaveFromDate":"02-Aug-2017",
"leaveToDate":"02-Aug-2017",
"reason":"My Birthday",
"status":"Approved",
"payElement":"AALL",
"leaveBalanceType":{
"leaveType":"Annual",
"name":"Annual Leave",
"unit":"hours",
"organisationSpecific":false
},
"payElementId":777,
"daysConsumed": 0,
"daysCurrent": 1,
"daysRemaining": 0,
"quantityConsumed": 0,
"quantityCurrent": 0,
"quantityRemaining": 0,
"leaveInDays": true,
"links":[
{
"rel":"self",
"href":"https://secure2.ipayroll.co.nz/api/v1/leaves/requests/9010"
},
{
"rel":"employee",
"href":"https://secure2.ipayroll.co.nz/api/v1/employees/5111"
},
{
"rel":"pay element",
"href":"https://secure2.ipayroll.co.nz/api/v1/payelements/AALL"
}
]
}
PUT /api/v1/leaves/requests/{requestId}
Update a Leave Request
Update a Leave Request for an employee.
Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| employeeId | Yes | String | Unique ID to identify an employee within an organisation |
| hours | Yes * | Number | Total number of hours of requested leave. * hours is not mandatory in case that the employee is defined as ADP and the payElement's Leave Balance saved in days e.g Sick, Bereavement |
| days | Yes ** | Number | Total number of days of requested leave (applies if a leave balance is stored in days) ** days is not mandatory for payElement whose Leave Balance saved in hours e.g Annual, Lieu |
| leaveFromDate | Yes | Date | First day of leave |
| leaveToDate | Yes | Date | Last day of leave |
| reason | No | String | Reason for leave |
| status | Yes | String |
Processing status of a leave request. The status can be one of the following:
|
| payElement | Yes | String | Code of pay element that is used to process the request in a payroll |
In case of ADP hours or days will be considered based on the payElement's Leave Balance
PUT /api/v1/leaves/requests/{requestId}
Request Body Example
{
"employeeId":"5111",
"hours":"7",
"days":"1",
"leaveFromDate":"02-Aug-2017",
"leaveToDate":"02-Aug-2017",
"reason":"My Birthday",
"status":"Approved",
"payElement":"AALL"
}
Response Example
{
"id":9010,
"employeeId":"5111",
"hours":7,
"leaveFromDate":"02-Aug-2017",
"leaveToDate":"02-Aug-2017",
"reason":"My Birthday",
"status":"Approved",
"payElement":"AALL",
"leaveBalanceType":{
"leaveType":"Annual",
"name":"Annual Leave",
"unit":"hours",
"organisationSpecific":false
},
"payElementId":777,
"daysConsumed": 0,
"daysCurrent": 1,
"daysRemaining": 0,
"quantityConsumed": 0,
"quantityCurrent": 0,
"quantityRemaining": 0,
"leaveInDays": true,
"links":[
{
"rel":"self",
"href":"https://secure2.ipayroll.co.nz/api/v1/leaves/requests/9010"
},
{
"rel":"employee",
"href":"https://secure2.ipayroll.co.nz/api/v1/employees/5111"
},
{
"rel":"pay element",
"href":"https://secure2.ipayroll.co.nz/api/v1/payelements/AALL"
}
]
}
Payslips
Attributes
| Name | Type | Description |
|---|---|---|
| id | Number | Unique ID to identify a payslip |
| totalPayments | Number | Gross payment for the period |
| overpayment | Number | Indicates recovery of money in this payroll (might have been caused by overpayment in a previous payroll) |
| taxCredit | Number | Tax credited for donations made |
| yearToDateTotals | Map | A map containing year-to-date totals as value (Number) for various pay elements as key (String) |
| nettPay | Number | Nett payment |
| payslipMessage | String | Organisation specific payslip message |
| abn | String | The Australia Business Number (only applicable to Australian organisations). This field would not be there for non-Australian organisations. |
| payroll arrow_drop_downarrow_drop_up | JSON Object | Payroll that this payslip belongs to |
| payments arrow_drop_downarrow_drop_up | JSON Object | Details of payments included in the payslip |
| deductions arrow_drop_downarrow_drop_up | JSON Object | Details of deductions included in the payslip |
| otherBenefits arrow_drop_downarrow_drop_up | JSON Object | Details of other benefits included in the payslip |
| leaveBalances arrow_drop_downarrow_drop_up | JSON Object | Details of leave balances (as of payroll time) |
| timesheet arrow_drop_downarrow_drop_up | JSON Object | The timesheet associated with the payslip |
GET /api/v1/payrolls/current/payslips
Retrieve all payslips in the latest payroll
Returns all payslips generated in the latest pay run.
GET /api/v1/payrolls/current/payslips
Response Example
{
"links": [
{
"rel": "self",
"href": "https://secure2.ipayroll.co.nz/api/v1/payrolls/current/payslips"
}
],
"content": [
{
"links": [
{
"rel": "self",
"href": "https://secure2.ipayroll.co.nz/api/v1/payslips/0040/employees/101"
},
{
"rel": "employee",
"href": "https://secure2.ipayroll.co.nz/api/v1/employees/101"
}
],
"totalPayments": -254.35,
"deductions": [
{
"amount": -320.07,
"quantity": 1,
"description": "PAYE (Tax Code M) to 013-166-374",
"notes": "",
"displayPayslipQuantity": ""
},
{
"amount": -43.15,
"quantity": 3,
"description": "KiwiSaver",
"displayPayslipQuantity": "3.00%"
},
{
"amount": -1008.59,
"description": "Take Home Pay to 06-0902-0068389-02"
}
],
"id":"0040",
"otherBenefits": [],
"yearToDateTotals": {
"Taxable Earnings": 2272.49,
"PAYE": 662.47
},
"leaveBalances": [
{
"balanceName": "Annual Leave",
"hours": 229,
"days": 28.5
}
],
"timesheet": {
"links": [
{
"rel": "self",
"href": "https://secure2.ipayroll.co.nz/api/v1/timesheets/101/payrolls/0040"
}
],
"employeeId": "101",
"totalHours": -9.16,
"transactions": [
{
"timesheetTransactionId": 1130873,
"amount": -254.35,
"quantity": -9.16,
"rate": 27.7675,
"description": "SICK - Sick Leave (01-Nov-2016 to 02-Nov-2016)",
"costCentre": "new",
"leaveFrom": "01-Nov-2016",
"leaveTo": "02-Nov-2016",
"leaveDays": "-0.9200",
"payElement": "SICK"
}
],
"paidToDate": "12-Nov-2016",
"paidFromDate": "04-Aug-2015"
},
"payments": [
{
"description": "Sick Leave (01-Nov-2016 to 02-Nov-2016) -0.92 days @ $27.7675",
"quantity": -9.16,
"amount": -254.35,
"notes": ""
}
],
"nettPay": 0,
"payroll": {
"payrollNumber": "0040",
"payDate": "25-Nov-2016"
},
"payslipMessage": "My Best Wishes for Your Partners"
},
...
],
"page": {
"size": 5,
"totalElements": 5,
"totalPages": 1,
"number": 0
}
}
GET /api/v1/payrolls/current/payslips/{payslipId}
Retrieve a single employee's payslip in the latest payroll
Returns payslip of the specified employee.
Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| payslipId | Yes | String | Unique ID to identify an payslip within an organisation |
GET /api/v1/payrolls/current/payslips/{payslipId}
Response Example
{
"links": [
{
"rel": "self",
"href": "https://secure2.ipayroll.co.nz/api/v1/payrolls/current/payslips/101"
},
{
"rel": "employee",
"href": "https://secure2.ipayroll.co.nz/api/v1/employees/101"
}
],
"id":"101"
"totalPayments": -254.35,
"deductions": [
{
"amount": -320.07,
"quantity": 1,
"description": "PAYE (Tax Code M) to 013-166-374",
"notes": "",
"displayPayslipQuantity": ""
},
{
"amount": -43.15,
"quantity": 3,
"description": "KiwiSaver",
"displayPayslipQuantity": "3.00%"
},
{
"amount": -1008.59,
"description": "Take Home Pay to 06-0902-0068389-02"
}
],
"otherBenefits": [],
"yearToDateTotals": {
"Taxable Earnings": 2272.49,
"PAYE": 662.47
},
"leaveBalances": [
{
"balanceName": "Annual Leave",
"hours": 229,
"days": 28.5
}
],
"timesheet": {
"links": [
{
"rel": "self",
"href": "https://secure2.ipayroll.co.nz/api/v1/timesheets/101/payrolls/0040"
}
],
"employeeId": "101",
"totalHours": -9.16,
"transactions": [
{
"timesheetTransactionId": 1130873,
"amount": -254.35,
"quantity": -9.16,
"rate": 27.7675,
"description": "SICK - Sick Leave (01-Nov-2016 to 02-Nov-2016)",
"costCentre": "new",
"leaveFrom": "01-Nov-2016",
"leaveTo": "02-Nov-2016",
"leaveDays": "-0.9200",
"payElement": "SICK"
}
],
"paidToDate": "12-Nov-2016",
"paidFromDate": "04-Aug-2015"
},
"payments": [
{
"description": "Sick Leave (01-Nov-2016 to 02-Nov-2016) -0.92 days @ $27.7675",
"quantity": -9.16,
"amount": -254.35,
"notes": ""
}
],
"nettPay": 0,
"payroll": {
"payrollNumber": "0040",
"payDate": "25-Nov-2016"
},
"payslipMessage": "Best Wishes!"
}
GET /api/v1/payrolls/{payrollId}/payslips
Retrieve all payslips in a specific payroll
Returns all payslips associated with the specified payroll.
Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| payrollId | Yes | String | Unique identifier of the payroll |
GET /api/v1/payrolls/{payrollId}/payslips
Response Example
{
"links": [
{
"rel": "self",
"href": "https://secure2.ipayroll.co.nz/api/v1/payrolls/0400/payslips"
}
],
"content": [
{
"links": [
{
"rel": "self",
"href": "https://secure2.ipayroll.co.nz/api/v1/payslips/0040/employees/101"
},
{
"rel": "employee",
"href": "https://secure2.ipayroll.co.nz/api/v1/employees/101"
}
],
"id": "101",
"totalPayments": -254.35,
"deductions": [
{
"amount": -320.07,
"quantity": 1,
"description": "PAYE (Tax Code M) to 013-166-374",
"notes": "",
"displayPayslipQuantity": ""
},
{
"amount": -43.15,
"quantity": 3,
"description": "KiwiSaver",
"displayPayslipQuantity": "3.00%"
},
{
"amount": -1008.59,
"description": "Take Home Pay to 06-0902-0068389-02"
}
],
"otherBenefits": [],
"yearToDateTotals": {
"Taxable Earnings": 2272.49,
"PAYE": 662.47
},
"leaveBalances": [
{
"balanceName": "Annual Leave",
"hours": 229,
"days": 28.5
}
],
"timesheet": {
"links": [
{
"rel": "self",
"href": "https://secure2.ipayroll.co.nz/api/v1/timesheets/101/payrolls/0040"
}
],
"employeeId": "101",
"totalHours": -9.16,
"transactions": [
{
"timesheetTransactionId": 1130873,
"amount": -254.35,
"quantity": -9.16,
"rate": 27.7675,
"description": "SICK - Sick Leave (01-Nov-2016 to 02-Nov-2016)",
"costCentre": "new",
"leaveFrom": "01-Nov-2016",
"leaveTo": "02-Nov-2016",
"leaveDays": "-0.9200",
"payElement": "SICK"
}
],
"paidToDate": "12-Nov-2016",
"paidFromDate": "04-Aug-2015"
},
"payments": [
{
"description": "Sick Leave (01-Nov-2016 to 02-Nov-2016) -0.92 days @ $27.7675",
"quantity": -9.16,
"amount": -254.35,
"notes": ""
}
],
"nettPay": 0,
"payroll": {
"payrollNumber": "0040",
"payDate": "25-Nov-2016"
},
"payslipMessage": "My Best Wishes for Your Partners"
},
...
],
"page": {
"size": 5,
"totalElements": 5,
"totalPages": 1,
"number": 0
}
}
GET /api/v1/payrolls/{payrollId}/payslips/{payslipId}
Retrieve specific employee's payslip in a specific payroll
Returns specified employee's payslip in the specified payroll.
Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| payrollId | Yes | String | Unique identifier of the payroll |
| payslipId | Yes | String | Unique identifier of the employee |
GET /api/v1/payrolls/{payrollId}/payslips/{payslipId}
Response Example
{
"links": [
{
"rel": "self",
"href": "https://secure2.ipayroll.co.nz/api/v1/payrolls/0040/payslips/101"
},
{
"rel": "employee",
"href": "https://secure2.ipayroll.co.nz/api/v1/employees/101"
}
],
"id": "101",
"totalPayments": -254.35,
"deductions": [
{
"amount": -320.07,
"quantity": 1,
"description": "PAYE (Tax Code M) to 013-166-374",
"notes": "",
"displayPayslipQuantity": ""
},
{
"amount": -43.15,
"quantity": 3,
"description": "KiwiSaver",
"displayPayslipQuantity": "3.00%"
},
{
"amount": -1008.59,
"description": "Take Home Pay to 06-0902-0068389-02"
}
],
"otherBenefits": [],
"yearToDateTotals": {
"Taxable Earnings": 2272.49,
"PAYE": 662.47
},
"leaveBalances": [
{
"balanceName": "Annual Leave",
"hours": 229,
"days": 28.5
}
],
"timesheet": {
"links": [
{
"rel": "self",
"href": "https://secure2.ipayroll.co.nz/api/v1/timesheets/101/payrolls/0040"
}
],
"employeeId": "101",
"totalHours": -9.16,
"transactions": [
{
"timesheetTransactionId": 1130873,
"amount": -254.35,
"quantity": -9.16,
"rate": 27.7675,
"description": "SICK - Sick Leave (01-Nov-2016 to 02-Nov-2016)",
"costCentre": "new",
"leaveFrom": "01-Nov-2016",
"leaveTo": "02-Nov-2016",
"leaveDays": "-0.9200",
"payElement": "SICK"
}
],
"paidToDate": "12-Nov-2016",
"paidFromDate": "04-Aug-2015"
},
"payments": [
{
"description": "Sick Leave (01-Nov-2016 to 02-Nov-2016) -0.92 days @ $27.7675",
"quantity": -9.16,
"amount": -254.35,
"notes": ""
}
],
"nettPay": 0,
"payroll": {
"payrollNumber": "0040",
"payDate": "25-Nov-2016"
},
"payslipMessage": "My Best Wishes for Your Partners"
}
Pay Element
A Pay Element defines the rules used to calculate transactions. Pay elements form the basis of transactions for Payments, Deductions and Leave. Pay elements are divided into Standard Pay elements (shared across all organisations) and specific - which are defined for and by a specific organisation.
Attributes
| Name | Type | Description |
|---|---|---|
| id | String | Unique ID to identify a pay element |
| code | String | Element code. This is unique for standard pay elements and unique within an organisation for the specific ones. |
| description | String | Free-form description of the pay element |
| displayValue | String | The on screen value for the Pay element. This is the same as code for most pay elements |
| calculationRule | String | Code for the calculation rule used with the pay element. Different rules apply to different types of pay element |
| group | String | The pay element group. Possible values are Payment, Deduction and Leave |
| type | String | Pay element type within its group |
| multiplier | Number | The multiplier used in rate calculations |
| expired | Boolean | Whether this pay element is active or inactive (expired) |
| accLevyLiable | Boolean | New Zealand only. True if the pay element is ACC levy liable |
| superableEarning | Boolean | True if the pay element is Superable Earning type |
| holidayPayLiable | String | New Zealand only. True if the pay element is holiday pay liable |
| notKiwiSaverLiable | Boolean | New Zealand only. True if the pay element is not kiwi saver liable |
| payrollTaxLiable | Boolean | Australia only. True if the pay element is payroll tax liable |
| rdoLiable | Boolean | Australia only. True if the pay element is rdo liable |
| lslLiable | Boolean | Australia only. True if the pay element is ls liable |
| casLiable | Boolean | Australia only. True if the pay element is cas liable |
| reducing | Boolean | True if the pay element is reducing |
| payableOnFinalPay | Boolean | True if the pay element is payable on final pay |
| itemisedOnPaymentSummary | Boolean | Australia only. True if the pay element is itemised on payment summary |
| allowPartialDeduction | Boolean | True if the pay element allows partitial deduction |
| consolidateTransactions | Boolean | True if the pay element applies consolidate transactions |
| payeeReference | String | Payee Reference |
| payeeCode | String | Payee code |
| bankAccountNumber | String | New Zealand only Bank account of the deduction by the pay element |
| bsbAccountNumber | String | Australia only The bsb account number of the deduction by the pay element |
| reduceSuperable | String | True if the pay element reduces superable |
| priority | Number | Pay element priority |
| costCentresRule | String | The rule applied to discern the pay element's cost centre |
| paymentMethod | String | Payment method |
| payeeParticulars | String | Payee particulars |
| doneeAddress | String | Donee address |
| doneeName | String | Donee name |
| unusedLeavePayment | Boolean | True if the pay element is an unused leave payment |
| employmentTerminationPayment | Boolean | Australia only True if the pay element is an employment termination payment |
| employmentTerminationPaymentNoLumpD | Boolean | Australia only True if the pay element is an employment termination payment with no LumpD |
| availableForLeaveRequest | Boolean | True if the pay element is available for leave request |
| leaveTaxType | String | Tax type of the leave |
| paymentGroup | String | Payment group of the pay element |
| calculationAccumulator | String | The name of the calculation accumulator for the pay element |
| debitCostCentreRule | String | The name of the debit cost centre rule |
| excessRedundancy | String | The pay element is Employment Termination Payment (ETP) exclueded or not |
| derivedFrom | String | If the pay element is defined by the organisation, the value will be "organisation". Otherwise, the value is "system" |
| customField | String | The name of the custom field for the pay element |
| rates arrow_drop_downarrow_drop_up | JSON Object | List of rates for the pay element |
| rules arrow_drop_downarrow_drop_up | JSON Object | List of rules for leave entitlement |
| leaveBalanceType arrow_drop_downarrow_drop_up | JSON Object | Leave Balance Type |
GET /api/v1/payelements
Retrieve All Pay Elements
Returns all the pay elements of an organisation.
GET /api/v1/payelements/{id}
Retrieve A Pay Element
Returns a particular pay element of the organisation, identified by pay element code.
Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| id | Yes | String | Unique ID to identify a pay element. |
Custom Fields
A custom field conains extra details relating to an employee. These details are not part of the core iPayroll application, and may not be in regular use by all organisations.
iPayroll offers some special, pre-configured custom fields such as Contact, Contract, Position, Renumeration and Leave.
The fields in the response change dynamically depending upon the category of of the custom field.
Attributes
| Name | Type | Description |
|---|---|---|
| id | String | Unique ID to identify a custom field. |
| category | Long | The category id of the custom field. |
| categoryName | String | The category name of the custom field. |
| customFieldId | Long | The id for this custom field. |
| name | String | Name of the custom field. |
| date | Date | Date the custom field was added to the employee. |
| description | String | Description of the custom field (if blank this will default to the name). |
| contactDetails | String | Contact Only.Contact's full name. |
| relationship | String | Contact Only.Relationship of contact to the employee. |
| phoneNumber | String | Contact Only.Phone number of contact. |
| String | Contact Only.Email address of contact. | |
| Address | String | Contact Only.Address of contact. |
| contractHours | Number | Contract only. Hours for the contract. |
| periodDays | Number | Contract only. The period in days for the contract. |
| contractEnd | String | Contract only. Contract end date. |
| fte | Number | Position only. Full Time Equivalent for the position. |
| hayPoints | Integer | Position only. Hay points for the position. |
| hayProfile | Number | Position only. Hay profile for the position. |
| finish | String | Position only. Date String for the position's finish date. |
| start | String | Position only. Date String for the position's start date. |
| reportsFrom | String | Position only. List of people reporting to the position (will not display if none exist). |
| reportsTo | String | Position only. Who the position reports to. |
| renumerationType | String | Remuneration only. The type of renumeration. |
| annualBenefit | String | Remuneration only. The formatted annual benefit. |
GET /api/v1/employees/{employee id}/customfields
Retrieve All Custom Fields For Employee
Returns all the custom fields including values for an employee.
GET /api/v1/employees/{employee id}/customfields/{category id}
Retrieve All Custom Fields of a Single Category for an Employee
Returns all the custom fields including values of the specified category id for an employee.
Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| category id | Yes | Long | The id of the category for which to retrieve the custom fields values. |
GET /api/v1/employees/{employeeId}/customfields/{categoryId}/{id}
Retrieve A Custom Field
Returns a specific custom field from the employee based on its id number and category.
Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| category | Yes | Long | The id of the custom field category. |
| id | Yes | Long | The id of the custom field. |
Payrolls
Attributes
| Name | Type | Description |
|---|---|---|
| payrollNumber | String | Payroll Number. |
| id | String | Same as Payroll Number. |
| payDate | String | The date that people can access their pay. |
| message | String | Payroll message. |
| status | String | Status of the payroll. |
| status | String |
Status of the payroll. The status can be one of the following:
|
| payrollType | String |
Type of the payroll. The payroll type can be one of the following:
|
| payFrequencies arrow_drop_downarrow_drop_up | JSON Array | A JSON array representing the Pay Frequencies. |
GET /api/v1/payrolls
Retrieve List of payrolls
Returns a list of payrolls of an organisation.
GET /api/v1/payrolls/{payrollId}
Retrieve a one payroll
Returns a particular payroll of an organisation.
GET /api/v1/payrolls/current
Retrieve current payroll
Returns the current payroll of an organisation.
Leave Balance Types
Attributes
| Name | Type | Description |
|---|---|---|
| leaveType | String | Leave Balance Type |
| name | String | The name used to identify the leave balance type. The name may be defined by the user or the system |
| unit | String | The unit used for entitled, accrued, taken and balance. e.g. "days", "hours" and "$" |
| organisationSpecific | Boolean | True if leave balance name is a special leave balance specific to organisation |
GET /api/v1/leavebalancetypes
Retrieve All Leave Balance Types
Returns all the leave balance types of an organisation.
Employee Superannuation
This is only used in Australian organisations so is only applicable to Cloudpayroll.
Attributes
| Name | Type | Description |
|---|---|---|
| amount | Number | Amount of transaction. Only used for Member Voluntary, Super Sacrifice and Reportable Superannuation Contribution type pay elements. |
| costCentre | String | Cost centre of the transaction. Only required to overide the default cost centre. |
| id | String | The id of the transaction. |
| payElement | String | They super pay element. |
| quantity | Number | Quantity of the transaction. |
| superannMemberNumber | String | The superannuation member number for the transaction |
| superFundIdentifier | String | Identifier for the superfund. |
GET /api/v1/employees/{employeeId}/superannuation
Retrieve All Employee Superannuation Transactions
Returns all the superannuation transactions for an employee.
| Name | Required | Type | Description |
|---|---|---|---|
| employeeId | Yes | String | Unique ID to identify an employee within an organisation |
POST /api/v1/employees/{employeeId}/superannuation
Create Employee Superannuation Transaction
Creates a superannuation transaction for an employee.
| Name | Required | Type | Description |
|---|---|---|---|
| amount | Yes* | Number | Amount of transaction. Only used for Member Voluntary, Super Sacrifice and Reportable Superannuation Contribution type pay elements. |
| costCentre | No | String | Cost centre of the transaction. Only required to overide the default cost centre. |
| payElement | No | String | They super pay element. |
| quantity | Yes | Number | Quantity of the transaction. |
| superannMemberNumber | No | String | The superannuation member number for the transaction |
| superFundIdentifier | No | String | Identifier for the superfund. |
GET /api/v1/employees/{employeeId}/superannuation/{transactionId}
Retrieve An Employee Superannuation Transaction
Returns a specific superannuation transactions for an employee.
| Name | Required | Type | Description |
|---|---|---|---|
| employeeId | Yes | String | Unique ID to identify an employee within an organisation. |
| transactionId | Yes | String | Unique ID to identify a transaction for an employee. |
PUT /api/v1/employees/{employeeId}/superannuation/{transactionId}
Update Employee Superannuation Transaction
Updates a specific superannuation transaction for an employee.
| Name | Required | Type | Description |
|---|---|---|---|
| amount | No | Number | Amount of transaction. Only used for Member Voluntary, Super Sacrifice and Reportable Superannuation Contribution type pay elements. |
| costCentre | No | String | Cost centre of the transaction. Only required to overide the default cost centre. |
| payElement | No | String | They super pay element. |
| quantity | No | Number | Quantity of the transaction. |
| superannMemberNumber | No | String | The superannuation member number for the transaction |
| superFundIdentifier | No | String | Identifier for the superfund. |
DELETE /api/v1/employees/{employeeId}/superannuation/{transactionId}
Delete Employee Superannuation Transaction
Delete a specific superannuation transaction for an employee.
Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| employeeId | Yes | String | Unique ID to identify an employee within an organisation. |
| transactionId | Yes | String | Unique ID to identify a transaction for an employee |