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
Functionality includes, but is not limited to:
- Get, create, update employees
- Get and update pay rates for an employee
- Get custom fields for an employee
- Get payslips
- Get all leave balances or a specific leave balance for an employee
- Get, create and update leave requests
- Get, create, update or delete parental leave (NZ only)
- Get timesheets for the latest payroll, a specific payroll, or the currently open payroll for all or a specific employee
- Create or delete timesheets
- Get and create cost centres
- Get pay elements
- Get a list of payrolls, the current open payroll or a specific payroll
- Get leave balance types
- Get custom fields
- Get, create, update and delete employee superannuation transactions (AU only)
- Get user defined groups
- Get general ledger entries by payroll or by date range
For a full list of requests, see Resources.
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)
- Parental Leave (parentalleaves) - NZ only
- Payslips (payslips)
- Pay Elements (payelements)
- Payrolls (payrolls)
- General Ledger (generalledger)
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 demo:
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 the 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://demo.ipayroll.co.nz - This is the test environment used when developing and testing your applications.
https://secure2.ipayroll.co.nz - This is the live production system.
Remember: Those environments require the 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 an HTTP header or as a request parameter.
We provide a detailed authentication and authorisation guide in the Authentication 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 |
| Boolean | Flag indicating either "true" or "false" | true |
| JSON Object | JavaScript Object Notation | {"foo" : "bar"} |
| String Array | An array of strings | [ "string 1", "string 2" ] |
Retrieving Resources with HTTP GET
Your application may retrieve a representation of a resource by GETting the correct URLs. Successful GET requests to 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
- yyyy/MM/dd
- yyyy/MMM/dd
- dd MMMM yyyy
- dd MMMM yy
- dd/MM (this will assume the current year)
- dd/MMM (this will assume the current year)
The API returns dd-MMM-yyyy format in responses.
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 pay rate and timeshseet endpoints.
{
"links": [
{
"rel": "self",
"href": "https://demo.ipayroll.co.nz/api/v1/employees/1"
},
{
"rel": "payrate",
"href": "https://demo.ipayroll.co.nz/api/v1/employees/1/payrates"
},
{
"rel": "timesheet",
"href": "https://demo.ipayroll.co.nz/api/v1/timesheets/1"
}
],
"surname": "White",
"firstNames": "Jason",
"employeeId": "1",
...rest of the properties...
}
Pagination
Some of the endpoints 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 these type of requests and will default to returning 20 elements per page.
{
"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://demo.ipayroll.co.nz/api/v1/employees?size=5 https://demo.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://demo.ipayroll.co.nz/api/v1/employees?page=0&size=5"
},
{
"rel": "self",
"href": "https://demo.ipayroll.co.nz/api/v1/employees?size=5"
},
{
"rel": "next",
"href": "https://demo.ipayroll.co.nz/api/v1/employees?page=1&size=5"
},
{
"rel": "last",
"href": "https://demo.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 |
| 409 | CONFLICT | Already exists or an update currently running prevents the request from being actioned |
| 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.
Note: If Xero Tracking Categories are used, the chart of account code and each tracking category must be split by a pipe, for example, "477|Sales|Wellington".
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
(Scope: costcentres)
Returns all the cost centres of an organisation.
GET /api/v1/costcentres/{costcentreId}
Retrieve a cost centre
(Scope: costcentres)
Returns a particular cost centre of the organisation, identified by cost centre id.
Path Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| costcentreId | Yes | Integer | Unique ID to identify a cost centre |
POST /api/v1/costcentres
Create one or more cost centres
(Scope: costcentres)
Create one or more cost centres in an organisation.
Request Body Properties
| Name | Required | Type | Description |
|---|---|---|---|
| code | Yes | String | The name of the cost centre. Unique within an organisation. If Xero Tracking Categories are used, the chart of account code and each tracking category must be split by a pipe, e.g. "477|Sales|Wellington". |
| description | Yes | String | Cost centre description |
Employees
Attributes
| Name | Type | Description | ||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| id | String | Unique ID to identify an employee within an organisation. Limited to a-z, A-Z, 0-9, _ (underscore) and - (hyphen). |
||||||||||||||||||||||||||||||||||||
| 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 | NZ Male or Female or Gender Diverse. AU Male or Female or Intersex/Indeterminate or Not Stated. | ||||||||||||||||||||||||||||||||||||
| 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 | Preferred Name of the employee | ||||||||||||||||||||||||||||||||||||
| userDefinedGroup | String | User Defined Group of the employee - value expected is one of the group values defined for the organisation. When User Defined Groups are disabled for an organisation, this field is optional. Alternatively, the value ‘DEFAULT’ can be used whether User Defined Groups are enabled or not. |
||||||||||||||||||||||||||||||||||||
| 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. AU TFN is masked in all responses, for example, "*** *** 123" |
||||||||||||||||||||||||||||||||||||
| finishDate | String | Final Pay day of the employee | ||||||||||||||||||||||||||||||||||||
| terminationReason | String | AU only: Termination reason of the employee | ||||||||||||||||||||||||||||||||||||
| deathBenefitSurname | String | AU only: Death beneficiaries Surname | ||||||||||||||||||||||||||||||||||||
| deathBenefitFirstName | String | AU only: Death beneficiaries First Name | ||||||||||||||||||||||||||||||||||||
| deathBenefitRecipient | String | AU only: Death benefit recipient. Code and Description are supported.
|
||||||||||||||||||||||||||||||||||||
| taxCode | String | New Zealand Tax Code of the employee
|
||||||||||||||||||||||||||||||||||||
| taxScale | String | Australian Tax scale of the employee. Tax Scale if proprietorStatus is Employee or Labour Hire. Contractor Tax if proprietorStatus is Company/Contractor. Note: See Tax Scale table at end of the attributes list to determine when a tax code can be applied.
|
||||||||||||||||||||||||||||||||||||
| kiwiSaverRate | Number | Kiwisaver Employee Contribution rate of the employee | ||||||||||||||||||||||||||||||||||||
| employerSubsidy | Number | KiwiSaver employer contribution | ||||||||||||||||||||||||||||||||||||
| 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 | NZ: Special tax rate of the employee AU: Specified rate of the employee |
||||||||||||||||||||||||||||||||||||
| specialStudentLoan | Number | NZ only: Special Student Loan rates of the employee | ||||||||||||||||||||||||||||||||||||
| specialEarnerLevy | Number | NZ only: Special Earner Levy rate of the employee | ||||||||||||||||||||||||||||||||||||
| specialExtraPayRate | Number | NZ only: Special Extra Pay Rate of the employee | ||||||||||||||||||||||||||||||||||||
| hasDebt | Boolean | AU only: Higher Education Loan Program (HELP), VET Student Loan (VSL), Financial Supplement (FS), Student Start-up Loan (SSL) or Trade Support Loan (TSL) Debt | ||||||||||||||||||||||||||||||||||||
| helpDebt | Boolean | AU only: HELP Debt. This attribute is legacy as of 15-Nov-2021 and is replaced by hasDebt. | ||||||||||||||||||||||||||||||||||||
| sfssDebt | Boolean | AU only: SFSS Debt. This attribute is legacy as of 15-Nov-2021 and is replaced by hasDebt. | ||||||||||||||||||||||||||||||||||||
| medicareLevyVariationDeclaration | Boolean | AU only: Has the employee filled a Medicare levy variation declaration | ||||||||||||||||||||||||||||||||||||
| hasSpouse | Boolean | AU only: Spouse | ||||||||||||||||||||||||||||||||||||
| incomeLessThanRelevantAmount | Boolean | AU only: 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 | AU only: Payroll Tax Exempt | ||||||||||||||||||||||||||||||||||||
| dependentChildren | Number | AU only: Number of dependent children of the employee | ||||||||||||||||||||||||||||||||||||
| surchargeIncrease | Number | AU only: Surcharge increase | ||||||||||||||||||||||||||||||||||||
| employmentBasisType | String | AU only
|
||||||||||||||||||||||||||||||||||||
| residenceType | String | AU only: Mandatory excluding if proprietorshipStatus is NA and employmentBasisType is LABOUR_HIRE.
|
||||||||||||||||||||||||||||||||||||
| taxTreatmentType | String | AU only: Note: See Tax Treatment Type table at end of the attributes list to determine when a Tax Treatment Type can be applied.
|
||||||||||||||||||||||||||||||||||||
| workPerformedOverseas | Boolean | AU only: True if employee is working overseas. Organisation setting must be enabled. |
||||||||||||||||||||||||||||||||||||
| workOverseasCountry | String | AU only: For workPerformedOverseas=true, this is the overseas country employee is working in. For residenceType=WORKING_HOLIDAY, this is the overseas country employee is from. | ||||||||||||||||||||||||||||||||||||
| closelyHeldPayee | Boolean | AU only: True if individual is directly related to entity. Organisation setting must be enabled. |
||||||||||||||||||||||||||||||||||||
| taxFreeThresholdType | String | AU only: Mandatory if taxTreatmentType is either REGULAR or ACTORS.
|
||||||||||||||||||||||||||||||||||||
| specifiedRateAppliesTo | String Array | AU only: specifies what types of tax the specialTax applies to
|
||||||||||||||||||||||||||||||||||||
| proprietorStatus | String | Proprietor Status of the employee. Description is supported.
|
||||||||||||||||||||||||||||||||||||
| surnameIsBusinessName | Boolean | AU only: When proprietorStatus = company/contractor. Flag to indicate when surname is contractor's business name. | ||||||||||||||||||||||||||||||||||||
| includeInTaxablePaymentReport | Boolean | AU only: When proprietorStatus = company/contractor. Flag to include contractor in 'Contractor Taxable Payments Annual Report Interface' and 'Amended Contractor Taxable Payments Annual Report Interface' | ||||||||||||||||||||||||||||||||||||
| 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 |
||||||||||||||||||||||||||||||||||||
| workPattern | String | Work pattern for the employee, possible values: None, 1 Week - Monday to Sunday | ||||||||||||||||||||||||||||||||||||
| nonResidentEntertainer | Boolean | New Zealand only. When non-resident entertainer is supported True if employee is a non-resident entertainer |
||||||||||||||||||||||||||||||||||||
| kiwisaverHolidayEndDate | String | New Zealand only. Date on which the KiwiSaver savings suspension 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
|
||||||||||||||||||||||||||||||||||||
| kiwiSaverAgeRange | String | New Zealand only. Age range for kiwisaver. Ignored if employee has birthDate. Mandatory if employee does not have birthDate. Code or description is supported
|
||||||||||||||||||||||||||||||||||||
| kiwiSaverCasualAutoEnrollExempt | Boolean | New Zealand only. True if employee is excempt from auto enroling in KiwiSaver. Only available if employee age is between 18 and 64 |
||||||||||||||||||||||||||||||||||||
| lastModifiedDate | String | The date the employee record was last changed by a user. | ||||||||||||||||||||||||||||||||||||
| timecardEmployeeSettingsarrow_drop_downarrow_drop_up | JSON Object | A JSON object representing the standard hours worked each day |
Australian Tax Tables
Tax Scales
| taxTreatmentType | taxFreeThreshold | employmentBasisType | taxScale Options |
|---|---|---|---|
| REGULAR | CLAIMED | TWO FOUR_A FIVE SIX |
|
| REGULAR | UNCLAIMED | ONE | |
| FOREIGN_RESIDENT | THREE FOUR_B |
||
| ACTORS | CLAIMED | A_ACTOR | |
| ACTORS | UNCLAIMED | B_ACTOR | |
| SENIORS | SINGLE ILLNESS_SEPARATE MEMBER_OF_A_COUPLE |
||
| WORKING_HOLIDAY | H FOUR_A FOUR_B |
||
| SEASONAL | W | ||
| NONE | |||
| CONTRACTOR_PAYG | CONTRACTOR_VOLUNTARY |
Tax Treatment Type
| proprietorStatus | employmentBasis | residenceType | Other flags | taxTreamentType Options |
|---|---|---|---|---|
| NA | CONTRACTOR_PAYG | COMMISSIONER_INSTALMENT NO_COMMISSIONER_INSTALMENT |
||
| NA | OTHER | NONE | ||
| NA | LABOUR_HIRE | AUSTRALIAN | REGULAR ACTORS SENIORS |
|
| NA | LABOUR_HIRE | FOREIGN | FOREIGN_RESIDENTS ACTORS SENIORS |
|
| WORKING_HOLIDAY | WORKING_HOLIDAY | |||
| FOREIGN | closelyHeldPayee = true | FOREIGN_RESIDENTS ACTORS SENIORS |
||
| AUSTRALIAN | closelyHeldPayee = true OR workPerformedOverseas = true | REGULAR ACTORS SENIORS |
||
| FOREIGN | FOREIGN_RESIDENTS ACTORS SEASONAL SENIORS |
|||
| AUSTRALIAN | REGULAR ACTORS SEASONAL SENIORS |
POST /api/v1/employees
Create one or more employees
(Scope: employees)
Create one or more employees in an organisation. An employee can be created with Surname alone. Otherwise, all other required attributes must be included. This cannot be used to update details of an existing employee.
Request Body Properties
| Name | Required | Type | Description | ||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| id | No | String | Unique ID to identify an employee within an organisation. Limited to a-z, A-Z, 0-9, _ (underscore) and - (hyphen). |
||||||||||||||||||||||||||||||||||||
| 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. If Xero Tracking Categories are used, the chart of account code and each tracking category must be split by a pipe, e.g. "477|Sales|Wellington". |
||||||||||||||||||||||||||||||||||||
| No | String | Email address | |||||||||||||||||||||||||||||||||||||
| firstNames | Yes | String | All first names | ||||||||||||||||||||||||||||||||||||
| fullTimeHoursWeek | Yes | 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 | Yes | String | NZ Male or Female or Gender Diverse. AU Male or Female or Intersex/Indeterminate or Not Stated. | ||||||||||||||||||||||||||||||||||||
| paidToDate | No | String | Date up to which the employee has been paid (multiple date formats supported, dd/mm/yyyy preferred) | ||||||||||||||||||||||||||||||||||||
| payFrequency | Yes | String | Frequency of payroll - pay frequency name, code and description are supported:
|
||||||||||||||||||||||||||||||||||||
| phone | No | String | Phone number | ||||||||||||||||||||||||||||||||||||
| startDate | Yes | String | Date on which the employee joined the organisation (multiple date formats supported, dd/mm/yyyy preferred) | ||||||||||||||||||||||||||||||||||||
| workState | Yes | 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 | Preferred Name of the employee | ||||||||||||||||||||||||||||||||||||
| userDefinedGroup | No | String | User Defined Group of the employee - value expected is one of the group values defined for the organisation. When User Defined Groups are disabled for an organisation, this field is optional. Alternatively, the value ‘DEFAULT’ can be used whether User Defined Groups are enabled or not. |
||||||||||||||||||||||||||||||||||||
| paymentMethod | Yes | String | Method of the employee is being paid. Code and Description are supported.
|
||||||||||||||||||||||||||||||||||||
| bankAccountNumber | Yes | String | Bank account number of the employee | ||||||||||||||||||||||||||||||||||||
| taxNumber | Yes | String | Tax number of the employee. AU TFN is masked in all responses, for example, "*** *** 123" |
||||||||||||||||||||||||||||||||||||
| finishDate | No | String | Final Pay day of the employee | ||||||||||||||||||||||||||||||||||||
| terminationReason | No | String | AU only: Termination reason of the employee | ||||||||||||||||||||||||||||||||||||
| deathBenefitSurname | No | String | AU only: Death beneficiaries Surname | ||||||||||||||||||||||||||||||||||||
| deathBenefitFirstName | No | String | AU only: Death beneficiaries First Name | ||||||||||||||||||||||||||||||||||||
| deathBenefitRecipient | No | String | AU only: Death benefit recipient. Code and Description are supported.
|
||||||||||||||||||||||||||||||||||||
| taxCode | Yes | String | New Zealand Tax Code of the employee
|
||||||||||||||||||||||||||||||||||||
| taxScale | Yes | String | Australian Tax scale of the employee. Tax Scale if proprietorStatus is Employee or Labour Hire. Contractor Tax if proprietorStatus is Company/Contractor. Note: See Tax Scale table at end of the attributes list to determine when a tax code can be applied.
|
||||||||||||||||||||||||||||||||||||
| kiwiSaverRate | Yes | Number | Kiwisaver Employee Contribution rate of the employee | ||||||||||||||||||||||||||||||||||||
| employerSubsidy | Yes | Number | KiwiSaver employer contribution | ||||||||||||||||||||||||||||||||||||
| esctRate | Yes | Number | NZ only: 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 | NZ: Special tax rate of the employee AU: Specified rate of the employee |
||||||||||||||||||||||||||||||||||||
| specialStudentLoan | No | Number | NZ only: Special Student Loan rates of the employee | ||||||||||||||||||||||||||||||||||||
| specialEarnerLevy | No | Number | NZ only: Special Earner Levy rate of the employee | ||||||||||||||||||||||||||||||||||||
| specialExtraPayRate | No | Number | NZ only: Special Extra Pay Rate of the employee | ||||||||||||||||||||||||||||||||||||
| hasDebt | No | Boolean | AU only: Higher Education Loan Program (HELP), VET Student Loan (VSL), Financial Supplement (FS), Student Start-up Loan (SSL) or Trade Support Loan (TSL) Debt | ||||||||||||||||||||||||||||||||||||
| helpDebt | No | Boolean | AU only: HELP Debt. This attribute is legacy as of 15-Nov-2021 and is replaced by hasDebt. | ||||||||||||||||||||||||||||||||||||
| sfssDebt | No | Boolean | AU only: SFSS Debt. This attribute is legacy as of 15-Nov-2021 and is replaced by hasDebt. | ||||||||||||||||||||||||||||||||||||
| medicareLevyVariationDeclaration | No | Boolean | AU only: Has the employee filled a Medicare levy variation declaration | ||||||||||||||||||||||||||||||||||||
| hasSpouse | No | Boolean | AU only: Spouse | ||||||||||||||||||||||||||||||||||||
| incomeLessThanRelevantAmount | No | Boolean | AU only: 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 | AU only: Payroll Tax Exempt | ||||||||||||||||||||||||||||||||||||
| dependentChildren | No | Number | AU only: Number of dependent children of the employee | ||||||||||||||||||||||||||||||||||||
| surchargeIncrease | No | Number | AU only: Surcharge increase | ||||||||||||||||||||||||||||||||||||
| employmentBasisType | Yes | String | AU only
|
||||||||||||||||||||||||||||||||||||
| residenceType | Yes | String | AU only: Mandatory excluding if proprietorshipStatus is NA and employmentBasisType is LABOUR_HIRE.
|
||||||||||||||||||||||||||||||||||||
| taxTreatmentType | Yes | String | AU only: Note: See Tax Treatment Type table at end of the attributes list to determine when a Tax Treatment Type can be applied.
|
||||||||||||||||||||||||||||||||||||
| workPerformedOverseas | No | Boolean | AU only: True if employee is working overseas. Organisation setting must be enabled. |
||||||||||||||||||||||||||||||||||||
| workOverseasCountry | No | String | AU only: For workPerformedOverseas=true, this is the overseas country employee is working in. For residenceType=WORKING_HOLIDAY, this is the overseas country employee is from. | ||||||||||||||||||||||||||||||||||||
| closelyHeldPayee | No | Boolean | AU only: True if individual is directly related to entity. Organisation setting must be enabled. |
||||||||||||||||||||||||||||||||||||
| taxFreeThresholdType | No | String | AU only: Mandatory if taxTreatmentType is either REGULAR or ACTORS.
|
||||||||||||||||||||||||||||||||||||
| specifiedRateAppliesTo | No | String Array | AU only: specifies what types of tax the specialTax applies to
|
||||||||||||||||||||||||||||||||||||
| proprietorStatus | No | String | Proprietor Status of the employee. Description is supported.
|
||||||||||||||||||||||||||||||||||||
| surnameIsBusinessName | No | Boolean | AU only: When proprietorStatus = company/contractor. Flag to indicate when surname is contractor's business name. | ||||||||||||||||||||||||||||||||||||
| includeInTaxablePaymentReport | No | Boolean | AU only: When proprietorStatus = company/contractor. Flag to include contractor in 'Contractor Taxable Payments Annual Report Interface' and 'Amended Contractor Taxable Payments Annual Report Interface' | ||||||||||||||||||||||||||||||||||||
| 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 | Yes | String | NZ only: 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 |
||||||||||||||||||||||||||||||||||||
| nonResidentEntertainer | No | Boolean | New Zealand only. When non-resident entertainer is supported True if employee is a non-resident entertainer |
||||||||||||||||||||||||||||||||||||
| kiwisaverHolidayEndDate | No | String | New Zealand only. Date on which the KiwiSaver savings suspension will end (multiple date formats supported, dd/mm/yyyy preferred) |
||||||||||||||||||||||||||||||||||||
| notSuppliedAddress | Yes | 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 | Yes | 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 | Yes | String | New Zealand only. KiwiSaver status
|
||||||||||||||||||||||||||||||||||||
| kiwiSaverAgeRange | No | New Zealand only. Age range for kiwisaver. Ignored if employee has birthDate. Mandatory if employee does not have birthDate. Code or description is supported
|
|||||||||||||||||||||||||||||||||||||
| kiwiSaverCasualAutoEnrollExempt | No | Boolean | New Zealand only. True if employee is excempt from auto enroling in KiwiSaver. Only available if employee age is between 18 and 64 |
||||||||||||||||||||||||||||||||||||
| timecardEmployeeSettingsarrow_drop_downarrow_drop_up | No | JSON Object | A JSON object representing the standard hours worked each day |
PUT /api/v1/employees/{employeeId}
Update an employee
(Scope: employees)
Update one employee in an organisation. If all the required attributes have previously been POST or PUT for an employee, you only need to include a required attribute if you are updating it.
Path Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| employeeId | Yes | String | Unique ID to identify an employee within an organisation. Limited to a-z, A-Z, 0-9, _ (underscore) and - (hyphen). |
Request Body Properties
| Name | Required | Type | Description | ||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| id | No | String | Unique ID to identify an employee within an organisation. Limited to a-z, A-Z, 0-9, _ (underscore) and - (hyphen). |
||||||||||||||||||||||||||||||||||||
| 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. If Xero Tracking Categories are used, the chart of account code and each tracking category must be split by a pipe, e.g. "477|Sales|Wellington". |
||||||||||||||||||||||||||||||||||||
| No | String | Email address | |||||||||||||||||||||||||||||||||||||
| firstNames | Yes | String | All first names | ||||||||||||||||||||||||||||||||||||
| fullTimeHoursWeek | Yes | 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 | Yes | String | NZ Male or Female or Gender Diverse. AU Male or Female or Intersex/Indeterminate or Not Stated. | ||||||||||||||||||||||||||||||||||||
| paidToDate | No | String | Date up to which the employee has been paid (multiple date formats supported, dd/mm/yyyy preferred) | ||||||||||||||||||||||||||||||||||||
| payFrequency | Yes | String | Frequency of payroll - pay frequency name, code and description are supported:
|
||||||||||||||||||||||||||||||||||||
| phone | No | String | Phone number | ||||||||||||||||||||||||||||||||||||
| startDate | Yes | String | Date on which the employee joined the organisation (multiple date formats supported, dd/mm/yyyy preferred) | ||||||||||||||||||||||||||||||||||||
| workState | Yes | 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 | Preferred Name of the employee | ||||||||||||||||||||||||||||||||||||
| userDefinedGroup | No | String | User Defined Group of the employee - value expected is one of the group values defined for the organisation. When User Defined Groups are disabled for an organisation, this field is optional. Alternatively, the value ‘DEFAULT’ can be used whether User Defined Groups are enabled or not. |
||||||||||||||||||||||||||||||||||||
| paymentMethod | Yes | String | Method of the employee is being paid. Code and Description are supported.
|
||||||||||||||||||||||||||||||||||||
| bankAccountNumber | Yes | String | Bank account number of the employee | ||||||||||||||||||||||||||||||||||||
| taxNumber | Yes | String | Tax number of the employee. AU TFN is masked in all responses, for example, "*** *** 123" |
||||||||||||||||||||||||||||||||||||
| finishDate | No | String | Final Pay day of the employee | ||||||||||||||||||||||||||||||||||||
| terminationReason | No | String | AU only: Termination reason of the employee | ||||||||||||||||||||||||||||||||||||
| deathBenefitSurname | No | String | AU only: Death beneficiaries Surname | ||||||||||||||||||||||||||||||||||||
| deathBenefitFirstName | No | String | AU only: Death beneficiaries First Name | ||||||||||||||||||||||||||||||||||||
| deathBenefitRecipient | No | String | AU only: Death benefit recipient. Code and Description are supported.
|
||||||||||||||||||||||||||||||||||||
| taxCode | Yes | String | New Zealand Tax Code of the employee
|
||||||||||||||||||||||||||||||||||||
| taxScale | Yes | String | Australian Tax scale of the employee. Tax Scale if proprietorStatus is Employee or Labour Hire. Contractor Tax if proprietorStatus is Company/Contractor. Note: See Tax Scale table at end of the attributes list to determine when a tax code can be applied.
|
||||||||||||||||||||||||||||||||||||
| kiwiSaverRate | Yes | Number | Kiwisaver Employee Contribution rate of the employee | ||||||||||||||||||||||||||||||||||||
| employerSubsidy | Yes | Number | KiwiSaver employer contribution | ||||||||||||||||||||||||||||||||||||
| esctRate | Yes | Number | NZ only: 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 | NZ: Special tax rate of the employee AU: Specified rate of the employee |
||||||||||||||||||||||||||||||||||||
| specialStudentLoan | No | Number | NZ only: Special Student Loan rates of the employee | ||||||||||||||||||||||||||||||||||||
| specialEarnerLevy | No | Number | NZ only: Special Earner Levy rate of the employee | ||||||||||||||||||||||||||||||||||||
| specialExtraPayRate | No | Number | NZ only: Special Extra Pay Rate of the employee | ||||||||||||||||||||||||||||||||||||
| hasDebt | No | Boolean | AU only: Higher Education Loan Program (HELP), VET Student Loan (VSL), Financial Supplement (FS), Student Start-up Loan (SSL) or Trade Support Loan (TSL) Debt | ||||||||||||||||||||||||||||||||||||
| helpDebt | No | Boolean | AU only: HELP Debt. This attribute is legacy as of 15-Nov-2021 and is replaced by hasDebt. | ||||||||||||||||||||||||||||||||||||
| sfssDebt | No | Boolean | AU only: SFSS Debt. This attribute is legacy as of 15-Nov-2021 and is replaced by hasDebt. | ||||||||||||||||||||||||||||||||||||
| medicareLevyVariationDeclaration | No | Boolean | AU only: Has the employee filled a Medicare levy variation declaration | ||||||||||||||||||||||||||||||||||||
| hasSpouse | No | Boolean | AU only: Spouse | ||||||||||||||||||||||||||||||||||||
| incomeLessThanRelevantAmount | No | Boolean | AU only: 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 | AU only: Payroll Tax Exempt | ||||||||||||||||||||||||||||||||||||
| dependentChildren | No | Number | AU only: Number of dependent children of the employee | ||||||||||||||||||||||||||||||||||||
| surchargeIncrease | No | Number | AU only: Surcharge increase | ||||||||||||||||||||||||||||||||||||
| employmentBasisType | Yes | String | AU only
|
||||||||||||||||||||||||||||||||||||
| residenceType | Yes | String | AU only: Mandatory excluding if proprietorshipStatus is NA and employmentBasisType is LABOUR_HIRE.
|
||||||||||||||||||||||||||||||||||||
| taxTreatmentType | Yes | String | AU only: Note: See Tax Treatment Type table at end of the attributes list to determine when a Tax Treatment Type can be applied.
|
||||||||||||||||||||||||||||||||||||
| workPerformedOverseas | No | Boolean | AU only: True if employee is working overseas. Organisation setting must be enabled. |
||||||||||||||||||||||||||||||||||||
| workOverseasCountry | No | String | AU only: For workPerformedOverseas=true, this is the overseas country employee is working in. For residenceType=WORKING_HOLIDAY, this is the overseas country employee is from. | ||||||||||||||||||||||||||||||||||||
| closelyHeldPayee | No | Boolean | AU only: True if individual is directly related to entity. Organisation setting must be enabled. |
||||||||||||||||||||||||||||||||||||
| taxFreeThresholdType | No | String | AU only: Mandatory if taxTreatmentType is either REGULAR or ACTORS.
|
||||||||||||||||||||||||||||||||||||
| specifiedRateAppliesTo | No | String Array | AU only: specifies what types of tax the specialTax applies to
|
||||||||||||||||||||||||||||||||||||
| proprietorStatus | No | String | Proprietor Status of the employee. Description is supported.
|
||||||||||||||||||||||||||||||||||||
| surnameIsBusinessName | No | Boolean | AU only: When proprietorStatus = company/contractor. Flag to indicate when surname is contractor's business name. | ||||||||||||||||||||||||||||||||||||
| includeInTaxablePaymentReport | No | Boolean | AU only: When proprietorStatus = company/contractor. Flag to include contractor in 'Contractor Taxable Payments Annual Report Interface' and 'Amended Contractor Taxable Payments Annual Report Interface' | ||||||||||||||||||||||||||||||||||||
| 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 | Yes | String | NZ only: 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 |
||||||||||||||||||||||||||||||||||||
| nonResidentEntertainer | No | Boolean | New Zealand only. When non-resident entertainer is supported True if employee is a non-resident entertainer |
||||||||||||||||||||||||||||||||||||
| kiwisaverHolidayEndDate | No | String | New Zealand only. Date on which the KiwiSaver savings suspension will end (multiple date formats supported, dd/mm/yyyy preferred) |
||||||||||||||||||||||||||||||||||||
| notSuppliedAddress | Yes | 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 | Yes | 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 | Yes | String | New Zealand only. KiwiSaver status
|
||||||||||||||||||||||||||||||||||||
| kiwiSaverAgeRange | No | String | New Zealand only. Age range for kiwisaver. Ignored if employee has birthDate. Mandatory if employee does not have birthDate. Code or description is supported
|
||||||||||||||||||||||||||||||||||||
| kiwiSaverCasualAutoEnrollExempt | No | Boolean | New Zealand only. True if employee is excempt from auto enroling in KiwiSaver. Only available if employee age is between 18 and 64 |
||||||||||||||||||||||||||||||||||||
| timecardEmployeeSettingsarrow_drop_downarrow_drop_up | No | JSON Object | A JSON object representing the standard hours worked each day |
GET /api/v1/employees
Retrieve all employees
(Scope: employees)
Returns all the active employees of an organisation. Optionally, use status=inactive, to retrieve the inactive employees.
AU TFN is masked in all responses, for example, "*** *** 123".
Query Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| status | No | String | Use status=inactive to retrieve the inactive employees: /api/v1/employees?status=inactive |
GET /api/v1/employees/{employeeId}
Retrieve an employee's details
(Scope: employees)
Returns an employee.
AU TFN is masked in all responses, for example, "*** *** 123".
Path Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| employeeId | Yes | String | Unique ID to identify an employee within an organisation. Limited to a-z, A-Z, 0-9, _ (underscore) and - (hyphen). |
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 | ||||||||||||
| employeeId | String | Unique ID to identify an employee within an organisation. Limited to a-z, A-Z, 0-9, _ (underscore) and - (hyphen). |
||||||||||||
| 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/payrates
Retrieve pay rates for all employees
(Scopes: payrates employees)
Returns details of all pay rates for active employees associated with an organisation.
Query Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| status | No | String | Use status=inactive to retrieve the pay rates for inactive employees: /api/v1/payrates?status=inactive |
GET /api/v1/payrates/{payRateId}
Retrieve a specific pay rate
(Scopes: payrates employees)
Returns details of a particular pay rate.
Path Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| payRateId | Yes | String | Unique ID to identify a pay rate. |
POST /api/v1/payrates
Update one or more pay rates
(Scopes: payrates employees)
Update one or more pay rates for one or more employees for an organisation.
Request Body Properties
| Name | Required | Type | Description | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| employeeId | Yes | String | Unique ID to identify an employee within an organisation. Limited to a-z, A-Z, 0-9, _ (underscore) and - (hyphen). |
||||||||||||
| code | Yes | String | Indicates the position of the rate on Personal Details
|
||||||||||||
| divisor | Yes * | String | If an organisation specific divisor is associated, this field should contain a 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 an organisation specific or global divisor. |
||||||||||||
| rate | Yes * | String | Value of pay rate as entered in iPayroll. * rate is mandatory when updating an 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. |
GET /api/v1/employees/{employeeId}/payrates
Retrieve all of an employee’s pay rates
(Scopes: payrates employees)
Returns details of all pay rates associated with an employee.
Path Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| employeeId | Yes | String | Unique ID to identify an employee within an organisation. Limited to a-z, A-Z, 0-9, _ (underscore) and - (hyphen). |
GET /api/v1/employees/{employeeId}/payrates/{code}
Retrieve a specific pay rate for an employee
(Scopes: payrates employees)
Returns details of a particular pay rate of an employee.
Path Parameters
| Name | Required | Type | Description | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| employeeId | Yes | String | Unique ID to identify an employee within an organisation. Limited to a-z, A-Z, 0-9, _ (underscore) and - (hyphen). |
||||||||||||
| code | Yes | String | Indicates the position of the rate on Personal Details
|
PUT /api/v1/employees/{employeeId}/payrates/{code}
Update a specific pay rate for an employee
(Scopes: payrates employees)
Update a particular pay rate of an employee.
Path Parameters
| Name | Required | Type | Description | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| employeeId | Yes | String | Unique ID to identify an employee within an organisation. Limited to a-z, A-Z, 0-9, _ (underscore) and - (hyphen). |
||||||||||||
| code | Yes | String | Indicates the position of the rate on Personal Details
|
Request Body Properties
| Name | Required | Type | Description |
|---|---|---|---|
| divisor | Yes * | String | If an organisation specific divisor is associated, this field should contain a 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 an organisation specific or global divisor. |
| rate | Yes * | String | Value of pay rate as entered in iPayroll. * rate is mandatory when updating an 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 as the employeeId |
| employeeId | String | Unique ID to identify an employee within an organisation. Limited to a-z, A-Z, 0-9, _ (underscore) and - (hyphen). |
| daysInPeriod | Number | Number of days an employee has worked within the period of the timesheet. 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 | String | The start date of the pay period (multiple date formats supported, dd/mm/yyyy preferred) |
| paidToDate | String | The end date of the pay period (multiple date formats supported, dd/mm/yyyy preferred) |
| 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 the timesheets in the latest payroll
(Scope: timesheets)
Returns all timesheets associated with the latest payroll of an organisation.
GET /api/v1/timesheets/{timesheetId}
Retrieve an employee's latest timesheet
(Scope: timesheets)
Returns the latest timesheet of an employee.
Path Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| timesheetId | Yes | String | Unique ID to identify a timesheet. employeeId can be used. |
GET /api/v1/payrolls/{payrollId}/timesheets
Retrieve all of the timesheets in a specific payroll
(Scopes: timesheets payrolls)
Returns all timesheets associated with the specific payroll of an organisation.
Path Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| payrollId | Yes | String | Unique ID to identify a payroll within an organisation |
GET /api/v1/payrolls/current/timesheets
Retrieve all timesheets in the current payroll
(Scopes: timesheets payrolls)
Returns all timesheets associated with the current payroll of an organisation.
GET /api/v1/payrolls/{payrollId}/timesheets/{timesheetId}
Retrieve an employee's timesheet in a specific payroll
(Scopes: timesheets payrolls)
Returns employee's timesheet associated with the specific payroll of an organisation.
Path 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/current/timesheets/{timesheetId}
Retrieve an employee's timesheet in the current payroll
(Scopes: timesheets payrolls)
Returns employee's timesheet associated with the current payroll of an organisation.
Path Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| timesheetId | Yes | String | Unique ID to identify a timesheet. employeeId can be used. |
POST /api/v1/timesheets
Create one or more timesheets
(Scope: 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.
Note: The payroll won't automatically open, if it is the very first payroll. You'll need to manually open the first payroll in the application.
Request Body Properties
| Name | Required | Type | Description |
|---|---|---|---|
| daysInPeriod | No | Number | Number of days an employee has worked within the period of the timesheet. May be omitted, it is only relevant for organisations that have "record day on timesheet" option on |
| employeeId | Yes | String | Unique ID to identify an employee within an organisation. The employee should already be added to the payroll before posting timesheets against. |
| paidToDate | No | String | The end date of the pay period (multiple date formats supported, dd/mm/yyyy preferred) |
| message | No | String | If supplied, the message will be appended to the person's payslip message |
| transactions arrow_drop_downarrow_drop_up | Yes | Array | List of timesheet transactions for the employee. An empty array is allowed |
Employee Not Found in Payroll
| Standard Codes | Standard Message | Description |
|---|---|---|
| 125 | Employee does not exist | Employee Id cannot be found. |
| 126 | Employee does not have a start date | The employee does not have a start date in Personal Details. |
| 127 | Employee does not have the correct pay frequency | The pay frequency of the current payroll is different from the pay frequency of the employee. |
| 128 | Employee does not have hours on timesheet template | The current payroll only accepts timesheets for employees with hours on their timesheet template. |
| 129 | Employee's start date is after the paid to date | The employee's start date is after the paid to date of the current payroll. |
| 130 | Employee has already been paid | Employee has a paid to date on or after the paid to date of the current payroll. |
| 131 | Employee has already finished | The employee’s finish date is on or before the paid to date of the current payroll. |
DELETE /api/v1/timesheets/{timesheetId}/transactions/{timesheetTransactionId}
Delete a timesheet transaction in the current payroll of an organisation
(Scope: timesheets)
The current payroll must be open.
Path Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| timesheetId | Yes | String | Unique ID to identify a timesheet. employeeId can be used. |
| timesheetTransactionId | Yes | Integer | Unique ID to identify a timesheet transaction |
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. Limited to a-z, A-Z, 0-9, _ (underscore) and - (hyphen). |
| entitled | Number | The number of units given since records started up to and including the current pay if a payroll is open |
| accrued | Number | The number of units accrued since last anniversary up to and including the current pay if a payroll is open |
| taken | Number | The total number of units taken from the leave balance up to and including the current pay if a payroll is open |
| balance | Number | The number of leave units remaining for an employee based on the following equation: Entitled + Accrued - Taken (up to and including the current pay if a payroll is open) |
| committedEntitled | Number | The number of units given since records started as at last pay |
| committedAccrued | Number | The number of units accrued since last anniversary as at last pay |
| committedTaken | Number | The total number of units taken from the leave balance as at last pay |
| committedBalance | Number | The number of leave units remaining for an employee based on the following equation: committedEntitled + committedAccrued - committedTaken as at last pay |
| nextAnniversaryDate | String | Next anniversary date (multiple date formats supported, dd/mm/yyyy preferred) |
| lastAnniversaryDate | String | Last anniversary date (multiple date formats supported, dd/mm/yyyy preferred) |
| 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/leaves/balances
Retrieve leave balances for all employees
(Scopes: leavebalances employees)
Returns details of all leave balances for active employees associated with an organisation.
Query Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| status | No | String | Use status=inactive to retrieve the leave balances for inactive employees: /api/v1/leaves/balances?status=inactive |
GET /api/v1/leaves/balances/{leaveBalanceId}
Retrieve a specific leave balance
(Scopes: leavebalances employees)
Returns details of a particular leave balance.
Path Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| leaveBalanceId | Yes | String | Unique ID to identify a leave balance. |
GET /api/v1/employees/{employeeId}/leaves/balances
Retrieve all of an employee's leave balances
(Scopes: leavebalances employees)
Returns details of all leave balances associated with an employee.
Path Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| employeeId | Yes | String | Unique ID to identify an employee within an organisation. Limited to a-z, A-Z, 0-9, _ (underscore) and - (hyphen). |
GET /api/v1/employees/{employeeId}/leaves/balances/{leaveBalanceTypeName}
Retrieve a specific leave balance for an employee
(Scopes: leavebalances employees)
Returns details of a particular leave balance of an employee.
Path Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| employeeId | Yes | String | Unique ID to identify an employee within an organisation. Limited to a-z, A-Z, 0-9, _ (underscore) and - (hyphen). |
| leaveBalanceTypeName | Yes | String | Name of the leave balance type |
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. Limited to a-z, A-Z, 0-9, _ (underscore) and - (hyphen). |
| 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 | String | First day of leave (multiple date formats supported, dd/mm/yyyy preferred) |
| leaveToDate | String | Last day of leave (multiple date formats supported, dd/mm/yyyy preferred) |
| 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
(Scope: leaverequests)
Returns details of all leave requests associated with an organisation.
Query 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/{requestId}
Retrieve details of a leave request
(Scope: leaverequests)
Returns a leave request.
Path Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| requestId | Yes | Number | Unique ID to identify a leave request |
GET /api/v1/leaves/requests/current
Retrieve current leave requests
(Scope: leaverequests)
Returns details of current leave requests (with status ‘Pending’ or ‘Approved’) associated with an organisation.
GET /api/v1/employees/{employeeId}/leaves/requests
Retrieve all of an employee's leave requests
(Scopes: leaverequests employees)
Returns details of all leave requests associated with an employee.
Path Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| employeeId | Yes | String | Unique ID to identify an employee within an organisation. Limited to a-z, A-Z, 0-9, _ (underscore) and - (hyphen). |
Query Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| status | No | String | Processing status of a leave request. The status can be one of the following:
|
GET /api/v1/employees/{employeeId}/leaves/requests/current
Retrieve current leave requests of an employee
(Scopes: leaverequests employees)
Returns details of current leave requests (with status ‘Pending’ or ‘Approved’) associated with an employee.
Path Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| employeeId | Yes | String | Unique ID to identify an employee within an organisation. Limited to a-z, A-Z, 0-9, _ (underscore) and - (hyphen). |
GET /api/v1/employees/{employeeId}/leaves/requests/{requestId}
Retrieve details of a leave request associated with an employee
(Scopes: leaverequests employees)
Returns a leave request.
Path Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| employeeId | Yes | String | Unique ID to identify an employee within an organisation. Limited to a-z, A-Z, 0-9, _ (underscore) and - (hyphen). |
| requestId | Yes | Number | Unique ID to identify a leave request |
POST /api/v1/leaves/requests
Create a leave request
(Scope: leaverequests)
Create a Leave Request for an employee.
Request Body Properties
| Name | Required | Type | Description |
|---|---|---|---|
| employeeId | Yes | String | Unique ID to identify an employee within an organisation. Limited to a-z, A-Z, 0-9, _ (underscore) and - (hyphen). |
| 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 | String | First day of leave (multiple date formats supported, dd/mm/yyyy preferred) |
| leaveToDate | Yes | String | Last day of leave (multiple date formats supported, dd/mm/yyyy preferred) |
| 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}
Update a leave request
(Scope: leaverequests)
Update a Leave Request for an employee.
Path Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| requestId | Yes | Number | Unique ID to identify a leave request |
Request Body Properties
| Name | Required | Type | Description |
|---|---|---|---|
| employeeId | Yes | String | Unique ID to identify an employee within an organisation. Limited to a-z, A-Z, 0-9, _ (underscore) and - (hyphen). |
| 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 | String | First day of leave (multiple date formats supported, dd/mm/yyyy preferred) |
| leaveToDate | Yes | String | Last day of leave (multiple date formats supported, dd/mm/yyyy preferred) |
| 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
Parental Leave
This is only used in New Zealand organisations so is only applicable to New Zealand customers.
Attributes
| Name | Type | Description |
|---|---|---|
| id | Number | Unique ID to identify a parental leave |
| employeeId | String | Unique ID to identify an employee within an organisation. Limited to a-z, A-Z, 0-9, _ (underscore) and - (hyphen). |
| startDate | String | First day of parental leave (multiple date formats supported, dd/mm/yyyy preferred) |
| plannedEndDate | String | Planned end day of parental leave (multiple date formats supported, dd/mm/yyyy preferred) |
| actualEndDate | String | Actual end day of parental leave (multiple date formats supported, dd/mm/yyyy preferred) |
GET /api/v1/employees/{employeeId}/leaves/parental
Retrieve all parental leave for an employee
(Scopes: parentalleaves employees)
Returns all current and historical parental leave for an employee.
Path Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| employeeId | Yes | String | Unique ID to identify an employee within an organisation. Limited to a-z, A-Z, 0-9, _ (underscore) and - (hyphen). |
GET /api/v1/employees/{employeeId}/leaves/parental/{parentalLeaveId}
Retrieve a parental leave
(Scopes: parentalleaves employees)
Returns a specific parental leave for an employee
Path Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| employeeId | Yes | String | Unique ID to identify an employee within an organisation. Limited to a-z, A-Z, 0-9, _ (underscore) and - (hyphen). |
| parentalLeaveId | Yes | Number | Unique ID to identify a parental leave. Use "current" to retrieve the currently active parental leave for the employee. |
POST /api/v1/employees/{employeeId}/leaves/parental
Create a parental leave
(Scopes: parentalleaves employees)
Creates a parental leave for an employee.
Path Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| employeeId | Yes | String | Unique ID to identify an employee within an organisation. Limited to a-z, A-Z, 0-9, _ (underscore) and - (hyphen). |
Request Body Properties
| Name | Required | Type | Description |
|---|---|---|---|
| startDate | Yes | String | First day of parental leave (multiple date formats supported, dd/mm/yyyy preferred) |
| plannedEndDate | Yes | String | Planned end day of parental leave (multiple date formats supported, dd/mm/yyyy preferred) |
| actualEndDate | No | String | Actual end day of parental leave. If provided, a historical parental leave will be created. If not provided a current parental leave will be created. (multiple date formats supported, dd/mm/yyyy preferred) |
| hoursPerPayPeriod | Yes | Number | Total hours per pay period |
PUT /api/v1/employees/{employeeId}/leaves/parental/{parentalLeaveId}
Update a parental leave
(Scopes: parentalleaves employees)
Update a parental leave for an employee.
Path Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| employeeId | Yes | String | Unique ID to identify an employee within an organisation. Limited to a-z, A-Z, 0-9, _ (underscore) and - (hyphen). |
| parentalLeaveId | Yes | Number | Unique ID to identify a parental leave. Use "current" to update the currently active parental leave for the employee. |
Request Body Properties
| Name | Required | Type | Description |
|---|---|---|---|
| startDate | No | String | First day of parental leave (multiple date formats supported, dd/mm/yyyy preferred) |
| plannedEndDate | No | String | Planned end day of parental leave (multiple date formats supported, dd/mm/yyyy preferred) |
| actualEndDate | No | String | Actual end day of parental leave. When provided for a current parental leave, this will return the employee from parental leave. (multiple date formats supported, dd/mm/yyyy preferred) |
DELETE /api/v1/employees/{employeeId}/leaves/parental/current
Delete a parental leave
(Scopes: parentalleaves employees)
Deletes the current parental leave for an employee.
Path Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| employeeId | Yes | String | Unique ID to identify an employee within an organisation. Limited to a-z, A-Z, 0-9, _ (underscore) and - (hyphen). |
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 | Australia only. Net 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
(Scopes: payslips payrolls)
Returns all payslips generated in the latest pay run.
GET /api/v1/payrolls/current/payslips/{employeeId}
Retrieve a single employee's payslip in the latest payroll
(Scopes: payslips payrolls)
Returns payslip of the specified employee.
Path Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| employeeId | Yes | String | Unique ID to identify an employee within an organisation. Limited to a-z, A-Z, 0-9, _ (underscore) and - (hyphen). |
GET /api/v1/payrolls/current/payslips/{employeeId}/download
Retrieve a single employee's payslip in the latest payroll in PDF format
(Scopes: payslips payrolls)
Returns a pdf file with the payslip of the specified employee.
Path Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| employeeId | Yes | String | Unique ID to identify an employee within an organisation. Limited to a-z, A-Z, 0-9, _ (underscore) and - (hyphen). |
GET /api/v1/payrolls/{payrollId}/payslips
Retrieve all payslips in a specific payroll
(Scopes: payslips payrolls)
Returns all payslips associated with the specified payroll.
Path Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| payrollId | Yes | String | Unique identifier of the payroll |
GET /api/v1/payrolls/{payrollId}/payslips/{employeeId}
Retrieve specific employee's payslip in a specific payroll
(Scopes: payslips payrolls)
Returns specified employee's payslip in the specified payroll.
Path Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| payrollId | Yes | String | Unique identifier of the payroll |
| employeeId | Yes | String | Unique ID to identify an employee within an organisation. Limited to a-z, A-Z, 0-9, _ (underscore) and - (hyphen). |
GET /api/v1/payrolls/{payrollId}/payslips/{employeeId}/download
Retrieve specific employee's payslip in a specific payroll in PDF format
(Scopes: payslips payrolls)
Returns a pdf file with the specified employee's payslip in the specified payroll.
Path Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| payrollId | Yes | String | Unique identifier of the payroll |
| employeeId | Yes | String | Unique ID to identify an employee within an organisation. Limited to a-z, A-Z, 0-9, _ (underscore) and - (hyphen). |
GET /api/v1/payrolls/payslips/{employeeId}/download?payDateFrom={payDateFrom}&payDateTo={payDateTo}
Retrieve specific employee's payslips for a date range in PDF format
(Scopes: payslips payrolls)
Returns a pdf file with the specified employee's payslips from a date range.
Path Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| employeeId | Yes | String | Unique ID to identify an employee within an organisation. Limited to a-z, A-Z, 0-9, _ (underscore) and - (hyphen). |
Query Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| payDateFrom | Yes | String | The start date of the period (multiple date formats supported, dd/mm/yyyy preferred) |
| payDateTo | Yes | String | The end date of the period (multiple date formats supported, dd/mm/yyyy preferred) |
Pay Elements
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. Same as code. |
| 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 |
| payslipDescription | String | When used, displays on the payslip in place of the "description" attribute |
| 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 | 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 |
| itemisedCategory | String | Australia only. The itemised category when pay element is itemised on payment summary |
| allowPartialDeduction | Boolean | True if the pay element allows partial deduction |
| consolidateTransactions | Boolean | True if the pay element applies consolidate transactions |
| payeeReference | String | Payee Reference |
| payeeCode | String | New Zealand only. Payee code |
| destinationAccountName | String | New Zealand only. Destination account name for the deduction pay element. |
| accountName | String | Australia only. Account name for the deduction pay element. |
| 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 | New Zealand only. Payee particulars |
| doneeAddress | String | New Zealand only. Donee address |
| doneeName | String | New Zealand only. 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 |
| lumpeLiable | Boolean | Australia only. True if the pay element is lump E liable |
| 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) excluded 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
(Scope: payelements)
Returns all the pay elements of an organisation.
GET /api/v1/payelements/{payElementId}
Retrieve a pay element
(Scope: payelements)
Returns a particular pay element of the organisation, identified by pay element code.
Path Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| payElementId | Yes | String | Unique ID to identify a pay element. Same as code. If the pay element code has special characters, use the GET /api/v1/payelement?code={payElementId} endpoint. |
GET /api/v1/payelement?code={payElementId}
Retrieve a pay element (includes special characters)
(Scope: payelements)
Returns a particular pay element of the organisation, identified by pay element code.
Query Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| payElementId | Yes | String | Unique ID to identify a pay element. Same as code. If the code has special characters, the special characters must be encoded. |
Custom Fields
A custom field contains 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 | Integer | The category id of the custom field. |
| categoryName | String | The category name of the custom field. |
| customFieldId | Integer | The id for this custom field. |
| name | String | Name of the custom field. |
| date | String | Date the custom field was added to the employee (multiple date formats supported, dd/mm/yyyy preferred) |
| 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. Full Time Equivalent for the contract. |
| contractEnd | String | Contract only. Contract end date (multiple date formats supported, dd/mm/yyyy preferred) |
| 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 (multiple date formats supported, dd/mm/yyyy preferred) |
| start | String | Position only. Date String for the position's start date (multiple date formats supported, dd/mm/yyyy preferred) |
| 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. |
| employeeId | String | Unique ID to identify an employee within an organisation. Limited to a-z, A-Z, 0-9, _ (underscore) and - (hyphen). |
GET /api/v1/employees/{employeeId}/customfields
Retrieve all custom fields for employee
(Scopes: customfields employees)
Returns all the custom fields including values for an employee.
Path Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| employeeId | Yes | String | Unique ID to identify an employee within an organisation. Limited to a-z, A-Z, 0-9, _ (underscore) and - (hyphen). |
GET /api/v1/employees/{employeeId}/customfields/{categoryId}
Retrieve all custom fields of a single category for an employee
(Scopes: customfields employees)
Returns all the custom fields including values of the specified category id for an employee.
Path Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| employeeId | Yes | String | Unique ID to identify an employee within an organisation. Limited to a-z, A-Z, 0-9, _ (underscore) and - (hyphen). |
| categoryId | Yes | Integer | 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
(Scopes: customfields employees)
Returns a specific custom field from the employee based on its id number and category.
Path Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| employeeId | Yes | String | Unique ID to identify an employee within an organisation. Limited to a-z, A-Z, 0-9, _ (underscore) and - (hyphen). |
| category | Yes | Integer | The id of the custom field category. |
| id | Yes | Integer | The id of the custom field. |
GET /api/v1/employees/customfields
Retrieve all custom fields
(Scopes: customfields employees)
Returns all the custom fields including values based on parameters.
Query Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| employeeId | No | String | Unique ID to identify an employee within an organisation. Limited to a-z, A-Z, 0-9, _ (underscore) and - (hyphen). |
| categoryId | No | Integer | The category id of the custom field. |
| categoryName | No | String | The category name of the custom field. Not case sensitive. |
| customFieldId | No | Integer | The id for this custom field. |
| customFieldName | No | String | Name of the custom field. Not case sensitive. Needs to be used together with categoryId or categoryName. |
Sample requests
GET /api/v1/employees/customfields?categoryName=CONTACT&customFieldName=NEXT OF KIN&employeeId=2
GET /api/v1/employees/customfields?categoryName=CONTACT&customFieldName=NEXT OF KIN
GET /api/v1/employees/customfields?categoryName=CONTACT&employeeId=2
GET /api/v1/employees/customfields?employeeId=2
GET /api/v1/employees/customfields?categoryName=CONTACT
GET /api/v1/employees/customfields?categoryId=137
GET /api/v1/employees/customfields?categoryId=137&customFieldId=177&employeeId=2
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 (multiple date formats supported, dd/mm/yyyy preferred) |
| 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
(Scope: payrolls)
Returns a list of payrolls of an organisation.
Query Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| dateFrom | No | String | The start date of the period (multiple date formats supported, dd/mm/yyyy preferred) |
| dateTo | No | String | The end date of the period (multiple date formats supported, dd/mm/yyyy preferred) |
Sample requests
GET /api/v1/payrolls?dateFrom=01/01/2021&dateTo=31/01/2021
GET /api/v1/payrolls?dateFrom=01/01/2021
GET /api/v1/payrolls?dateTo=31/01/2021
GET /api/v1/payrolls
GET /api/v1/payrolls/current
Retrieve current payroll
(Scope: payrolls)
Returns the current payroll of an organisation.
GET /api/v1/payrolls/{payrollId}
Retrieve a single payroll
(Scope: payrolls)
Returns a particular 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
(Scope: leavebalances)
Returns all the leave balance types of an organisation.
Employee Superannuation
This is only used in Australian organisations so is only applicable to Australian customers.
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 override the default cost centre. |
| id | String | The id of the transaction. |
| payElement | String | The 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
(Scope: employees)
Returns all the superannuation transactions for an employee.
Path Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| employeeId | Yes | String | Unique ID to identify an employee within an organisation. Limited to a-z, A-Z, 0-9, _ (underscore) and - (hyphen). |
POST /api/v1/employees/{employeeId}/superannuation
Create employee superannuation transaction
(Scope: employees)
Creates a superannuation transaction for an employee.
Path Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| employeeId | Yes | String | Unique ID to identify an employee within an organisation. Limited to a-z, A-Z, 0-9, _ (underscore) and - (hyphen). |
Request Body Properties
| 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 override the default cost centre. If Xero Tracking Categories are used, the chart of account code and each tracking category must be split by a pipe, e.g. "477|Sales|Wellington". |
| payElement | Yes | String | The 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
(Scope: employees)
Returns a specific superannuation transactions for an employee.
Path Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| employeeId | Yes | String | Unique ID to identify an employee within an organisation. Limited to a-z, A-Z, 0-9, _ (underscore) and - (hyphen). |
| transactionId | Yes | String | Unique ID to identify a transaction for an employee. |
PUT /api/v1/employees/{employeeId}/superannuation/{transactionId}
Update employee superannuation transaction
(Scope: employees)
Updates a specific superannuation transaction for an employee.
Path Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| employeeId | Yes | String | Unique ID to identify an employee within an organisation. Limited to a-z, A-Z, 0-9, _ (underscore) and - (hyphen). |
| transactionId | Yes | String | Unique ID to identify a transaction for an employee. |
Request Body Properties
| 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 override the default cost centre. If Xero Tracking Categories are used, the chart of account code and each tracking category must be split by a pipe, e.g. "477|Sales|Wellington". |
| payElement | Yes | String | The 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
(Scope: employees)
Delete a specific superannuation transaction for an employee.
Path Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| employeeId | Yes | String | Unique ID to identify an employee within an organisation. Limited to a-z, A-Z, 0-9, _ (underscore) and - (hyphen). |
| transactionId | Yes | String | Unique ID to identify a transaction for an employee |
User Defined Groups
A User Defined Group can be set up in iPayroll to assist with sorting of employees into groups, for example, teams, approving leave and restricting access of employees to users.
If User Defined Groups are used, each employee can only be allocated to a single group.
Attributes
| Name | Type | Description |
|---|---|---|
| id | String | Unique ID to identify a user defined group. This id is the same as the value |
| value | String | User defined group value |
| description | String | User defined group description |
| label | String | User defined group label |
GET /api/v1/userdefinedgroups
Retrieve all user defined groups
(Scope: employees)
Returns all the user defined groups of an organisation.
GET /api/v1/userdefinedgroups/{value}
Retrieve a user defined group details
(Scopes: employees)
Returns a user defined group.
Path Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| value | Yes | String | Value of the user defined group |
General Ledger
Post payroll journal entries to a general ledger.
Attributes
| Name | Type | Description |
|---|---|---|
| date | String | Pay date of the payroll or dateTo when using date filters (multiple date formats supported, dd/mm/yyyy preferred) |
| accounts arrow_drop_downarrow_drop_up | JSON Object | List of accounts for the general ledger |
GET /api/v1/generalledger/{payrollId}
Retrieve the general ledger from a specific payroll
(Scope: generalledger)
Path Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| payrollId | Yes | String | Unique ID to identify a payroll within an organisation |
GET /api/v1/generalledger
Retrieve the general ledger from a date range
(Scope: generalledger)
Query Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| dateFrom | Yes | String | Starting date for the period (multiple date formats supported, dd/mm/yyyy preferred) |
| dateTo | Yes | String | End date for the period (multiple date formats supported, dd/mm/yyyy preferred) |