Developer's Guide

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 creat and update leave requests
  • 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)

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)
  • Payslips (payslips)
  • Pay Elements (payelements)
  • Payrolls (payrolls)

Your application will have to request access for the scopes it is interested in, and the user will have to grant that access.

Getting Started

To begin using the API, you first need to register a developer account by emailing api@ipayroll.co.nz with your request. We will then provide you with the following on our 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 Authorisation how to.

The parameter types in the document are described in the following table:

Type Description Examples
String A sequence of characters "This is a String"
Integer Whole number, with no fractional part 1000
Number A number which may contain a fractional part of up to 4 digits 1.1234
JSON Object JavaScript Object Notation {"foo" : "bar"}

Retrieving Resources with HTTP GET

Your application may retrieve a representation of a resource by GETting the correct URLs. Successful GET requests 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
  • MM/dd/yy
  • MM/dd/yyyy
  • dd/MM
  • dd/MMM

Links

Elements in the response may contain HATEOAS style links indicating further, related actions.

For example, a response containing an employee element, may contain links for the employee's 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...
}

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.

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

Response Example

{
  "content": [
	{
	  "links": [
		{
		  "rel": "self",
		  "href": "https://secure2.ipayroll.co.nz/api/v1/costcentres/0"
		}
	  ],
	  "id": 0,
	  "code": "Software",
	  "description": "Software Developers Department",
          "displayValue": "Software (Software Developers Department)",
          "active": true
	},
	{
	  "links": [
		{
		  "rel": "self",
		  "href": "https://secure2.ipayroll.co.nz/api/v1/costcentres/1"
		}
	  ],
	  "id": 1,
	  "code": "Marketing",
	  "description": "The Marketing Team"
	},
	...
  ]
}

GET /api/v1/costcentres/{costcentreId}

Retrieve a cost centre

(Scope: costcentres)

Returns a particular cost centre of the organisation, identified by cost centre id.

Parameters
Name Required Type Description
costcentreId Yes Integer Unique ID to identify a cost centre

GET /api/v1/costcentres/{costcentreId}

Response Example

[
  {
  	"id": 0,
	"code": "Software",
	"description": "Software Developers Department",
        "displayValue": "Software (Software Developers Department)",
        "active": true,
	"links": [
	  {
		"rel": "self",
		"href": "https://secure2.ipayroll.co.nz/api/v1/costcentres/0"
	  }
	]
  },
  ...
]

POST /api/v1/costcentres

Create one or more cost centres

(Scope: costcentres)

Create one or more cost centres in an organisation.

Parameters
Name Required Type Description
costCentres arrow_drop_down Yes JSON Object A list of costCentres to be created. This end point takes a single cost centre or an array of cost centres

POST /api/v1/costcentres

Request Body Example

[
  {
	"code": "Software",
	"description": "Software Developers Department"
   },
   {
	 "code": "Marketing",
	 "description": "The Marketing Team"
   }
  ...more cost centres...
]

Response Example

[
  {
  	"id": 0,
	"code": "Software",
	"description": "Software Developers Department",
        "displayValue": "Software (Software Developers Department)",
        "active": true,
	"links": [
		{
		  "rel": "self",
		  "href": "https://secure2.ipayroll.co.nz/api/v1/costcentres/0"
		}
	]
  },
  {
  	"id": 1,
	"code": "Marketing",
	"description": "The Marketing Team",
        "displayValue": "Marketing (The Marketing Team)",
        "active": true,
	"links": [
		{
		  "rel": "self",
		  "href": "https://secure2.ipayroll.co.nz/api/v1/costcentres/1"
		}
	]
  },
  ...
]

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
email 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:
Name Code Description
WEEKLY W Weekly
FORTNIGHTLY F Fortnightly
MONTHLY M Monthly
BI_MONTHLY B Bi-Monthly
FOUR_WEEKLY 4 4-Weekly
WEEKLY_2 W2 Weekly (2)
FORTNIGHTLY_2 F2 Fortnightly (2)
MONTHLY_2 M2 Monthly (2)
BI_MONTHLY_2 B2 Bi-Monthly (2)
FOUR_WEEKLY_2 42 4-Weekly (2)
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.
Code Description
ACT Australian Capital Territory
NSW New South Wales
NT Northern Territory
QLD Queensland
SA South Australia
TAS Tasmania
VIC Victoria
WA Western Australia
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
paymentMethod String Method of the employee is being paid. Code and Description are supported.
Code Description
BANK Bank
CASH Cash
CHEQUE Cheque
bankAccountNumber String Bank account number of the employee
taxNumber String Tax number of the employee
finishDate String Final Pay day of the employee
terminationReason String Termination reason of the employee
deathBenefitSurname String Death beneficiaries Surname
deathBenefitFirstName String Death beneficiaries First Name
deathBenefitRecipient String Death benefit recipient
taxCode String New Zealand Tax Code of the employee
taxScale String Australian Tax scale of the employee
kiwiSaverRate Number Kiwisaver Employee Contribution rate of the employee
employerSubsidy Number Employer's subsidy rate for Kiwisaver
esctRate Number Tax rate that will be deducted from Superannuation Employer Contribution
kiwiSaverOptOutDate String Opt out date of employee from Kiwisaver
Mandatory if kiwiSaverStatus is Opted Out Address Line 1, City and Post Code are mandatory if an Opt Out Date exists
existingKiwiSaverMember Boolean Indication of whether employee is existing KiwiSaver member. This attribute is legacy as of 21-Nov-2018.
specialTax Number Special tax rate of the emploee
specialStudentLoan Number Special Student Loan rates of the employee
specialEarnerLevy Number Special Earner Levy rate of the employee
specialExtraPayRate Number Special Extra Pay Rate of the employee
helpDebt Boolean HELP Debt
sfssDebt Boolean SFSS Debt
medicareLevyVariationDeclaration Boolean Has the employee filled a Medicare levy variation declaration
hasSpouse Boolean Spouse
incomeLessThanRelevantAmount Boolean Is the combined weekly income of payee and payee's spouse, or the payee's income as a sole parent, less than the relevant amount in table A
payrollTaxExempt Boolean Payroll Tax Exempt
dependentChildren Number Number of dependent children of the employee
surchargeIncrease Number Surcharge increase
proprietorStatus String Proprietor Status of the employee. Description is supported.
NZ
Code Description
NO 0, no, no (employee)
YES 1, yes
NA 2, n/a, na, n/a (company/contractor)
AU
Code Description
NA 0, no, company/contractor
NO 1, yes, employee
LABOUR_HIRE 2, labour, labour hire
FOREIGN_EMPLOYMENT (AU only) 3, foreign, foreign employment
contractorsAbn String Contractors ABN
address arrow_drop_down 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
Code Description
RDP Relevant Daily Pay
ADP Average Daily Pay
holidayCalendar String Applicable public holiday calendar
defineSetHoursPerDay Boolean Define set hours per day
True if standard hours exist for any day
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
Description Related attributes
New Member  
Pre-existing member  
Opted Out kiwiSaverOptOutDate, addressLine1, city and postCode are mandatory for this status
Savings Suspension - IRD Approved kiwisaverHolidayEndDate is mandatory for this status
Savings Suspension - IRD Approved with Employer Subsidy kiwisaverHolidayEndDate is mandatory for this status
Not Eligible kiwiSaverRate must be 0.00
Not a Member kiwiSaverRate must be 0.00
employerSubsidy must be 0.00
Used when no other KiwiSaver status applies
timecardEmployeeSettingsarrow_drop_down JSON Object A JSON object representing the standard hours worked each day

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.

Parameters
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
email 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:
Name Code Description
WEEKLY W Weekly
FORTNIGHTLY F Fortnightly
MONTHLY M Monthly
BI_MONTHLY B Bi-Monthly
FOUR_WEEKLY 4 4-Weekly
WEEKLY_2 W2 Weekly (2)
FORTNIGHTLY_2 F2 Fortnightly (2)
MONTHLY_2 M2 Monthly (2)
BI_MONTHLY_2 B2 Bi-Monthly (2)
FOUR_WEEKLY_2 42 4-Weekly (2)
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.
Code Description
ACT Australian Capital Territory
NSW New South Wales
NT Northern Territory
QLD Queensland
SA South Australia
TAS Tasmania
VIC Victoria
WA Western Australia
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
paymentMethod Yes String Method of the employee is being paid. Code and Description are supported.
Code Description
BANK Bank
CASH Cash
CHEQUE Cheque
bankAccountNumber Yes String Bank account number of the employee
taxNumber Yes String Tax number of the employee
finishDate No String Final Pay day of the employee
terminationReason No String Termination reason of the employee
deathBenefitSurname No String Death beneficiaries Surname
deathBenefitFirstName No String Death beneficiaries First Name
deathBenefitRecipient No String Death benefit recipient
taxCode Yes String New Zealand Tax Code of the employee
taxScale Yes String Australian Tax scale of the employee
kiwiSaverRate Yes Number Kiwisaver Employee Contribution rate of the employee
employerSubsidy Yes Number Employer's subsidy rate for Kiwisaver
esctRate Yes Number Tax rate that will be deducted from Superannuation Employer Contribution
kiwiSaverOptOutDate No String Opt out date of employee from Kiwisaver
Mandatory if kiwiSaverStatus is Opted Out Address Line 1, City and Post Code are mandatory if an Opt Out Date exists
existingKiwiSaverMember No Boolean Indication of whether employee is existing KiwiSaver member. This attribute is legacy as of 21-Nov-2018.
specialTax No Number Special tax rate of the emploee
specialStudentLoan No Number Special Student Loan rates of the employee
specialEarnerLevy No Number Special Earner Levy rate of the employee
specialExtraPayRate No Number Special Extra Pay Rate of the employee
helpDebt No Boolean HELP Debt
sfssDebt No Boolean SFSS Debt
medicareLevyVariationDeclaration No Boolean Has the employee filled a Medicare levy variation declaration
hasSpouse No Boolean Spouse
incomeLessThanRelevantAmount No Boolean Is the combined weekly income of payee and payee's spouse, or the payee's income as a sole parent, less than the relevant amount in table A
payrollTaxExempt No Boolean Payroll Tax Exempt
dependentChildren No Number Number of dependent children of the employee
surchargeIncrease No Number Surcharge increase
proprietorStatus No String Proprietor Status of the employee. Description is supported.
NZ
Code Description
NO 0, no, no (employee)
YES 1, yes
NA 2, n/a, na, n/a (company/contractor)
AU
Code Description
NA 0, no, company/contractor
NO 1, yes, employee
LABOUR_HIRE 2, labour, labour hire
FOREIGN_EMPLOYMENT (AU only) 3, foreign, foreign employment
contractorsAbn No String Contractors ABN
address arrow_drop_down 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 Daily pay type, when Average Daily Pay is enabled. Code is supported
Code Description
RDP Relevant Daily Pay
ADP Average Daily Pay
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
Description Related attributes
New Member  
Pre-existing member  
Opted Out kiwiSaverOptOutDate, addressLine1, city and postCode are mandatory for this status
Savings Suspension - IRD Approved kiwisaverHolidayEndDate is mandatory for this status
Savings Suspension - IRD Approved with Employer Subsidy kiwisaverHolidayEndDate is mandatory for this status
Not Eligible kiwiSaverRate must be 0.00
Not a Member kiwiSaverRate must be 0.00
Used when no other KiwiSaver status applies
timecardEmployeeSettingsarrow_drop_down No JSON Object A JSON object representing the standard hours worked each day

POST /api/v1/employees

Request Body Example

[
   {
      "id":"myCustomId",
      "surname":"iPayroll",
      "firstNames":"Jackie",
      "address":{
         "country":"New Zealand"
      },
      "startDate":"1-May-2014",
      "email":"email@email.com",
      "gender":"Female",
      "payFrequency":"Fortnightly",
      "fullTimeHoursWeek":33
   }
   ...
]

Response Example

[
   {
      "id":"myCustomId",
      "firstNames":"Jackie",
      "address":{
         "country":"New Zealand"
      },
      "startDate":"1-May-2014",
      "email":"email@email.com",
      "gender":"Female",
      "payFrequency":"Fortnightly",
      "fullTimeHoursWeek":33,
      "organisation":10000,
      "links":[
         {
            "rel":"self",
            "href":"https://secure2.ipayroll.co.nz/api/v1/employees/1111"
         },
         {
            "rel":"payrate",
            "href":"https://secure2.ipayroll.co.nz/api/v1/employees/1111/payrates"
         },
         {
            "rel":"timesheet",
            "href":"https://secure2.ipayroll.co.nz/api/v1/timesheets/1111"
         },
         {
            "rel":"customField",
            "href":"https://secure2.ipayroll.co.nz/api/v1/employees/1111/customfields"
         }
      ]
   }
]

PUT /api/v1/employees/{employeeId}

Update an employee

(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.

Parameters
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
email 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:
Name Code Description
WEEKLY W Weekly
FORTNIGHTLY F Fortnightly
MONTHLY M Monthly
BI_MONTHLY B Bi-Monthly
FOUR_WEEKLY 4 4-Weekly
WEEKLY_2 W2 Weekly (2)
FORTNIGHTLY_2 F2 Fortnightly (2)
MONTHLY_2 M2 Monthly (2)
BI_MONTHLY_2 B2 Bi-Monthly (2)
FOUR_WEEKLY_2 42 4-Weekly (2)
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.
Code Description
ACT Australian Capital Territory
NSW New South Wales
NT Northern Territory
QLD Queensland
SA South Australia
TAS Tasmania
VIC Victoria
WA Western Australia
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
paymentMethod Yes String Method of the employee is being paid. Code and Description are supported.
Code Description
BANK Bank
CASH Cash
CHEQUE Cheque
bankAccountNumber Yes String Bank account number of the employee
taxNumber Yes String Tax number of the employee
finishDate No String Final Pay day of the employee
terminationReason No String Termination reason of the employee
deathBenefitSurname No String Death beneficiaries Surname
deathBenefitFirstName No String Death beneficiaries First Name
deathBenefitRecipient No String Death benefit recipient
taxCode Yes String New Zealand Tax Code of the employee
taxScale Yes String Australian Tax scale of the employee
kiwiSaverRate Yes Number Kiwisaver Employee Contribution rate of the employee
employerSubsidy Yes Number Employer's subsidy rate for Kiwisaver
esctRate Yes Number Tax rate that will be deducted from Superannuation Employer Contribution
kiwiSaverOptOutDate No String Opt out date of employee from Kiwisaver
Mandatory if kiwiSaverStatus is Opted Out Address Line 1, City and Post Code are mandatory if an Opt Out Date exists
existingKiwiSaverMember No Boolean Indication of whether employee is existing KiwiSaver member. This attribute is legacy as of 21-Nov-2018.
specialTax No Number Special tax rate of the emploee
specialStudentLoan No Number Special Student Loan rates of the employee
specialEarnerLevy No Number Special Earner Levy rate of the employee
specialExtraPayRate No Number Special Extra Pay Rate of the employee
helpDebt No Boolean HELP Debt
sfssDebt No Boolean SFSS Debt
medicareLevyVariationDeclaration No Boolean Has the employee filled a Medicare levy variation declaration
hasSpouse No Boolean Spouse
incomeLessThanRelevantAmount No Boolean Is the combined weekly income of payee and payee's spouse, or the payee's income as a sole parent, less than the relevant amount in table A
payrollTaxExempt No Boolean Payroll Tax Exempt
dependentChildren No Number Number of dependent children of the employee
surchargeIncrease No Number Surcharge increase
proprietorStatus No String Proprietor Status of the employee. Description is supported.
NZ
Code Description
NO 0, no, no (employee)
YES 1, yes
NA 2, n/a, na, n/a (company/contractor)
AU
Code Description
NA 0, no, company/contractor
NO 1, yes, employee
LABOUR_HIRE 2, labour, labour hire

FOREIGN_EMPLOYMENT (AU only)

 3, foreign, foreign employment
contractorsAbn No String Contractors ABN
address arrow_drop_down 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 Daily pay type, when Average Daily Pay is enabled. Code is supported
Code Description
RDP Relevant Daily Pay
ADP Average Daily Pay
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
Description Related attributes
New Member  
Pre-existing member  
Opted Out kiwiSaverOptOutDate, addressLine1, city and postCode are mandatory for this status
Savings Suspension - IRD Approved kiwisaverHolidayEndDate is mandatory for this status
Savings Suspension - IRD Approved with Employer Subsidy kiwisaverHolidayEndDate is mandatory for this status
Not Eligible kiwiSaverRate must be 0.00
Not a Member kiwiSaverRate must be 0.00
Used when no other KiwiSaver status applies
timecardEmployeeSettingsarrow_drop_up No JSON Object A JSON object representing the standard hours worked each day
monStandardHours No Number Monday standard hours
tueStandardHours No Number Tuesday standard hours
wedStandardHours No Number Wednesday standard hours
thuStandardHours No Number Thursday standard hours
friStandardHours No Number Friday standard hours
satStandardHours No Number Saturday standard hours
sunStandardHours No Number Sunday standard hours

PUT /api/v1/employees/{employeeId}

Request Body Example

{
   "id":"newCustomId",
   "surname":"Caroline",
   "firstNames":"Jackie",
   "preferredName":"Jackie",
   "address":{
      "addressLine1":"10 Leinster St",
      "addressLine2":"abc",
      "suburb":"suburb",
      "city":"Wellington",
      "postCode":"6611",
      "country":"New Zealand"
   },
   "startDate":"18-Jul-2017",
   "birthDate":"03-Jul-1992",
   "paidToDate":"31-Dec-2017",
   "defaultCostCentre":"CostCenter",
   "userDefinedGroup":"AAAA",
   "email":"email@gmail.com",
   "phone":"0123456786",
   "title":"SSE",
   "gender":"Male",
   "payFrequency":"Weekly",
   "fullTimeHoursWeek":10,
   "paymentMethod":"Bank",
   "bankAccountNumber":"123456789",
   "taxNumber":"00-000-000",
   "taxCode":"A",
   "kiwiSaverRate":4,
   "employerSubsidy":4.2,
   "esctRate":17.5,
   "kiwiSaverOptOutDate":"26-Dec-2017",
   "existingKiwiSaverMember":false,
   "specialTax":2.7,
   "specialStudentLoan":1.2,
   "specialEarnerLevy":0.3,
   "specialExtraPayRate":"HIGH",
   "proprietorStatus":"Yes",
   "holidayCalendar":"Wellington",
   "defineSetHoursPerDay":true,
   "nonResidentEntertainer":true,
   "kiwisaverHolidayEndDate":"28-Jan-2018",
   "notSuppliedAddress":true,
   "notSuppliedDateOfBirth":true,
   "kiwiSaverStatus":"Pre-existing member",
   "timecardEmployeeSettings":{
      "monStandardHours":7,
      "tueStandardHours":7,
      "wedStandardHours":3,
      "thuStandardHours":8,
      "friStandardHours":6,
      "satStandardHours":0,
      "sunStandardHours":0
   }
}

Response Example

{  
   "id":"newCustomId",
   "surname":"Caroline",
   "firstNames":"Jackie",
   "preferredName":"Jackie",
   "address":{  
      "addressLine1":"10 Leinster St",
      "addressLine2":"abc",
      "suburb":"suburb",
      "city":"Wellington",
      "postCode":"6611",
      "country":"New Zealand"
   },
   "startDate":"18-Jul-2017",
   "birthDate":"03-Jul-1992",
   "paidToDate":"31-Dec-2017",
   "defaultCostCentre":"CostCenter", 
   "userDefinedGroup":"AAAA",
   "email":"email@gmail.com",   
   "phone":"0123456786",   
   "title":"SSE",   
   "gender":"Male",
   "payFrequency":"Weekly",   
   "fullTimeHoursWeek":10,   
   "organisation":40000,
   "paymentMethod":"Bank",   
   "bankAccountNumber":"123456789",   
   "taxNumber":"00-000-000",   
   "taxCode":"A",   
   "kiwiSaverRate":4,   
   "employerSubsidy":4.2,   
   "esctRate":17.5,   
   "kiwiSaverOptOutDate":"26-Dec-2017",   
   "existingKiwiSaverMember":false,   
   "specialTax":2.7,
   "specialStudentLoan":1.2,
   "specialEarnerLevy":0.3,
   "specialExtraPayRate":"HIGH",
   "proprietorStatus":"Yes",
   "holidayCalendar":"Wellington",
   "defineSetHoursPerDay":true,
   "nonResidentEntertainer":true,
   "kiwisaverHolidayEndDate":"28-Jan-2018",
   "notSuppliedAddress":true,
   "notSuppliedDateOfBirth":true,
   "kiwiSaverStatus":"Pre-existing member",
   "timecardEmployeeSettings":{
      "monStandardHours":7,
      "tueStandardHours":7,
      "wedStandardHours":3,
      "thuStandardHours":8,
      "friStandardHours":6,
      "satStandardHours":0,
      "sunStandardHours":0
   },
   "links":[  
      {  
         "rel":"self",
         "href":"https://secure2.ipayroll.co.nz/api/v1/employees/12345"
      },
      {  
         "rel":"payrate",
         "href":"https://secure2.ipayroll.co.nz/api/v1/employees/12345/payrates"
      },
      {  
         "rel":"timesheet",
         "href":"https://secure2.ipayroll.co.nz/api/v1/timesheets/12345"
      },
      {  
         "rel":"customField",
         "href":"https://secure2.ipayroll.co.nz/api/v1/employees/12345/customfields"
      }
   ]
}

GET /api/v1/employees

Retrieve all employees

(Scope: employees)

Returns all the active employees of an organisation.

GET /api/v1/employees

Response Example

{
   "links":[
      {
         "rel":"first",
         "href":"https://secure2.ipayroll.co.nz/api/v1/employees/?page=0&size=20"
      },
      {
         "rel":"self",
         "href":"https://secure2.ipayroll.co.nz/api/v1/employees/"
      },
      {
         "rel":"next",
         "href":"https://secure2.ipayroll.co.nz/api/v1/employees/?page=1&size=20"
      },
      {
         "rel":"last",
         "href":"https://secure2.ipayroll.co.nz/api/v1/employees/?page=5&size=20"
      }
   ],
   "content":[
      {
         "id":"12345",
         "surname":"Caroline",
         "firstNames":"Jackie",
         "preferredName":"Jackie",
         "address":{
            "addressLine1":"10 Leinster St",
            "addressLine2":"abc",
            "suburb":"suburb",
            "city":"Wellington",
            "state": "",
            "stateName": ""
            "postCode":"6611",
            "country":"New Zealand"
         },
         "startDate":"18-Jul-2017",
         "birthDate":"03-Jul-1992",
         "paidToDate":"31-Dec-2017",
         "defaultCostCentre":"CostCenter",
         "userDefinedGroup":"AAAA",
         "email":"email@gmail.com",
         "phone":"0123456786",
         "title":"SSE",
         "gender":"Male",
         "payFrequency":"Weekly",
         "fullTimeHoursWeek":10,
         "organisation":40000,
         "paymentMethod":"Bank",
         "bankAccountNumber":"123456789",
         "taxNumber":"00-000-000",
         "taxCode":"A",
         "kiwiSaverRate":4,
         "employerSubsidy":4.2,
         "esctRate":17.5,
         "kiwiSaverOptOutDate":"26-Dec-2017",
         "existingKiwiSaverMember":false,
         "specialTax":2.7,
         "specialStudentLoan":1.2,
         "specialEarnerLevy":0.3,
         "specialExtraPayRate":"HIGH",
         "proprietorStatus":"Yes",
         "daysPerPeriod": 5,
         "dailyPayType": "ADP",
         "holidayCalendar":"Wellington",
         "defineSetHoursPerDay":true,
         "nonResidentEntertainer":true,
         "kiwisaverHolidayEndDate":"28-Jan-2018",
         "notSuppliedAddress":true,
   		 "notSuppliedDateOfBirth":true,
         "kiwiSaverStatus":"Pre-existing member",
         "timecardEmployeeSettings":{
            "monStandardHours":7,
            "tueStandardHours":7,
            "wedStandardHours":3,
            "thuStandardHours":8,
            "friStandardHours":6,
            "satStandardHours":0,
            "sunStandardHours":0
         },
         "links":[
            {
               "rel":"self",
               "href":"https://secure2.ipayroll.co.nz/api/v1/employees/12345"
            },
            {
               "rel":"payrate",
               "href":"https://secure2.ipayroll.co.nz/api/v1/employees/12345/payrates"
            },
            {
               "rel":"timesheet",
               "href":"https://secure2.ipayroll.co.nz/api/v1/timesheets/12345"
            },
            {
               "rel":"customField",
               "href":"https://secure2.ipayroll.co.nz/api/v1/employees/12345/customfields"
            }
         ]
      }
   ],
   "page":{
      "size":20,
      "totalElements":114,
      "totalPages":6,
      "number":0
   }
}

GET /api/v1/employees/{employeeId}

Retrieve an employee's details

(Scope: employees)

Returns an employee.

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}

Response Example

{  
   "id":"12345",
   "surname":"Caroline",
   "firstNames":"Jackie",
   "preferredName":"Jackie",
   "address":{  
      "addressLine1":"10 Leinster St",
      "addressLine2":"abc",
      "suburb":"suburb",
      "city":"Wellington",
      "state": "",
      "stateName": ""
      "postCode":"6611",
      "country":"New Zealand"
   },
   "startDate":"18-Jul-2017",
   "birthDate":"03-Jul-1992",
   "paidToDate":"31-Dec-2017",
   "defaultCostCentre":"CostCenter", 
   "userDefinedGroup":"AAAA",
   "email":"email@gmail.com",   
   "phone":"0123456786",   
   "title":"SSE",   
   "gender":"Male",
   "payFrequency":"Weekly",   
   "fullTimeHoursWeek":10,   
   "organisation":40000,
   "paymentMethod":"Bank",   
   "bankAccountNumber":"123456789",   
   "taxNumber":"00-000-000",   
   "taxCode":"A",   
   "kiwiSaverRate":4,   
   "employerSubsidy":4.2,   
   "esctRate":17.5,   
   "kiwiSaverOptOutDate":"26-Dec-2017",   
   "existingKiwiSaverMember":false,   
   "specialTax":2.7,
   "specialStudentLoan":1.2,
   "specialEarnerLevy":0.3,
   "specialExtraPayRate":"HIGH",
   "proprietorStatus":"Yes",
   "daysPerPeriod": 5,
   "dailyPayType": "ADP",
   "holidayCalendar":"Wellington",
   "defineSetHoursPerDay":true,
   "nonResidentEntertainer":true,
   "kiwisaverHolidayEndDate":"28-Jan-2018",
   "notSuppliedAddress":true,
   "notSuppliedDateOfBirth":true,
   "kiwiSaverStatus":"Pre-existing member",
   "timecardEmployeeSettings":{
      "monStandardHours":7,
      "tueStandardHours":7,
      "wedStandardHours":3,
      "thuStandardHours":8,
      "friStandardHours":6,
      "satStandardHours":0,
      "sunStandardHours":0
   },	
   "links":[  
      {  
         "rel":"self",
         "href":"https://secure2.ipayroll.co.nz/api/v1/employees/12345"
      },
      {  
         "rel":"payrate",
         "href":"https://secure2.ipayroll.co.nz/api/v1/employees/12345/payrates"
      },
      {  
         "rel":"timesheet",
         "href":"https://secure2.ipayroll.co.nz/api/v1/timesheets/12345"
      },
      {  
         "rel":"customField",
         "href":"https://secure2.ipayroll.co.nz/api/v1/employees/12345/customfields"
      }
   ]
}

Pay Rates

Pay rates define the expected base rate that will be used in paying a Person. A divisor is used to identify whether the rate is an hourly or annual type, and holds the formula to convert the rate between hourly and annual as required.

Attributes
Name Type Description
id String Unique ID to identify a payrate
code String Indicates the position of the rate on Personal Details
rate Number Value of pay rate as entered in iPayroll
divisor String If an organisation specific divisor is associated, this field would contain the name of it. If not, a global divisor's name, e.g. "per hour", "per annum", "pa (Govt: 14/365th's)" or "pa (Aust: 12/313th's)".
payScale String Pay Scales are designed to allow pay rates to be set up under a code that can then be used for multiple people. Displayed if Pay Scales are used and a Pay Scale is selected for employee, e.g. K1P107.
annualRate Number Conversion of “rate” to an annualised rate using rules in divisor, e.g. 25 * 2080 = 52,000
hourlyRate Number Conversion of “rate” to an hourly rate using rules in divisor e.g. 52,000 / 2080 = $25

GET /api/v1/employees/{employeeId}/payrates

Retrieve all of an employee’s pay rates

(Scopes: payrates employees)

Returns details of all pay rates associated with an employee.

Parameters
Name Required Type Description
employeeId Yes String Unique ID to identify an employee within an organisation.
Limited to a-z, A-Z, 0-9, _ (underscore) and - (hyphen).

GET /api/v1/employees/{employeeId}/payrates

Response Example

{
    "links": [ 
        { 
            "rel": "self", 
            "href": "https://secure2.ipayroll.co.nz/api/v1/employees/1111/payrates" 
        } 
    ],
    "content": [
        {
            "id": "1",
            "code": "1",
            "hourlyRate": 14.25,
            "annualRate": 29640,
            "rate": 14.25,
            "divisor": "per hour",
            "links": [
                {
                    "rel":"self",
                    "href":"https://secure2.ipayroll.co.nz/api/v1/employees/1111/payrates/1"
                },
                {
                    "rel":"employee",
                    "href":"https://secure2.ipayroll.co.nz/api/v1/employees/1111"
                }
            ]
        },
        ...
    ],
    "page": {
        "size": 20,
        "totalElements": 5,
        "totalPages": 1,
        "number": 0
    }
}

GET /api/v1/employees/{employeeId}/payrates/{payrateId}

Retrieve a specific pay rate for an employee

(Scopes: payrates employees)

Returns details of a particular pay rate of an employee.

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).
payrateId Yes String Unique ID to identify a pay rate

GET /api/v1/employees/{employeeId}/payrates/{code}

Response Example

{
    "id": "1",
    "code": "1",
    "hourlyRate": 14.25,
    "annualRate": 29640,
    "rate": 14.25,
    "divisor": "per hour",
    "links": [
        {
            "rel":"self",
            "href":"https://secure2.ipayroll.co.nz/api/v1/employees/1111/payrates/1"
        }
    ]
}

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.

Parameters
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.

PUT /api/v1/employees/{employeeId}/payrates/{code}

Request Body Example

{
    "rate": 40000,
    "divisor": "per annum"
}

Response Example

{
    "hourlyRate": 19.231,
    "annualRate": 40000,
    "rate": 40000,
    "code": "111",
    "divisor": "per annum",
    "usePayScale": false,
    "links": [
        {
            "rel": "self",
            "href": "http://localhost:8080/api/v1/employees/654004/payrates/111"
        },
        {
            "rel": "employee",
            "href": "http://localhost:8080/api/v1/employees/111111"
        }
    ],
    "id": "111"
}

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 Date The start date of the pay period
paidToDate Date The end date of the pay period
message String A message to be appended to the employee payslip
transactions arrow_drop_down JSON Object List of timesheet transactions for the employee

GET /api/v1/timesheets

Retrieve all of timesheets in the latest payroll

(Scope: timesheets)

Returns all timesheets associated with the latest payroll of an organisation.

GET /api/v1/timesheets

Response Example

{
  "content":[
    {
      "links": [
        {
          "rel": "self",
          "href": "https://secure2.ipayroll.co.nz/api/v1/timesheets/123456"
        }
      ],
      "id": "123456",
      "employeeId": "123456",
      "totalHours": 40,
      "paidToDate": "12-Nov-2016",
      "paidFromDate": "04-Aug-2015",
      "transactions": [
        {
          "links": [],
          "timesheetTransactionId": 993590,
          "amount": 0,
          "quantity": 1,
          "rate": 0,
          "description": "BANK - Take Home Pay to BANK_NUMBER",
          "costCentre": "",
          "payElement": "BANK"
        },
        {
          "links": [],
          "timesheetTransactionId": 993589,
          "amount": 0,
          "quantity": 1,
          "rate": 0,
          "description": "WT - Withholding Tax to TAX_NUMBER",
          "costCentre": "",
          "payElement": "WT"
        },
        ...
      ]
    }
  ],
  "links": [
    {
      "rel": "first",
      "href": "https://secure2.ipayroll.co.nz/api/v1/timesheets?page=0&size=20"
    },
    {
      "rel": "self",
      "href": "https://secure2.ipayroll.co.nz/api/v1/timesheets"
    },
    {
      "rel": "next",
      "href": "https://secure2.ipayroll.co.nz/api/v1/timesheets?page=1&size=20"
    },
    {
      "rel": "last",
      "href": "https://secure2.ipayroll.co.nz/api/v1/timesheets?page=3&size=20"
    }
  ],
  "page": {
    "size": 20,
    "totalElements": 75,
    "totalPages": 4,
    "number": 0
  }
}

GET /api/v1/timesheets/{timesheetId}

Retrieve an employee's latest timesheet

(Scope: timesheets)

Returns the latest timesheet of an employee.

Parameters
Name Required Type Description
timesheetId Yes String Unique ID to identify a timesheet. employeeId can be used.

GET /api/v1/timesheets/{timesheetId}

Response Example

{
  {
    "id": "123456",
    "employeeId": "123456",
    "totalHours": 40,
    "paidToDate": "12-Nov-2016",
    "paidFromDate": "04-Aug-2015",
    "transactions": [
      {
        "links": [],
        "timesheetTransactionId": 993590,
        "amount": 0,
        "quantity": 1,
        "rate": 0,
        "description": "BANK - Take Home Pay to BANK_NUMBER",
        "costCentre": "",
        "payElement": "BANK"
      },
      {
        "links": [],
        "timesheetTransactionId": 993589,
        "amount": 0,
        "quantity": 1,
        "rate": 0,
        "description": "WT - Withholding Tax to TAX_NUMBER",
        "costCentre": "",
        "payElement": "WT"
      }
    ],
    "links": [
      {
        "rel": "self",
        "href": "https://secure2.ipayroll.co.nz/api/v1/timesheets/123456"
      },
      {
        "rel": "employee",
        "href": "https://secure2.ipayroll.co.nz/api/v1/employees/123456"
      }
    ]
  }
  ...
}

GET /api/v1/payrolls/{payrollId}/timesheets

Retrieve all of timesheets in the specific payroll

(Scopes: timesheets payrolls)

Returns all timesheets associated with the specific payroll of an organisation.

Parameters
Name Required Type Description
payrollId Yes String Unique ID to identify a payroll within an organisation

GET /api/v1/payrolls/{payrollId}/timesheets

Response Example

{
  "content":[
    {
      "links": [
        {
          "rel": "self",
          "href": "https://secure2.ipayroll.co.nz/api/v1/payrolls/0030/timesheets"
        }
      ],
      "id": "123456",
      "employeeId": "123456",
      "totalHours": 40,
      "paidToDate": "12-Nov-2016",
      "paidFromDate": "04-Aug-2015",
      "transactions": [
        {
          "links": [],
          "timesheetTransactionId": 993590,
          "amount": 0,
          "quantity": 1,
          "rate": 0,
          "description": "BANK - Take Home Pay to BANK_NUMBER",
          "costCentre": "",
          "payElement": "BANK"
        },
        {
          "links": [],
          "timesheetTransactionId": 993589,
          "amount": 0,
          "quantity": 1,
          "rate": 0,
          "description": "WT - Withholding Tax to TAX_NUMBER",
          "costCentre": "",
          "payElement": "WT"
        },
        ...
      ]
    }
  ],
  "links": [
    {
      "rel": "first",
      "href": "https://secure2.ipayroll.co.nz/api/v1/payrolls/0030/timesheets?page=0&size=20"
    },
    {
      "rel": "self",
      "href": "https://secure2.ipayroll.co.nz/api/v1/payrolls/0030/timesheets"
    },
    {
      "rel": "next",
      "href": "https://secure2.ipayroll.co.nz/api/v1/payrolls/0030/timesheets?page=1&size=20"
    },
    {
      "rel": "last",
      "href": "https://secure2.ipayroll.co.nz/api/v1/payrolls/0030/timesheets?page=3&size=20"
    }
  ],
  "page": {
    "size": 20,
    "totalElements": 75,
    "totalPages": 4,
    "number": 0
  }
}

GET /api/v1/payrolls/current/timesheets

Retrieve all timesheets in the current payroll

(Scopes: timesheets payrolls)

Returns all timesheets associated with the current payroll of an organisation.

GET /api/v1/payrolls/current/timesheets

Response Example

{
  "content":[
    {
      "links": [
        {
          "rel": "self",
          "href": "https://secure2.ipayroll.co.nz/api/v1/payrolls/0030/timesheets"
        }
      ],
      "id": "123456",
      "employeeId": "123456",
      "totalHours": 40,
      "paidToDate": "12-Nov-2016",
      "paidFromDate": "04-Aug-2015",
      "transactions": [
        {
          "links": [],
          "timesheetTransactionId": 993590,
          "amount": 0,
          "quantity": 1,
          "rate": 0,
          "description": "BANK - Take Home Pay to BANK_NUMBER",
          "costCentre": "",
          "payElement": "BANK"
        },
        {
          "links": [],
          "timesheetTransactionId": 993589,
          "amount": 0,
          "quantity": 1,
          "rate": 0,
          "description": "WT - Withholding Tax to TAX_NUMBER",
          "costCentre": "",
          "payElement": "WT"
        },
        ...
      ]
    }
  ],
  "links": [
    {
      "rel": "first",
      "href": "https://secure2.ipayroll.co.nz/api/v1/payrolls/0030/timesheets?page=0&size=20"
    },
    {
      "rel": "self",
      "href": "https://secure2.ipayroll.co.nz/api/v1/payrolls/0030/timesheets"
    },
    {
      "rel": "next",
      "href": "https://secure2.ipayroll.co.nz/api/v1/payrolls/0030/timesheets?page=1&size=20"
    },
    {
      "rel": "last",
      "href": "https://secure2.ipayroll.co.nz/api/v1/payrolls/0030/timesheets?page=3&size=20"
    }
  ],
  "page": {
    "size": 20,
    "totalElements": 75,
    "totalPages": 4,
    "number": 0
  }
}

GET /api/v1/payrolls/{payrollId}/timesheets/{timesheetId}

Retrieve an employee's timesheet in the specific payroll

(Scopes: timesheets payrolls)

Returns employee's timesheet associated with the specific payroll of an organisation.

Parameters
Name Required Type Description
payrollId Yes String Unique ID to identify a payroll within an organisation
timesheetId Yes String Unique ID to identify a timesheet. employeeId can be used.

GET /api/v1/payrolls/{payrollId}/timesheets/{timesheetId}

Response Example

{
  {
    "id": "123456",
    "employeeId": "123456",
    "totalHours": 40,
    "paidToDate": "12-Nov-2016",
    "paidFromDate": "04-Aug-2015",
    "transactions": [
      {
        "links": [],
        "timesheetTransactionId": 993590,
        "amount": 0,
        "quantity": 1,
        "rate": 0,
        "description": "BANK - Take Home Pay to BANK_NUMBER",
        "costCentre": "",
        "payElement": "BANK"
      },
      {
        "links": [],
        "timesheetTransactionId": 993589,
        "amount": 0,
        "quantity": 1,
        "rate": 0,
        "description": "WT - Withholding Tax to TAX_NUMBER",
        "costCentre": "",
        "payElement": "WT"
      }
    ],
    "links": [
      {
        "rel": "self",
        "href": "https://secure2.ipayroll.co.nz/api/v1/payrolls/0014/timesheets/123456"
      },
      {
        "rel": "employee",
        "href": "https://secure2.ipayroll.co.nz/api/v1/payrolls/0014/timesheets/123456"
      }
    ]
  }
  ...
}

GET /api/v1/payrolls/current/timesheets/{timesheetId}

Retrieve an employee's timesheet in the current payroll

(Scopes: timesheets payrolls)

Returns employee's timesheet associated with the current payroll of an organisation.

Parameters
Name Required Type Description
timesheetId Yes String Unique ID to identify a timesheet. employeeId can be used.

GET /api/v1/payrolls/current/timesheets/{timesheetId}

Response Example

{
  {
    "id": "123456",
    "employeeId": "123456",
    "totalHours": 40,
    "paidToDate": "12-Nov-2016",
    "paidFromDate": "04-Aug-2015",
    "transactions": [
      {
        "links": [],
        "timesheetTransactionId": 993590,
        "amount": 0,
        "quantity": 1,
        "rate": 0,
        "description": "BANK - Take Home Pay to BANK_NUMBER",
        "costCentre": "",
        "payElement": "BANK"
      },
      {
        "links": [],
        "timesheetTransactionId": 993589,
        "amount": 0,
        "quantity": 1,
        "rate": 0,
        "description": "WT - Withholding Tax to TAX_NUMBER",
        "costCentre": "",
        "payElement": "WT"
      }
    ],
    "links": [
      {
        "rel": "self",
        "href": "https://secure2.ipayroll.co.nz/api/v1/payrolls/0014/timesheets/123456"
      },
      {
        "rel": "employee",
        "href": "https://secure2.ipayroll.co.nz/api/v1/payrolls/0014/timesheets/123456"
      }
    ]
  }
  ...
}

POST /api/v1/timesheets

Create one or more timesheets

(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.

Parameters
Name Required Type Description
timesheets arrow_drop_down Yes JSON Object List of timesheets to be created

POST /api/v1/timesheets

Request Body Example

[
  {
    "employeeId": "123456",
    "totalHours": 40, 
    "paidToDate": "12-Nov-2016", 
    "paidFromDate": "04-Aug-2015",
    "transactions": [
      {
        "amount": 0,
        "quantity": 1,
        "rate": 0,
        "description": "BANK - Take Home Pay to BANK_NUMBER",
        "costCentre": "",
        "payElement": "BANK"
      },
      {
        "amount": 0,
        "quantity": 1,
        "rate": 0,
        "description": "WT - Withholding Tax to TAX_NUMBER",
        "costCentre": "",
        "payElement": "WT"
      },
      ...
    ]
  }
  ...
]

Response Example

[
  {
    "id": "123456",
    "employeeId": "123456",
    "totalHours": 40,
    "paidToDate": "12-Nov-2016",
    "paidFromDate": "04-Aug-2015",
    "transactions": [
      {
        "links": [],
        "timesheetTransactionId": 993590,
        "amount": 0,
        "quantity": 1,
        "rate": 0,
        "description": "BANK - Take Home Pay to BANK_NUMBER",
        "costCentre": "",
        "payElement": "BANK"
      },
      {
        "links": [],
        "timesheetTransactionId": 993589,
        "amount": 0,
        "quantity": 1,
        "rate": 0,
        "description": "WT - Withholding Tax to TAX_NUMBER",
        "costCentre": "",
        "payElement": "WT"
      },
      ...
    ],
    "links": [
      {
        "rel": "self",
        "href": "https://secure2.ipayroll.co.nz/api/v1/timesheets/123456"
      },
      {
        "rel": "employee",
        "href": "https://secure2.ipayroll.co.nz/api/v1/employees/123456"
      }
    ]
  }
  ...
]

DELETE /api/v1/timesheets/{timesheetId}/transactions/{timesheetTransactionId}

Delete a timesheet transaction in the current payroll of an organisation

(Scope: timesheets)

The current payroll must be open.

Parameters
Name Required Type Description
timesheetId Yes String Unique ID to identify a timesheet. employeeId can be used.
timesheetTransactionId Yes Long Unique ID to identify a timesheet transaction

DELETE /api/v1/timesheets/{employeeId}/transactions/{timesheetTransactionId}

Empty response.

Leave Balances

A timesheet is a collection of all payments and deductions for a person paid in a single pay.

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 Date First day of leave
leaveToDate Date Last day of leave
reason String Reason for leave
status String Processing status of a leave request. The status can be one of the following:
  • Pending
  • Approved
  • Declined
  • Cancelled
  • Closed
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_down 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/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.

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

Response Example

{
 "links": [
   {
     "rel": "self",
     "href": "https://secure2.ipayroll.co.nz/api/v1/employees/1/leaves/balances"
   }
 ],
 "content": [
 {
  "links": [
    {
      "rel": "self",
      "href": "https://secure2.ipayroll.co.nz/api/v1/employees/1/leaves/balances/ACC%20Leave"
    },
    {
      "rel": "employee",
      "href": "https://secure2.ipayroll.co.nz/api/v1/employees/1"
    }
  ],
  "id": "ACC Leave",
  "employeeId": "1",
  "entitled": 0,
  "accrued": 0,
  "taken": 8,
  "balance": -8,
  "leaveBalanceType": {
    "leaveType": "ACC First Week",
    "name": "ACC Leave",
    "unit": "hours",
    "organisationSpecific":false
  },
  "nextAnniversaryDate": "31-May-2017",
  "lastAnniversaryDate": "31-May-2016",
  "approvedQuantity": 1
},
   ...
 ],
 "page": {
   "size": 5,
   "totalElements": 5,
   "totalPages": 1,
   "number": 0
 }
}

GET /api/v1/employees/{employeeId}/leaves/balances/{leaveBalanceId}

Retrieve a specific leave balance for an employee

(Scopes: leavebalances employees)

Returns details of a particular leave balance of an employee.

Parameters
Name Required Type Description
employeeId Yes String Unique ID to identify an employee within an organisation.
Limited to a-z, A-Z, 0-9, _ (underscore) and - (hyphen).
leaveBalanceId Yes String Unique ID to identify a leave balance

GET /api/v1/employees/{employeeId}/leaves/balances/{leaveBalanceId}

Response Example

{
  "links": [
    {
      "rel": "self",
      "href": "secure2.ipayroll.co.nz/api/v1/employees/12345/leaves/ACC%20Leave"
    },
    {
      "rel": "employee",
      "href": "secure2.ipayroll.co.nz/api/v1/employees/12345"
    }
  ],
  "id": "ACC Leave",
  "employeeId": "12345",
  "entitled": 0,
  "accrued": 0,
  "taken": 8,
  "balance": -8,
  "leaveBalanceType": {
    "leaveType": "ACC First Week",
    "name": "ACC Leave",
    "unit": "hours",
    "organisationSpecific":false
  },
  "nextAnniversaryDate": "31-May-2017",
  "lastAnniversaryDate": "31-May-2016",
  "approvedQuantity": 1
}

Leave Requests

Attributes
Name Type Description
id Number Unique ID to identify a request
employeeId String Unique ID to identify an employee within an organisation.
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 Date First day of leave
leaveToDate Date Last day of leave
reason String Reason for leave
status String Processing status of a leave request. The status can be one of the following:
  • Pending
  • Approved
  • Declined
  • Cancelled
  • Closed
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_down 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.

Parameters
Name Required Type Description
status No String Processing status of a leave request. The status can be one of the following:
  • Pending
  • Approved
  • Declined
  • Cancelled
  • Closed
leaveBalanceType No String Name of a leave balance type, for example, "Annual Leave", "Sick Leave", "Alternative Holiday"
Sample requests

GET /api/v1/leaves/requests?status=Pending&leaveBalanceType=Annual%20Leave

GET /api/v1/leaves/requests

GET /api/v1/leaves/requests?status=Approved

GET /api/v1/leaves/requests?status={status}&leaveBalanceType={leaveBalanceType}

Response Example

{
   "links":[
      {
         "rel":"self",
         "href":"https://secure2.ipayroll.co.nz/api/v1/leaves/requests?status=Approved&leaveBalanceType=Annual%20Leave"
      }
   ],
   "content":[
      {
         "links":[
            {
               "rel":"self",
               "href":"https://secure2.ipayroll.co.nz/api/v1/leaves/requests/255"
            },
            {
               "rel":"employee",
               "href":"https://secure2.ipayroll.co.nz/api/v1/employees/1"
            },
            {
               "rel":"pay element",
               "href":"https://secure2.ipayroll.co.nz/api/v1/payelements/AALL"
            }
         ],
         "id":255,
         "employeeId":"1",
         "hours":32,
         "leaveFromDate":"07-Mar-2017",
         "leaveToDate":"10-Mar-2017",
         "reason":"Annual Holidays Break",
         "status":"Approved",
         "payElement":"AALL",
         "leaveBalanceType":{
            "leaveType":"Annual",
            "name":"Annual Leave",
            "unit":"hours",
            "organisationSpecific":false
         },
         "payElementId":777,
         "daysConsumed":0,
         "daysCurrent":0,
         "daysRemaining":0,
         "quantityConsumed":8,
         "quantityCurrent":0,
         "quantityRemaining":0,
         "leaveInDays":false
      }
   ],
   "page":{
      "size":20,
      "totalElements":1,
      "totalPages":1,
      "number":0
   }
}

GET /api/v1/leaves/requests/{leaveRequestId}

Retrieve details of a leave request

(Scope: leaverequests)

Returns a leave request.

Parameters
Name Required Type Description
leaveRequestId Yes Number Unique ID to identify a leave request

GET /api/v1/leaves/requests/{leaveRequestId}

Response Example

{
   "links":[
      {
         "rel":"self",
         "href":"https://secure2.ipayroll.co.nz/api/v1/leaves/requests/255"
      },
      {
         "rel":"employee",
         "href":"https://secure2.ipayroll.co.nz/api/v1/employees/1"
      },
      {
         "rel":"pay element",
         "href":"https://secure2.ipayroll.co.nz/api/v1/payelements/AALL"
      }
   ],
   "id":255,
   "employeeId":"1",
   "hours":32,
   "leaveFromDate":"02-Mar-2017",
   "leaveToDate":"10-Mar-2017",
   "reason":"Annual Holidays Break",
   "status":"Approved",
   "payElement":"AALL",
   "leaveBalanceType":{
      "leaveType":"Annual",
      "name":"Annual Leave",
      "unit":"hours",
      "organisationSpecific":false
   },
   "payElementId":777,
   "daysConsumed": 0,
   "daysCurrent": 0,
   "daysRemaining": 0,
   "quantityConsumed": 8,
   "quantityCurrent": 0,
   "quantityRemaining": 0,
   "leaveInDays": false
}

GET /api/v1/leaves/requests/current

Retrieve current leave requests

(Scope: leaverequests)

Returns details of current leave requests (with status ‘Pending’ or ‘Approved’) associated with an organisation.

GET /api/v1/leaves/requests/current

Response Example

{
   "links":[
      {
         "rel":"self",
         "href":"https://secure2.ipayroll.co.nz/api/v1/employees/1/leaves/requests/current"
      }
   ],
   "content":[
      {
         "links":[
            {
               "rel":"self",
               "href":"https://secure2.ipayroll.co.nz/api/v1/leaves/requests/254"
            },
            {
               "rel":"employee",
               "href":"https://secure2.ipayroll.co.nz/api/v1/employees/1"
            },
            {
               "rel":"pay element",
               "href":"https://secure2.ipayroll.co.nz/api/v1/payelements/AAHH"
            }
         ],
         "id":254,
         "employeeId":"1",
         "hours":12,
         "days":3,
         "leaveFromDate":"09-Mar-2017",
         "leaveToDate":"13-Mar-2017",
         "reason":"Holidays",
         "status":"Pending",
         "payElement":"AAHH",
         "leaveBalanceType":{
            "leaveType":"Alternative Holiday",
            "name":"Alternative Holiday",
            "unit":"days",
            "organisationSpecific":false
         },
         "payElementId":888,
         "daysConsumed":0,
         "daysCurrent":1,
         "daysRemaining":0,
         "quantityConsumed":0,
         "quantityCurrent":0,
         "quantityRemaining":0,
         "leaveInDays":true
      },
      {
         "links":[
            {
               "rel":"self",
               "href":"https://secure2.ipayroll.co.nz/api/v1/leaves/requests/255"
            },
            {
               "rel":"employee",
               "href":"https://secure2.ipayroll.co.nz/api/v1/employees/1"
            },
            {
               "rel":"pay element",
               "href":"https://secure2.ipayroll.co.nz/api/v1/payelements/AALL"
            }
         ],
         "id":255,
         "employeeId":"2",
         "hours":24,
         "leaveFromDate":"01-Feb-2017",
         "leaveToDate":"03-Feb-2017",
         "reason":"Annual Holidays Break",
         "status":"Approved",
         "payElement":"AALL",
         "leaveBalanceType":{
            "leaveType":"Annual",
            "name":"Annual Leave",
            "unit":"hours",
            "organisationSpecific":false
         },
         "payElementId":777,
         "daysConsumed":0,
         "daysCurrent":0,
         "daysRemaining":0,
         "quantityConsumed":8,
         "quantityCurrent":0,
         "quantityRemaining":0,
         "leaveInDays":false
      }
   ],
   "page":{
      "size":20,
      "totalElements":2,
      "totalPages":1,
      "number":0
   }
}

GET /api/v1/employees/{employeeId}/leaves/requests

Retrieve all of an employee's leave requests

(Scopes: leaverequests employees)

Returns details of all leave requests associated with an employee.

Parameters
Name Required Type Description
employeeId Yes String Unique ID to identify an employee within an organisation.
Limited to a-z, A-Z, 0-9, _ (underscore) and - (hyphen).
status No String Processing status of a leave request. The status can be one of the following:
  • Pending
  • Approved
  • Declined
  • Cancelled
  • Closed

GET /api/v1/employees/{employeeId}/leaves/requests?status={status}

Response Example

{
   "links":[
      {
         "rel":"self",
         "href":"https://secure2.ipayroll.co.nz/api/v1/employees/1/leaves/requests?status=Pending"
      }
   ],
   "content":[
      {
         "links":[
            {
               "rel":"self",
               "href":"https://secure2.ipayroll.co.nz/api/v1/leaves/requests/254"
            },
            {
               "rel":"employee",
               "href":"https://secure2.ipayroll.co.nz/api/v1/employees/1"
            },
            {
               "rel":"pay element",
               "href":"https://secure2.ipayroll.co.nz/api/v1/payelements/AAHH"
            }
         ],
         "id":254,
         "employeeId":"1",
         "hours":12,
         "days":3,
         "leaveFromDate":"09-Mar-2017",
         "leaveToDate":"13-Mar-2017",
         "reason":"Holidays",
         "status":"Pending",
         "payElement":"AAHH",
         "leaveBalanceType":{
            "leaveType":"Alternative Holiday",
            "name":"Alternative Holiday",
            "unit":"days",
            "organisationSpecific":false
         },
         "payElementId":888,
         "daysConsumed":0,
         "daysCurrent":1,
         "daysRemaining":0,
         "quantityConsumed":0,
         "quantityCurrent":0,
         "quantityRemaining":0,
         "leaveInDays":true
      }
   ],
   "page":{
      "size":20,
      "totalElements":1,
      "totalPages":1,
      "number":0
   }
}

GET /api/v1/employees/{employeeId}/leaves/requests/current

Retrieve current leave requests of an employee

(Scopes: leaverequests employees)

Returns details of current leave requests (with status ‘Pending’ or ‘Approved’) associated with an employee.

Parameters
Name Required Type Description
employeeId Yes String Unique ID to identify an employee within an organisation.
Limited to a-z, A-Z, 0-9, _ (underscore) and - (hyphen).

GET /api/v1/employees/{employeeId}/leaves/requests/current

Response Example

{
   "links":[
      {
         "rel":"self",
         "href":"https://secure2.ipayroll.co.nz/api/v1/employees/1/leaves/requests/current"
      }
   ],
   "content":[
      {
         "links":[
            {
               "rel":"self",
               "href":"https://secure2.ipayroll.co.nz/api/v1/leaves/requests/254"
            },
            {
               "rel":"employee",
               "href":"https://secure2.ipayroll.co.nz/api/v1/employees/1"
            },
            {
               "rel":"pay element",
               "href":"https://secure2.ipayroll.co.nz/api/v1/payelements/AAHH"
            }
         ],
         "id":254,
         "employeeId":"1",
         "hours":12,
         "days":3,
         "leaveFromDate":"09-Mar-2017",
         "leaveToDate":"13-Mar-2017",
         "reason":"Holidays",
         "status":"Pending",
         "payElement":"AAHH",
         "leaveBalanceType":{
            "leaveType":"Alternative Holiday",
            "name":"Alternative Holiday",
            "unit":"days",
            "organisationSpecific":false
         },
         "payElementId":888,
         "daysConsumed":0,
         "daysCurrent":1,
         "daysRemaining":0,
         "quantityConsumed":0,
         "quantityCurrent":0,
         "quantityRemaining":0,
         "leaveInDays":true
      },
      {
         "links":[
            {
               "rel":"self",
               "href":"https://secure2.ipayroll.co.nz/api/v1/leaves/requests/255"
            },
            {
               "rel":"employee",
               "href":"https://secure2.ipayroll.co.nz/api/v1/employees/1"
            },
            {
               "rel":"pay element",
               "href":"https://secure2.ipayroll.co.nz/api/v1/payelements/AALL"
            }
         ],
         "id":255,
         "employeeId":"1",
         "hours":32,
         "leaveFromDate":"02-Mar-2017",
         "leaveToDate":"10-Mar-2017",
         "reason":"Annual Holidays Break",
         "status":"Approved",
         "payElement":"AALL",
         "leaveBalanceType":{
            "leaveType":"Annual",
            "name":"Annual Leave",
            "unit":"hours",
            "organisationSpecific":false
         },
         "payElementId":777,
         "daysConsumed":0,
         "daysCurrent":0,
         "daysRemaining":0,
         "quantityConsumed":8,
         "quantityCurrent":0,
         "quantityRemaining":0,
         "leaveInDays":false
      }
   ],
   "page":{
      "size":20,
      "totalElements":2,
      "totalPages":1,
      "number":0
   }
}

GET /api/v1/employees/{employeeId}/leaves/requests/{requestId}

Retrieve details of a leave request associated with an employee

(Scopes: leaverequests employees)

Returns a leave request.

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

GET /api/v1/employees/{employeeId}/leaves/requests/{requestId}

Response Example

{
   "links":[
      {
         "rel":"self",
         "href":"http://secure2.ipayroll.co.nz/api/v1/employees/1/leaves/requests/255"
      },
      {
         "rel":"employee",
         "href":"http://secure2.ipayroll.co.nz/api/v1/employees/1"
      }
   ],
   "id": 255,
   "employeeId":"1",
   "hours":32,
   "leaveFromDate":"02-Mar-2017",
   "leaveToDate":"10-Mar-2017",
   "reason":"Annual Holidays Break",
   "status":"Approved",
   "payElement":"Annual Leave",
   "leaveBalanceType":{
      "leaveType":"Annual",
      "name":"Annual Leave",
      "unit":"hours",
      "organisationSpecific":false
   },
   "payElementId":50,
   "daysConsumed":0,
   "daysCurrent":0,
   "daysRemaining":0,
   "quantityConsumed":8,
   "quantityCurrent":0,
   "quantityRemaining":0,
   "leaveInDays":false
}

POST /api/v1/leaves/requests

Create a leave request

(Scope: leaverequests)

Create a Leave Request for an employee.

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).
hours Yes * Number Total number of hours of requested leave.
* hours is not mandatory in case that the employee is defined as ADP and the payElement's Leave Balance saved in days e.g Sick, Bereavement
days Yes ** Number Total number of days of requested leave (applies if a leave balance is stored in days)
** days is not mandatory for payElement whose Leave Balance saved in hours e.g Annual, Lieu
leaveFromDate Yes Date First day of leave
leaveToDate Yes Date Last day of leave
reason No String Reason for leave
status Yes String Processing status of a leave request. The status can be one of the following:
  • Pending
  • Approved
  • Declined
  • Cancelled
payElement Yes String Code of pay element that is used to process the request in a payroll


In case of ADP hours or days will be considered based on the payElement's Leave Balance

POST /api/v1/leaves/requests

Request Body Example

{
	"employeeId":"5111",
	"hours":"7",
	"days":"1",
	"leaveFromDate":"02-Aug-2017",
	"leaveToDate":"02-Aug-2017",
	"reason":"My Birthday",
	"status":"Approved",
	"payElement":"AALL"
}

Response Example

{
   "id":9010,
   "employeeId":"5111",
   "hours":7,
   "leaveFromDate":"02-Aug-2017",
   "leaveToDate":"02-Aug-2017",
   "reason":"My Birthday",
   "status":"Approved",
   "payElement":"AALL",
   "leaveBalanceType":{
      "leaveType":"Annual",
      "name":"Annual Leave",
      "unit":"hours",
      "organisationSpecific":false
   },
   "payElementId":777,
   "daysConsumed": 0,
   "daysCurrent": 1,
   "daysRemaining": 0,
   "quantityConsumed": 0,
   "quantityCurrent": 0,
   "quantityRemaining": 0,
   "leaveInDays": true,
   "links":[
      {
         "rel":"self",
         "href":"https://secure2.ipayroll.co.nz/api/v1/leaves/requests/9010"
      },
      {
         "rel":"employee",
         "href":"https://secure2.ipayroll.co.nz/api/v1/employees/5111"
      },
      {
         "rel":"pay element",
         "href":"https://secure2.ipayroll.co.nz/api/v1/payelements/AALL"
      }
   ]
}

PUT /api/v1/leaves/requests/{requestId}

Update a leave request

(Scope: leaverequests)

Update a Leave Request for an employee.

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).
hours Yes * Number Total number of hours of requested leave.
* hours is not mandatory in case that the employee is defined as ADP and the payElement's Leave Balance saved in days e.g Sick, Bereavement
days Yes ** Number Total number of days of requested leave (applies if a leave balance is stored in days)
** days is not mandatory for payElement whose Leave Balance saved in hours e.g Annual, Lieu
leaveFromDate Yes Date First day of leave
leaveToDate Yes Date Last day of leave
reason No String Reason for leave
status Yes String Processing status of a leave request. The status can be one of the following:
  • Pending
  • Approved
  • Declined
  • Cancelled
payElement Yes String Code of pay element that is used to process the request in a payroll


In case of ADP hours or days will be considered based on the payElement's Leave Balance

PUT /api/v1/leaves/requests/{requestId}

Request Body Example

{
	"employeeId":"5111",
	"hours":"7",
	"days":"1",
	"leaveFromDate":"02-Aug-2017",
	"leaveToDate":"02-Aug-2017",
	"reason":"My Birthday",
	"status":"Approved",
	"payElement":"AALL"
}

Response Example

{
   "id":9010,
   "employeeId":"5111",   
   "hours":7,
   "leaveFromDate":"02-Aug-2017",
   "leaveToDate":"02-Aug-2017",
   "reason":"My Birthday",
   "status":"Approved",
   "payElement":"AALL",
   "leaveBalanceType":{
      "leaveType":"Annual",
      "name":"Annual Leave",
      "unit":"hours",
      "organisationSpecific":false
   },
   "payElementId":777,
   "daysConsumed": 0,
   "daysCurrent": 1,
   "daysRemaining": 0,
   "quantityConsumed": 0,
   "quantityCurrent": 0,
   "quantityRemaining": 0,
   "leaveInDays": true,
   "links":[
      {
         "rel":"self",
         "href":"https://secure2.ipayroll.co.nz/api/v1/leaves/requests/9010"
      },
      {
         "rel":"employee",
         "href":"https://secure2.ipayroll.co.nz/api/v1/employees/5111"
      },
      {
         "rel":"pay element",
         "href":"https://secure2.ipayroll.co.nz/api/v1/payelements/AALL"
      }
   ]
}

Payslips

Attributes
Name Type Description
id Number Unique ID to identify a payslip
totalPayments Number Gross payment for the period
overpayment Number Indicates recovery of money in this payroll (might have been caused by overpayment in a previous payroll)
taxCredit Number Tax credited for donations made
yearToDateTotals Map A map containing year-to-date totals as value (Number) for various pay elements as key (String)
nettPay Number 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_down JSON Object Payroll that this payslip belongs to
payments arrow_drop_down JSON Object Details of payments included in the payslip
deductions arrow_drop_down JSON Object Details of deductions included in the payslip
otherBenefits arrow_drop_down JSON Object Details of other benefits included in the payslip
leaveBalances arrow_drop_down JSON Object Details of leave balances (as of payroll time)
timesheet arrow_drop_down 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

Response Example

{
 "links": [
   {
     "rel": "self",
     "href": "https://secure2.ipayroll.co.nz/api/v1/payrolls/current/payslips"
   }
 ],
 "content": [
 {
  "links": [
    {
      "rel": "self",
      "href": "https://secure2.ipayroll.co.nz/api/v1/payslips/0040/employees/101"
    },
    {
      "rel": "employee",
      "href": "https://secure2.ipayroll.co.nz/api/v1/employees/101"
    }
  ],
  "totalPayments": -254.35,
  "deductions": [
    {
      "amount": -320.07,
      "quantity": 1,
      "description": "PAYE (Tax Code M) to 013-166-374",
      "notes": "",
      "displayPayslipQuantity": ""
    },
    {
      "amount": -43.15,
      "quantity": 3,
      "description": "KiwiSaver",
      "displayPayslipQuantity": "3.00%"
    },
    {
      "amount": -1008.59,
      "description": "Take Home Pay to 06-0902-0068389-02"
    }
  ],
  "id":"0040",
  "otherBenefits": [],
  "yearToDateTotals": {
    "Taxable Earnings": 2272.49,
    "PAYE": 662.47
  },
  "leaveBalances": [
    {
      "balanceName": "Annual Leave",
      "hours": 229,
      "days": 28.5
    }
  ],
  "timesheet": {
    "links": [
      {
        "rel": "self",
        "href": "https://secure2.ipayroll.co.nz/api/v1/timesheets/101/payrolls/0040"
      }
    ],
    "employeeId": "101",
    "totalHours": -9.16,
    "transactions": [
      {
        "timesheetTransactionId": 1130873,
        "amount": -254.35,
        "quantity": -9.16,
        "rate": 27.7675,
        "description": "SICK - Sick Leave (01-Nov-2016 to 02-Nov-2016)",
        "costCentre": "new",
        "leaveFrom": "01-Nov-2016",
        "leaveTo": "02-Nov-2016",
        "leaveDays": "-0.9200",
        "payElement": "SICK"
      }
    ],
    "paidToDate": "12-Nov-2016",
    "paidFromDate": "04-Aug-2015"
  },
  "payments": [
    {
      "description": "Sick Leave (01-Nov-2016 to 02-Nov-2016) -0.92 days @ $27.7675",
      "quantity": -9.16,
      "amount": -254.35,
      "notes": ""
    }
  ],
  "nettPay": 0,
  "payroll": {
    "payrollNumber": "0040",
    "payDate": "25-Nov-2016"
  },
  "payslipMessage": "My Best Wishes for Your Partners"
},
   ...
 ],
 "page": {
   "size": 5,
   "totalElements": 5,
   "totalPages": 1,
   "number": 0
 }
}

GET /api/v1/payrolls/current/payslips/{payslipId}

Retrieve a single employee's payslip in the latest payroll

(Scopes: payslips payrolls)

Returns payslip of the specified employee.

Parameters
Name Required Type Description
payslipId Yes String Unique ID to identify an payslip within an organisation

GET /api/v1/payrolls/current/payslips/{payslipId}

Response Example

 {
  "links": [
    {
      "rel": "self",
      "href": "https://secure2.ipayroll.co.nz/api/v1/payrolls/current/payslips/101"
    },
    {
      "rel": "employee",
      "href": "https://secure2.ipayroll.co.nz/api/v1/employees/101"
    }
  ],
  "id":"101"
  "totalPayments": -254.35,
  "deductions": [
    {
      "amount": -320.07,
      "quantity": 1,
      "description": "PAYE (Tax Code M) to 013-166-374",
      "notes": "",
      "displayPayslipQuantity": ""
    },
    {
      "amount": -43.15,
      "quantity": 3,
      "description": "KiwiSaver",
      "displayPayslipQuantity": "3.00%"
    },
    {
      "amount": -1008.59,
      "description": "Take Home Pay to 06-0902-0068389-02"
    }
  ],
  "otherBenefits": [],
  "yearToDateTotals": {
    "Taxable Earnings": 2272.49,
    "PAYE": 662.47
  },
  "leaveBalances": [
    {
      "balanceName": "Annual Leave",
      "hours": 229,
      "days": 28.5
    }
  ],
  "timesheet": {
    "links": [
      {
        "rel": "self",
        "href": "https://secure2.ipayroll.co.nz/api/v1/timesheets/101/payrolls/0040"
      }
    ],
    "employeeId": "101",
    "totalHours": -9.16,
    "transactions": [
      {
        "timesheetTransactionId": 1130873,
        "amount": -254.35,
        "quantity": -9.16,
        "rate": 27.7675,
        "description": "SICK - Sick Leave (01-Nov-2016 to 02-Nov-2016)",
        "costCentre": "new",
        "leaveFrom": "01-Nov-2016",
        "leaveTo": "02-Nov-2016",
        "leaveDays": "-0.9200",
        "payElement": "SICK"
      }
    ],
    "paidToDate": "12-Nov-2016",
    "paidFromDate": "04-Aug-2015"
  },
  "payments": [
    {
      "description": "Sick Leave (01-Nov-2016 to 02-Nov-2016) -0.92 days @ $27.7675",
      "quantity": -9.16,
      "amount": -254.35,
      "notes": ""
    }
  ],
  "nettPay": 0,
  "payroll": {
    "payrollNumber": "0040",
    "payDate": "25-Nov-2016"
  },
  "payslipMessage": "Best Wishes!"
}

GET /api/v1/payrolls/{payrollId}/payslips

Retrieve all payslips in a specific payroll

(Scopes: payslips payrolls)

Returns all payslips associated with the specified payroll.

Parameters
Name Required Type Description
payrollId Yes String Unique identifier of the payroll

GET /api/v1/payrolls/{payrollId}/payslips

Response Example

{
 "links": [
   {
     "rel": "self",
     "href": "https://secure2.ipayroll.co.nz/api/v1/payrolls/0400/payslips"
   }
 ],
 "content": [
 {
  "links": [
    {
      "rel": "self",
      "href": "https://secure2.ipayroll.co.nz/api/v1/payslips/0040/employees/101"
    },
    {
      "rel": "employee",
      "href": "https://secure2.ipayroll.co.nz/api/v1/employees/101"
    }
  ],
  "id": "101",
  "totalPayments": -254.35,
  "deductions": [
    {
      "amount": -320.07,
      "quantity": 1,
      "description": "PAYE (Tax Code M) to 013-166-374",
      "notes": "",
      "displayPayslipQuantity": ""
    },
    {
      "amount": -43.15,
      "quantity": 3,
      "description": "KiwiSaver",
      "displayPayslipQuantity": "3.00%"
    },
    {
      "amount": -1008.59,
      "description": "Take Home Pay to 06-0902-0068389-02"
    }
  ],
  "otherBenefits": [],
  "yearToDateTotals": {
    "Taxable Earnings": 2272.49,
    "PAYE": 662.47
  },
  "leaveBalances": [
    {
      "balanceName": "Annual Leave",
      "hours": 229,
      "days": 28.5
    }
  ],
  "timesheet": {
    "links": [
      {
        "rel": "self",
        "href": "https://secure2.ipayroll.co.nz/api/v1/timesheets/101/payrolls/0040"
      }
    ],
    "employeeId": "101",
    "totalHours": -9.16,
    "transactions": [
      {
        "timesheetTransactionId": 1130873,
        "amount": -254.35,
        "quantity": -9.16,
        "rate": 27.7675,
        "description": "SICK - Sick Leave (01-Nov-2016 to 02-Nov-2016)",
        "costCentre": "new",
        "leaveFrom": "01-Nov-2016",
        "leaveTo": "02-Nov-2016",
        "leaveDays": "-0.9200",
        "payElement": "SICK"
      }
    ],
    "paidToDate": "12-Nov-2016",
    "paidFromDate": "04-Aug-2015"
  },
  "payments": [
    {
      "description": "Sick Leave (01-Nov-2016 to 02-Nov-2016) -0.92 days @ $27.7675",
      "quantity": -9.16,
      "amount": -254.35,
      "notes": ""
    }
  ],
  "nettPay": 0,
  "payroll": {
    "payrollNumber": "0040",
    "payDate": "25-Nov-2016"
  },
  "payslipMessage": "My Best Wishes for Your Partners"
},
   ...
 ],
 "page": {
   "size": 5,
   "totalElements": 5,
   "totalPages": 1,
   "number": 0
 }
}

GET /api/v1/payrolls/{payrollId}/payslips/{payslipId}

Retrieve specific employee's payslip in a specific payroll

(Scopes: payslips payrolls)

Returns specified employee's payslip in the specified payroll.

Parameters
Name Required Type Description
payrollId Yes String Unique identifier of the payroll
payslipId Yes String Unique identifier of the employee

GET /api/v1/payrolls/{payrollId}/payslips/{payslipId}

Response Example

 {
  "links": [
    {
      "rel": "self",
      "href": "https://secure2.ipayroll.co.nz/api/v1/payrolls/0040/payslips/101"
    },
    {
      "rel": "employee",
      "href": "https://secure2.ipayroll.co.nz/api/v1/employees/101"
    }
  ],
  "id": "101",
  "totalPayments": -254.35,
  "deductions": [
    {
      "amount": -320.07,
      "quantity": 1,
      "description": "PAYE (Tax Code M) to 013-166-374",
      "notes": "",
      "displayPayslipQuantity": ""
    },
    {
      "amount": -43.15,
      "quantity": 3,
      "description": "KiwiSaver",
      "displayPayslipQuantity": "3.00%"
    },
    {
      "amount": -1008.59,
      "description": "Take Home Pay to 06-0902-0068389-02"
    }
  ],
  "otherBenefits": [],
  "yearToDateTotals": {
    "Taxable Earnings": 2272.49,
    "PAYE": 662.47
  },
  "leaveBalances": [
    {
      "balanceName": "Annual Leave",
      "hours": 229,
      "days": 28.5
    }
  ],
  "timesheet": {
    "links": [
      {
        "rel": "self",
        "href": "https://secure2.ipayroll.co.nz/api/v1/timesheets/101/payrolls/0040"
      }
    ],
    "employeeId": "101",
    "totalHours": -9.16,
    "transactions": [
      {
        "timesheetTransactionId": 1130873,
        "amount": -254.35,
        "quantity": -9.16,
        "rate": 27.7675,
        "description": "SICK - Sick Leave (01-Nov-2016 to 02-Nov-2016)",
        "costCentre": "new",
        "leaveFrom": "01-Nov-2016",
        "leaveTo": "02-Nov-2016",
        "leaveDays": "-0.9200",
        "payElement": "SICK"
      }
    ],
    "paidToDate": "12-Nov-2016",
    "paidFromDate": "04-Aug-2015"
  },
  "payments": [
    {
      "description": "Sick Leave (01-Nov-2016 to 02-Nov-2016) -0.92 days @ $27.7675",
      "quantity": -9.16,
      "amount": -254.35,
      "notes": ""
    }
  ],
  "nettPay": 0,
  "payroll": {
    "payrollNumber": "0040",
    "payDate": "25-Nov-2016"
  },
  "payslipMessage": "My Best Wishes for Your Partners"
}

Pay 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
code String Element code. This is unique for standard pay elements and unique within an organisation for the specific ones.
description String Free-form description of the pay element
displayValue String The on screen value for the Pay element. This is the same as code for most pay elements
calculationRule String Code for the calculation rule used with the pay element. Different rules apply to different types of pay element
group String The pay element group. Possible values are Payment, Deduction and Leave
type String Pay element type within its group
multiplier Number The multiplier used in rate calculations
expired Boolean Whether this pay element is active or inactive (expired)
accLevyLiable Boolean New Zealand only.
True if the pay element is ACC levy liable
superableEarning Boolean True if the pay element is Superable Earning type
holidayPayLiable String True if the pay element is holiday pay liable
notKiwiSaverLiable Boolean New Zealand only.
True if the pay element is not kiwi saver liable
payrollTaxLiable Boolean Australia only.
True if the pay element is payroll tax liable
rdoLiable Boolean Australia only.
True if the pay element is rdo liable
lslLiable Boolean Australia only.
True if the pay element is ls liable
casLiable Boolean Australia only.
True if the pay element is cas liable
reducing Boolean True if the pay element is reducing
payableOnFinalPay Boolean True if the pay element is payable on final pay
itemisedOnPaymentSummary Boolean Australia only.
True if the pay element is itemised on payment summary
allowPartialDeduction Boolean True if the pay element allows partial deduction
consolidateTransactions Boolean True if the pay element applies consolidate transactions
payeeReference String Payee Reference
payeeCode String New Zealand only.
Payee code
bankAccountNumber String New Zealand only.
Bank account of the deduction by the pay element
bsbAccountNumber String Australia only.
The bsb account number of the deduction by the pay element
reduceSuperable String True if the pay element reduces superable
priority Number Pay element priority
costCentresRule String The rule applied to discern the pay element's cost centre
paymentMethod String Payment method
payeeParticulars String 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
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_down JSON Object List of rates for the pay element
rules arrow_drop_down JSON Object List of rules for leave entitlement
leaveBalanceType arrow_drop_down 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

Response Example

{
  "links": [
    {
      "rel": "self",
      "href": "https://secure2.ipayroll.co.nz/api/v1/payelements?size=100&page=0"
    }
  ],
  "content": [
    {
      "links": [
        {
          "rel": "self",
          "href": "https://secure2.ipayroll.co.nz/api/v1/payelements/ACC1"
        }
      ],
      "id": "ACC1",
      "code": "ACC1",
      "description": "ACC First Week",
      "displayValue": "ACC1",
      "calculationRule": "\"Pay Rate\" from Person",
      "group": "Leave",
      "type": "ACC First Week",
      "multiplier": 0.8,
      "rateAmount": "0.000000",
      "expired": false,
      "priority": 199,
      "leaveBalanceType": "ACC Leave",
      "costCentresRule": "from Person",
      "availableForLeaveRequest": false,
      "leaveTaxType": "Taxable",
      "derivedFrom": "system",
      "superableEarning": false,
      "accLevyLiable": false,
      "holidayPayLiable": true,
      "payableOnFinalPay": false
    }
    ...
  ],
  "page": {
    "size": 100,
    "totalElements": 30,
    "totalPages": 1,
    "number": 0
  }
}

GET /api/v1/payelements/{id}

Retrieve a pay element

(Scope: payelements)

Returns a particular pay element of the organisation, identified by pay element code.

Parameters
Name Required Type Description
id Yes String Unique ID to identify a pay element.

GET /api/v1/payelements/{code}

Response Example

{
  "links": [
    {
      "rel": "self",
      "href": "https://secure2.ipayroll.co.nz/api/v1/payelements/AH"
    }
  ],
  "id": "AH",
  "code": "AH",
  "description": "A sample pay element",
  "displayValue": "AH",
  "calculationRule": "\"Pay Rate\" from Person",
  "group": "Payment",
  "type": "Penal Time",
  "multiplier": 1,
  "rateAmount": "2.000000",
  "expired": false,
  "priority": 2,
  "paymentGroup": "Salary/Wages",
  "derivedFrom": "organisation",
  "superableEarning": true,
  "reducing": false,
  "accLevyLiable": true,
  "holidayPayLiable": true,
  "notKiwiSaverLiable": false,
  "payableOnFinalPay": false
}

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 Long The category id of the custom field.
categoryName String The category name of the custom field.
customFieldId Long The id for this custom field.
name String Name of the custom field.
date Date Date the custom field was added to the employee.
description String Description of the custom field (if blank this will default to the name).
contactDetails String Contact Only.
Contact's full name.
relationship String Contact Only.
Relationship of contact to the employee.
phoneNumber String Contact Only.
Phone number of contact.
email String Contact Only.
Email address of contact.
Address String Contact Only.
Address of contact.
contractHours Number Contract only.
Hours for the contract.
periodDays Number Contract only.
The period in days for the contract.
contractEnd String Contract only.
Contract end date.
fte Number Position only.
Full Time Equivalent for the position.
hayPoints Integer Position only.
Hay points for the position.
hayProfile Number Position only.
Hay profile for the position.
finish String Position only.
Date String for the position's finish date.
start String Position only.
Date String for the position's start date.
reportsFrom String Position only.
List of people reporting to the position (will not display if none exist).
reportsTo String Position only.
Who the position reports to.
renumerationType String Remuneration only.
The type of renumeration.
annualBenefit String Remuneration only.
The formatted annual benefit.
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/{employee id}/customfields

Retrieve all custom fields for employee

(Scopes: customfields employees)

Returns all the custom fields including values for an employee.

GET /api/v1/employees/{employee id}/customfields

Response Example

{
  "links": [
    {
      "rel": "self",
      "href": "https://secure2.ipayroll.co.nz/api/v1/employees/2/customfields"
    }
  ],
  "content": [
    {
      "id": 1,
      "category": 1649,
      "categoryName": "Position",
      "customFieldId": 35997,
      "name": "TUTOR",
      "description": "Class Tutor",
      "hayPoints": 2,
      "haysProfile": 23,
      "fte": 2,
      "finish": "10-May-2017",
      "start": "03-May-2016",
      "reportsTo": "MANAGER"
      "employeeId": "2",
      "links": [
        {
          "rel": "self",
          "href": "https://secure2.ipayroll.co.nz/api/v1/employees/2/customfields/1649/1"
        },
        {
          "rel": "employee",
          "href": " https://secure2.ipayroll.co.nz/api/v1/employees/2"
        }
      ]
    },
    {
      "id": 2,
      "category": 1650,
      "categoryName": "Qualification",
      "customFieldId": 35998,
      "name": "BACHELORS",
      "description": "Degree",
      "links": [
        {
          "rel": "self",
          "href": "https://secure2.ipayroll.co.nz/api/v1/employees/2/customfields/1650/2"
        },
        {
          "rel": "employee",
          "href": " https://secure2.ipayroll.co.nz/api/v1/employees/2"
        }
      ]
    }
  ],
  "page": {
    "size": 20,
    "totalElements": 2,
    "totalPages": 1,
    "number": 0
  }
}

GET /api/v1/employees/{employee id}/customfields/{category id}

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.

Parameters
Name Required Type Description
category id Yes Long The id of the category for which to retrieve the custom fields values.

GET /api/v1/employees/{employeeId}/customfields/{categoryId}

Response Example

{
  "links": [
    {
      "rel": "self",
      "href": "https://secure2.ipayroll.co.nz/api/v1/employees/2/customfields/1650"
    }
  ],
  "content": [
    {
      "id": 1,
      "category": 1650,
      "categoryName": "Qualification",
      "customFieldId": 35998,
      "name": "BACHELORS",
      "description": "Degree",
      "employeeId": "2",
      "links": [
        {
          "rel": "self",
          "href": "https://secure2.ipayroll.co.nz/api/v1/employees/2/customfields/1650/1"
        },
        {
          "rel": "employee",
          "href": " https://secure2.ipayroll.co.nz/api/v1/employees/2"
        }
      ]
    }
  ],
  "page": {
    "size": 20,
    "totalElements": 1,
    "totalPages": 1,
    "number": 0
  }
}

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.

Parameters
Name Required Type Description
category Yes Long The id of the custom field category.
id Yes Long The id of the custom field.

GET /api/v1/employees/{employeeId}/customfields/{categoryId}/{id}

Response Example

{
  "id", "35998",
  "category": 1650,
  "categoryName": "Qualification",
  "customFieldId": 35998,
  "name": "BACHELORS",
  "description": "Degree",
  "employeeId": "2",
  "links": [
    {
      "rel": "self",
      "href": "https://secure2.ipayroll.co.nz/api/v1/employees/2/customfields/1650/35998"
    },
        {
          "rel": "employee",
          "href": " https://secure2.ipayroll.co.nz/api/v1/employees/2"
        }
  ]
}

GET /api/v1/employees/customfields

Retrieve all custom fields

(Scopes: customfields employees)

Returns all the custom fields including values based on parameters.

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 Long The category id of the custom field.
categoryName No String The category name of the custom field. Not case sensitive.
customFieldId No Long 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

GET api/v1/employees/customfields?categoryName={categoryName}&customFieldName={customFieldName}

Response Example

{
    "links": [
        {
            "rel": "self",
            "href": " https://secure2.ipayroll.co.nz/api/v1/employees/customfields?categoryName=CONTACT&customFieldName=NEXT%20OF%20KIN"
        }
    ],
    "content": [
        {
            "category": 147,
            "categoryName": "Contact",
            "customFieldId": 198,
            "name": "NEXT OF KIN",
            "date": "31-Jul-2019",
            "description": "",
            "contact": "John Doe",
            "relationship": "Father",
            "phoneNumber": "022 123456",
            "email": "john@gmail.com",
            "address": "888, Sample Road",
            "employeeId": "2",
            "links": [
                {
                    "rel": "self",
                    "href": " https://secure2.ipayroll.co.nz/api/v1/employees/2/customfields/147/508"
                },
                {
                    "rel": "employee",
                    "href": " https://secure2.ipayroll.co.nz/api/v1/employees/2"
                }
            ],
            "id": "508"
        },
        {
            "category": 147,
            "categoryName": "Contact",
            "customFieldId": 198,
            "name": "NEXT OF KIN",
            "date": "30-Jul-2019",
            "description": "",
            "contact": "Jane Doe",
            "relationship": "Wife",
            "phoneNumber": "022 321654",
            "email": "jane@gmail.com",
            "address": "123 sample street",
            "employeeId": "2",
            "links": [
                {
                    "rel": "self",
                    "href": "https://secure2.ipayroll.co.nz/api/v1/employees/2/customfields/147/507"
                },
                {
                    "rel": "employee",
                    "href": " https://secure2.ipayroll.co.nz/api/v1/employees/2"
                }
            ],
            "id": "507"
        }
    ],
    "page": {
        "size": 20,
        "totalElements": 2,
        "totalPages": 1,
        "number": 0
    }
}

Payrolls

Attributes
Name Type Description
payrollNumber String Payroll Number.
id String Same as Payroll Number.
payDate String The date that people can access their pay.
message String Payroll message.
status String Status of the payroll.
status String Status of the payroll. The status can be one of the following:
  • Not Opened
  • Open
  • Confirming
  • Partially Confirmed
  • Confirmed
  • Debiting
  • Paid
  • Closed
payrollType String Type of the payroll. The payroll type can be one of the following:
  • Normal
  • One-Off
payFrequencies arrow_drop_down 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.

GET /api/v1/payrolls

Response Example

{
   "links":[
      {
         "rel":"first",
         "href":"https://secure2.ipayroll.co.nz/api/v1/payrolls?page=0&size=2"
      },
      {
         "rel":"self",
         "href":"https://secure2.ipayroll.co.nz/api/v1/payrolls?size=2"
      },
      {
         "rel":"next",
         "href":"https://secure2.ipayroll.co.nz/api/v1/payrolls?page=1&size=2"
      },
      {
         "rel":"last",
         "href":"https://secure2.ipayroll.co.nz/api/v1/payrolls?page=28&size=2"
      }
   ],
   "content":[
      {  "id": "1111",
         "payrollNumber":"1111",
         "payDate":"19-Aug-2014",
         "message":"payroll message",
         "status":"Closed",
         "payrollType":"Normal",
         "payFrequencies":[
            {
               "payFrequency":"Fortnightly",
               "included":false,
               "paidToDate":"26-Oct-2014"
            },
            {
               "payFrequency":"Monthly",
               "included":false,
               "paidToDate":"31-Oct-2014"
            },
            {
               "payFrequency":"Weekly (2)",
               "included":false,
               "paidToDate":"26-Oct-2014"
            },
            {
               "payFrequency":"Weekly",
               "included":true,
               "paidToDate":"07-Sep-2014"
            }
         ],
         "links":[
            {
               "rel":"self",
               "href":"https://secure2.ipayroll.co.nz/api/v1/payrolls/1111"
            },
            {
               "rel":"payslip",
               "href":"https://secure2.ipayroll.co.nz/api/v1/payslips/1111"
            }
         ]
      },
      {
         "id": "2222",
         "payrollNumber":"2222",
         "payDate":"20-Aug-2014",
         "message":"payroll message",
         "status":"Closed",
         "payrollType":"One-Off",
         "links":[
            {
               "rel":"self",
               "href":"https://secure2.ipayroll.co.nz/api/v1/payrolls/2222"
            },
            {
               "rel":"payslip",
               "href":"https://secure2.ipayroll.co.nz/api/v1/payslips/2222"
            }
         ]
      }
   ],
   "page":{
      "size":2,
      "totalElements":58,
      "totalPages":29,
      "number":0
   }
}

GET /api/v1/payrolls/current

Retrieve current payroll

(Scope: payrolls)

Returns the current payroll of an organisation.

GET /api/v1/payrolls/current

Response Example

{
   "id":"1111",
   "payrollNumber":"1111",
   "payDate":"19-Aug-2014",
   "message":"payroll message",
   "status":"Open",
   "payrollType":"Normal",
   "payFrequencies":[
      {
         "payFrequency":"Fortnightly",
         "included":false,
         "paidToDate":"26-Oct-2014"
      },
      {
         "payFrequency":"Monthly",
         "included":false,
         "paidToDate":"31-Oct-2014"
      },
      {
         "payFrequency":"Weekly (2)",
         "included":false,
         "paidToDate":"26-Oct-2014"
      },
      {
         "payFrequency":"Weekly",
         "included":true,
         "paidToDate":"07-Sep-2014"
      }
   ],
   "links":[
      {
         "rel":"self",
         "href":"https://secure2.ipayroll.co.nz/api/v1/payrolls/1111"
      },
      {
         "rel":"payslip",
         "href":"https://secure2.ipayroll.co.nz/api/v1/payslips/1111"
      }
   ]
}

GET /api/v1/payrolls/{payrollId}

Retrieve a single payroll

(Scope: payrolls)

Returns a particular payroll of an organisation.

GET /api/v1/payrolls/{payrollId}

Response Example

{
   "id": "1111",
   "payrollNumber":"1111",
   "payDate":"19-Aug-2014",
   "message":"payroll message",
   "status":"Closed",
   "payrollType":"Normal",
   "payFrequencies":[
      {
         "payFrequency":"Fortnightly",
         "included":false,
         "paidToDate":"26-Oct-2014"
      },
      {
         "payFrequency":"Monthly",
         "included":false,
         "paidToDate":"31-Oct-2014"
      },
      {
         "payFrequency":"Weekly (2)",
         "included":false,
         "paidToDate":"26-Oct-2014"
      },
      {
         "payFrequency":"Weekly",
         "included":true,
         "paidToDate":"07-Sep-2014"
      }
   ],
   "links":[
      {
         "rel":"self",
         "href":"https://secure2.ipayroll.co.nz/api/v1/payrolls/1111"
      },
      {
         "rel":"payslip",
         "href":"https://secure2.ipayroll.co.nz/api/v1/payslips/1111"
      }
   ]
}

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.

GET /api/v1/leavebalancetypes

Response Example

[
   {
      "leaveType":"Other (including Unpaid)",
      "name":"test2",
      "unit":"days",
      "organisationSpecific":true
   },
   {
      "leaveType":"Annual",
      "name":"Annual Leave",
      "unit":"hours",
      "organisationSpecific":false
   },
   {
      "leaveType":"Holiday",
      "name":"Holiday",
      "unit":"days",
      "organisationSpecific":false
   }
]

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 They super pay element.
quantity Number Quantity of the transaction.
superannMemberNumber String The superannuation member number for the transaction
superFundIdentifier String Identifier for the superfund.

GET /api/v1/employees/{employeeId}/superannuation

Retrieve all employee superannuation transactions

(Scope: employees)

Returns all the superannuation transactions for an employee.

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}/superannuation

Response Example

{
    "links": [
        {
            "rel": "self",
            "href":"https://secure2.cloudpayroll.com.au/api/v1/employees/1/superannuation"
        }
    ],
    "content": [
        {
            "quantity": 9.5,
            "costCentre": "Software",
            "payElement": "SUPER",
            "superFundIdentifier": "PTC0133AU",
            "superannMemberNumber": "123456",
            "links": [
                {
                    "rel": "self",
                    "href":"https://secure2.cloudpayroll.com.au/api/v1/employees/1/superannuation/73658"
                }
            ],
            "id": "73658"
        }
    ],
    "page": {
        "size": 20,
        "totalElements": 1,
        "totalPages": 1,
        "number": 0
    }
 }

POST /api/v1/employees/{employeeId}/superannuation

Create employee superannuation transaction

(Scope: employees)

Creates a superannuation transaction for an employee.

Name Required Type Description
amount Yes* Number Amount of transaction. Only used for Member Voluntary, Super Sacrifice and Reportable Superannuation Contribution type pay elements.
costCentre No String Cost centre of the transaction. Only required to override the default cost centre.
payElement No String They super pay element.
quantity Yes Number Quantity of the transaction.
superannMemberNumber No String The superannuation member number for the transaction
superFundIdentifier No String Identifier for the superfund.

POST /api/v1/employees/{employeeId}/superannuation

Request Body Example

 {
      "quantity": 9.5,
      "payElement": "MV",
      "superFundIdentifier": "AGE0102AU",
      "superannMemberNumber": "123456",
      "costCentre": "Software",
      "amount": 63
  }

Response Example

{
       "amount": 63,
       "quantity": 9.5,
       "costCentre": "Software",
       "payElement": "MV",
       "superFundIdentifier": "AGE0102AU",
       "superannMemberNumber": "123456",
       "links": [
          {
            "rel": "self",
            "href":"https://secure2.cloudpayroll.com.au/api/v1/employees/1/superannuation/73660"
          }
       ],
       "id": "73660"
  }

GET /api/v1/employees/{employeeId}/superannuation/{transactionId}

Retrieve an employee superannuation transaction

(Scope: employees)

Returns a specific superannuation transactions for an employee.

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.

GET /api/v1/employees/{employeeId}/superannuation/{transactionId}

Response Example

 {
       "quantity": 9.5,
       "costCentre": "Software",
       "payElement": "SUPER",
       "superFundIdentifier": "PTC0133AU",
       "superannMemberNumber": "123456",
       "links": [
          {
            "rel": "self",
            "href":"https://secure2.cloudpayroll.com.au/api/v1/employees/1/superannuation/73658"
          }
       ],
       "id": "73658"
  }

PUT /api/v1/employees/{employeeId}/superannuation/{transactionId}

Update employee superannuation transaction

(Scope: employees)

Updates a specific superannuation transaction for an employee.

Name Required Type Description
amount No Number Amount of transaction. Only used for Member Voluntary, Super Sacrifice and Reportable Superannuation Contribution type pay elements.
costCentre No String Cost centre of the transaction. Only required to override the default cost centre.
payElement No String They super pay element.
quantity No Number Quantity of the transaction.
superannMemberNumber No String The superannuation member number for the transaction
superFundIdentifier No String Identifier for the superfund.

PUT /api/v1/employees/{employeeId}/superannuation/{transactionId}

Request Body Example

 {
      "quantity": 9.5,
      "payElement": "MV",
      "superFundIdentifier": "AGE0102AU",
      "superannMemberNumber": "123456",
      "costCentre": "Software",
      "amount": 63
  }

Response Example

 {
       "amount": 63,
       "quantity": 9.5,
       "costCentre": "Software",
       "payElement": "MV",
       "superFundIdentifier": "AGE0102AU",
       "superannMemberNumber": "123456",
       "links": [
          {
            "rel": "self",
            "href":"https://secure2.cloudpayroll.com.au/api/v1/employees/1/superannuation/73660"
          }
       ],
       "id": "73660"
  }

DELETE /api/v1/employees/{employeeId}/superannuation/{transactionId}

Delete employee superannuation transaction

(Scope: employees)

Delete a specific superannuation transaction for an employee.

Parameters
Name Required Type Description
employeeId Yes String Unique ID to identify an employee within an organisation.
Limited to a-z, A-Z, 0-9, _ (underscore) and - (hyphen).
transactionId Yes String Unique ID to identify a transaction for an employee

DELETE /api/v1/employees/{employeeId}/superannuation/{transactionId}

Empty response.

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/{value}

Retrieve a user defined group details

(Scopes: employees)

Returns a user defined group.

Parameters
Name Required Type Description
value Yes String Value of the user defined group

GET /api/v1/userdefinedgroups/{value}

Response Example

{
    "value": "JOHN",
    "description": "John Smith",
    "label": "Leave Approver",
    "links": [
        {
            "rel": "self",
            "href": "https://secure2.ipayroll.co.nz/api/v1/userdefinedgroups/JOHN"
        }
    ],
    "id": "JOHN"
}

GET /api/v1/userdefinedgroups

Retrieve all user defined groups

(Scope: employees)

Returns all the user defined groups of an organisation.

GET /api/v1/userdefinedgroups

Response Example

{
    "links": [
        {
            "rel": "self",
            "href": "https://secure2.ipayroll.co.nz/api/v1/userdefinedgroups"
        }
    ],
    "content": [
        {
            "value": "JOHN",
            "description": "John Smith",
            "label": "Leave Approver",
            "links": [
                {
                    "rel": "self",
                    "href": "https://secure2.ipayroll.co.nz/api/v1/userdefinedgroups/JOHN"
                }
            ],
            "id": "DEFAULT"
        },
        {
            "value": "JANE",
            "description": "Jane Brown",
            "label": "Leave Approver",
            "links": [
                {
                    "rel": "self",
                    "href": "https://secure2.ipayroll.co.nz/api/v1/userdefinedgroups/JANE"
                }
            ],
            "id": "JANE"
        }
    ],
    "page": {
        "size": 20,
        "totalElements": 2,
        "totalPages": 1,
        "number": 0
    }
}