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, create 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)
  • Get user defined groups
  • Get general ledger entries by payroll or by date range

For a full list of requests, see Resources.

Scopes

Data available via the iPayroll API is grouped into scopes.

Scopes allow an organisation to expose only a particular section of their data to a third-party application. For example, permission can be granted only to access employee details, but not their timesheets.

The iPayroll API supports the following scopes:

  • Employees (employees)
  • Timesheets (timesheets)
  • Pay Rates (payrates)
  • Custom Fields (customfields)
  • Cost Centres (costcentres)
  • Leave Balances (leavebalances)
  • Leave Requests (leaverequests)
  • Payslips (payslips)
  • Pay Elements (payelements)
  • Payrolls (payrolls)
  • General Ledger (generalledger)

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

Getting Started

To begin using the API, you first need to register a developer account by emailing api@ipayroll.co.nz with your request. We will then provide you with the following on our demo:

application-account: This is the account your application can use to make API calls.

developer-account: You may use this account to login to your application's dashboard where you can obtain your client id and secret, and also configure your application.

organisation-account (client): The developer and application accounts are not associated with a specific organisation, therefore, you can not access any data that belongs to a particular organisation if you login with your developer account.

In order to make any productive API calls, you'll need access to an organisation in the system. So you can use one of the organisation's user accounts to grant permission to your application to access the organisation's data.

Whether you are an existing iPayroll customer or a third party developer who wants to integrate with iPayroll, a new organisation would be created in the demo environment, along with a user account with full access rights to the organisation. You can use this account to set data up for your organisation to test API calls or verify information uploaded through the API.

Developer Overview

Technologies used

The iPayroll API comprises a set of REST services. It accepts JSON formatted payloads where applicable, and always returns JSON data along with HATEOAS style links indicating further actions that can be performed on data elements. OAuth 2 is used for authorisation.

Environments

iPayroll provides two API environments.

https://demo.ipayroll.co.nz - This is the test environment used when developing and testing your applications.

https://secure2.ipayroll.co.nz - This is the live production system.

Remember: Those environments require the use of HTTPS.

Requests

All requests to iPayroll API end-points require your application to authenticate. Authentication is token based. This means that a valid access token must be attached to every API request, either as an HTTP header or as a request parameter.

We provide a detailed authentication and authorisation guide in the Authentication how to.

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

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

Retrieving Resources with HTTP GET

Your application may retrieve a representation of a resource by GETting the correct URLs. Successful GET requests to return HTTP code 200.

Response Format

All of the responses from iPayroll's API are in JSON format.

Date Formats

Definition of letters used:

Letter Represented component Examples
d Day in month 10
M Month in year Jul when MMM; 07 when MM
y Year 1996 when yyyy; 96 when yy

When posting data, you may use any of the following formats:

  • dd-MM-yyyy
  • dd-MMM-yyyy
  • yyyy-MM-dd
  • yyyy-MMM-dd
  • dd/MM/yy
  • dd/MM/yyyy
  • dd/MMM/yy
  • dd/MMM/yyyy
  • yyyy/MM/dd
  • yyyy/MMM/dd
  • dd MMMM yyyy
  • dd MMMM yy
  • dd/MM (this will assume the current year)
  • dd/MMM (this will assume the current year)

The API returns dd-MMM-yyyy format in responses.

Links

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

For example, a response containing an employee element, may contain links for the employee's pay rate and timeshseet endpoints.

{
  "links": [
    {
      "rel": "self",
      "href": "https://demo.ipayroll.co.nz/api/v1/employees/1"
    },
    {
      "rel": "payrate",
      "href": "https://demo.ipayroll.co.nz/api/v1/employees/1/payrates"
    },
    {
      "rel": "timesheet",
      "href": "https://demo.ipayroll.co.nz/api/v1/timesheets/1"
    }
  ],
  "surname": "White",
  "firstNames": "Jason",
  "employeeId": "1",
  ...rest of the properties...
}

Error handling

When an error occurs, the iPayroll API returns an error response formatted as a JSON object. The HTTP status code of the response is set as well.

Status code Status description Reason
400 BAD_REQUEST Invalid request or request syntax
401 UNAUTHORIZED User is not authenticated
403 FORBIDDEN User is authenticated but not authorized to view the data
404 NOT_FOUND Invalid URL
409 CONFLICT Already exists or an update currently running prevents the request from being actioned
412 PRECONDITION_FAILED Expected condition did not match
422 UNPROCESSABLE_ENTITY Failed to process the request
423 LOCKED Resource is in read-only state or access/update is disabled
500 INTERNAL_SERVER_ERROR Server error

Resources

Cost Centres

Cost Centres are disabled by default for an organisation. Make sure to enable through the UI before making API calls related to cost centres. Any call to cost centres would return an error with HTTP code 423 if disabled.

Note: If Xero Tracking Categories are used, the chart of account code and each tracking category must be split by a pipe, for example, "477|Sales|Wellington".

Attributes
Name Type Description
id Integer Unique ID to identify a cost centre
code String The name of the cost centre. Unique within an organisation
description String Cost centre description

GET /api/v1/costcentres

Retrieve all cost centres

(Scope: costcentres)

Returns all the cost centres of an organisation.

GET /api/v1/costcentres

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.

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

Request Body Properties
Name Required Type Description
code Yes String The name of the cost centre. Unique within an organisation.
If Xero Tracking Categories are used, the chart of account code and each tracking category must be split by a pipe, e.g. "477|Sales|Wellington".
description Yes String Cost centre description

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)
QUARTERLY Q1 Quarterly
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. 
AU TFN is masked in all responses, for example, "*** *** 123"
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
Code
CAE
M
M_SL
ME
ME_SL
ND
NSW
NONE
S
S_SL
SA
SA_SL
SB
SB_SL
SH
SH_SL
ST
ST_SL
STC
WT
taxScale String Australian Tax scale of the employee.
Tax Scale if proprietorStatus is Employee or Labour Hire.
Contractor Tax if proprietorStatus is Company/Contractor.
Note: See Tax Scale table at end of the attributes list to determine when a tax code can be applied.
Code Description
ONE 1 - Tax-free threshold not claimed
TWO 2 - Claimed Tax-free threshold and with or without Leave Loading
THREE 3 - Foreign Residents
FOUR_A 4a - No Tax File Number provided - Resident
FOUR_B 4b - No Tax File Number provided - Foreign
FIVE 5 - Full exemption from Medicare levy
SIX 6 - Half exemption from Medicare levy
H H - Working Holiday
W W - Seasonal Workers
A_ACTOR A-Actor - Employee has claimed the tax-free threshold
B_ACTOR B-Actor - Employee has not claimed the tax-free threshold
CONTRACTOR_VOLUNTARY CIR - Voluntary Withholding Agreement
SINGLE Single
ILLNESS_SEPARATE Illness-separated
MEMBER_OF_A_COUPLE Member of a couple
kiwiSaverRate Number Kiwisaver Employee Contribution rate of the employee
employerSubsidy Number KiwiSaver employer contribution
esctRate Number Tax rate that will be deducted from Superannuation Employer Contribution
kiwiSaverOptOutDate String Opt out date of employee from Kiwisaver
Mandatory if kiwiSaverStatus is Opted Out Address Line 1, City and Post Code are mandatory if an Opt Out Date exists
existingKiwiSaverMember Boolean Indication of whether employee is existing KiwiSaver member. This attribute is legacy as of 21-Nov-2018.
specialTax Number NZ: Special tax rate of the employee
AU: Specified rate of the employee
specialStudentLoan Number 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
hasDebt Boolean AU only: Higher Education Loan Program (HELP), VET Student Loan (VSL), Financial Supplement (FS), Student Start-up Loan (SSL) or Trade Support Loan (TSL) Debt
helpDebt Boolean AU only: HELP Debt. This attribute is legacy as of 15-Nov-2021 and is replaced by hasDebt.
sfssDebt Boolean AU only: SFSS Debt. This attribute is legacy as of 15-Nov-2021 and is replaced by hasDebt.
medicareLevyVariationDeclaration Boolean AU only: Has the employee filled a Medicare levy variation declaration
hasSpouse Boolean AU only: Spouse
incomeLessThanRelevantAmount Boolean AU only: Is the combined weekly income of payee and payee's spouse, or the payee's income as a sole parent, less than the relevant amount in table A
payrollTaxExempt Boolean AU only: Payroll Tax Exempt
dependentChildren Number AU only: Number of dependent children of the employee
surchargeIncrease Number AU only: Surcharge increase
employmentBasisType String AU only
proprietorStatus Code Description
NA (company / contractor) LABOUR_HIRE Labour Hire
  CONTRACTOR_PAYG Voluntary Agreement
  OTHER Other
NO (employee) FULLTIME Full Time
  PARTTIME Part Time
  CASUAL Casual
residenceType String AU only: Mandatory excluding if proprietorshipStatus is NA and employmentBasisType is LABOUR_HIRE.
Code Description
AUSTRALIAN Australian resident for tax purposes
FOREIGN Foreign resident for tax purposes
WORKING_HOLIDAY Working Holiday Maker
taxTreatmentType String AU only: Note: See Tax Treatment Type table at end of the attributes list to determine when a Tax Treatment Type can be applied.
Code Description
NONE None
REGULAR Regular
ACTORS Actors
SEASONAL Seasonal Worker Program
SENIORS Seniors and Pensioners
FOREIGN_HOLIDAY Foreign Resident
WORKING_HOLIDAY Working Holiday Maker
COMMISSIONER_INSTALMENT Commissioner’s Instalment Rate
NO_COMMISSION_INSTALMENT No Commissioner’s Instalment Rate
workPerformedOverseas Boolean AU only: True if employee is working overseas.
Organisation setting must be enabled.
workOverSeasCountry String AU only: Overseas country employee is working in.
closelyHeldPayee Boolean AU only: True if individual is directly related to entity.
Organisation setting must be enabled.
taxFreeThresholdType String AU only: Mandatory if taxTreatmentType is either REGULAR or ACTORS.
Code Description
CLAIMED Claimed
NOT_CLAIMED Not Claimed
specialTaxTypes  String Array AU only
Code Description
TIME Time (Ordinary, Overtime, Penal Time, Leave)
BACKPAY Back Payments & Overtime Backpay
TAXABLE_ALLOWANCES Taxable & Overtime Allowance (not itemised)
BONUS Bonus & Overtime Bonus
COMMISSION Commission & Overtime Commission
CAR Itemised – Cents per KM
TRANSPORT Itemised – Award Transport Payments
LAUNDRY Itemised – Laundry
MEALS Itemised – Overtime Meal Allowances
TRAVEL Itemised – Domestic or overseas travel & overseas accommodation allowances
TOOLS Itemised – Tool Allowances
TASKS Itemised – Tasks
QUALIFICATIONS Itemised – Qualifications
OTHER Itemised – Other
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
This attribute is legacy as of 15-Nov-2021 and is replaced by proprietorStatus NA and employmentBasisType LABOUR_HIRE.
FOREIGN_EMPLOYMENT 3, foreign, foreign employment
This attribute is legacy as of 15-Nov-2021 and is replaced by proprietorStatus NO and workPerformedOverseas = true.
surnameIsBusinessName Boolean AU only: When proprietorStatus = company/contractor. Flag to indicate when surname is contractor's business name.
includeInTaxablePaymentReport Boolean AU only: When proprietorStatus = company/contractor. Flag to include contractor in 'Contractor Taxable Payments Annual Report Interface' and 'Amended Contractor Taxable Payments Annual Report Interface'
contractorsAbn String Contractors ABN
address arrow_drop_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
workPattern String Work pattern for the employee, possible values: None, 1 Week - Monday to Sunday
nonResidentEntertainer Boolean New Zealand only.
When non-resident entertainer is supported
True if employee is a non-resident entertainer
kiwisaverHolidayEndDate String New Zealand only.
Date on which the KiwiSaver savings suspension will end (multiple date formats supported, dd/mm/yyyy preferred)
notSuppliedAddress Boolean New Zealand only.
Mandatory. True if employee has not supplied an address.
Must be True if any of addressLine1, city and postCode are empty strings.
notSuppliedDateOfBirth Boolean New Zealand only.
Mandatory. True if employee has not supplied a date of birth.
Must be True if birthDate is an empty string.
kiwiSaverStatus String New Zealand only.
KiwiSaver status
Description Related attributes
New Member Not applicable for 'Under 18'
Pre-existing member Not applicable for 'Under 18'
Opted Out kiwiSaverOptOutDate, addressLine1, city and postCode are mandatory for this status
'65 plus' must opt out of KiwiSaver with ‘Not Eligible’ status
Savings Suspension - IRD Approved kiwisaverHolidayEndDate is mandatory for this status
Not applicable for 'Under 18'
Savings Suspension - IRD Approved with Employer Contribution kiwisaverHolidayEndDate is mandatory for this status
Not applicable for 'Under 18'
Not Eligible kiwiSaverRate must be 0.00 (excluding 'Under 18')
employerSubsidy must be 0.00 (excluding 'Under 18')
Status for '65 plus' to opt out of KiwiSaver
Casual / Temporary First 28 Days kiwiSaverCasualAutoEnrollExempt must be true
kiwiSaverRate must be 0.00
employerSubsidy must be 0.00
Must be a new employee
Not applicable for 'Under 18' or '65 plus'
 Casual / Temporary Over 28 Days kiwiSaverCasualAutoEnrollExempt must be true
Must be an existing employee
Not applicable for 'Under 18' or '65 plus'
Not a Member Internal iPayroll status
Not available for POST or PUT
kiwiSaverAgeRange String New Zealand only.
Age range for kiwisaver. Ignored if employee has birthDate. Mandatory if employee does not have birthDate. Code or description is supported
Code Description
UNDER 0, under 18
EIGHTEEN_TO_SIXTY_FOUR 1, 18 to 64, 18 to 64 and if age is unknown
OVER 2, 65, 65 plus
kiwiSaverCasualAutoEnrollExempt Boolean New Zealand only.
True if employee is excempt from auto enroling in KiwiSaver. Only available if employee age is between 18 and 64
timecardEmployeeSettingsarrow_drop_down JSON Object A JSON object representing the standard hours worked each day

 

Australian Tax Tables

Tax Scales
taxTreatmentType taxFreeThreshold employmentBasisType taxScale Options
REGULAR CLAIMED   TWO
FOUR_A
FIVE
SIX
REGULAR UNCLAIMED   ONE
FOREIGN_RESIDENT     THREE
FOUR_B
ACTORS CLAIMED   A_ACTOR
ACTORS UNCLAIMED   B_ACTOR
SENIORS     SINGLE
ILLNESS_SEPARATE
MEMBER_OF_A_COUPLE
WORKING_HOLIDAY     H
FOUR_A
FOUR_B
SEASONAL     W
NONE      
    CONTRACTOR_PAYG CONTRACTOR_VOLUNTARY

 

Tax Treatment Type
proprietorStatus employmentBasis residenceType Other flags taxTreamentType Options
NA CONTRACTOR_PAYG     COMMISSIONER_INSTALMENT
NO_COMMISSIONER_INSTALMENT
NA OTHER     NONE
NA LABOUR_HIRE AUSTRALIAN   REGULAR
ACTORS
SENIORS
NA LABOUR_HIRE FOREIGN   FOREIGN_RESIDENTS
ACTORS
SENIORS
    WORKING_HOLIDAY   WORKING_HOLIDAY
    FOREIGN closelyHeldPayee = true FOREIGN_RESIDENTS
ACTORS
SENIORS
    AUSTRALIAN closelyHeldPayee = true OR workPerformedOverseas = true REGULAR
ACTORS
SENIORS
    FOREIGN   FOREIGN_RESIDENTS
ACTORS
SEASONAL
SENIORS
    AUSTRALIAN   REGULAR
ACTORS
SEASONAL
SENIORS

POST /api/v1/employees

Create one or more employees

(Scope: employees)

Create one or more employees in an organisation. An employee can be created with Surname alone. Otherwise, all other required attributes must be included. This cannot be used to update details of an existing employee.

Request Body Properties
Name Required Type Description
id No String Unique ID to identify an employee within an organisation.
Limited to a-z, A-Z, 0-9, _ (underscore) and - (hyphen).
birthDate No String Date of birth (multiple date formats supported, dd/mm/yyyy preferred)
defaultCostCentre No String Default cost centre for the employee - value expected is one of the cost centre codes defined for the organisation.
If Xero Tracking Categories are used, the chart of account code and each tracking category must be split by a pipe, e.g. "477|Sales|Wellington".
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)
QUARTERLY Q1 Quarterly
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. 
AU TFN is masked in all responses, for example, "*** *** 123"
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
Code
CAE
M
M_SL
ME
ME_SL
ND
NSW
NONE
S
S_SL
SA
SA_SL
SB
SB_SL
SH
SH_SL
ST
ST_SL
STC
WT
taxScale Yes String Australian Tax scale of the employee.
Tax Scale if proprietorStatus is Employee or Labour Hire.
Contractor Tax if proprietorStatus is Company/Contractor.
Note: See Tax Scale table at end of the attributes list to determine when a tax code can be applied.
Code Description
ONE 1 - Tax-free threshold not claimed
TWO 2 - Claimed Tax-free threshold and with or without Leave Loading
THREE 3 - Foreign Residents
FOUR_A 4a - No Tax File Number provided - Resident
FOUR_B 4b - No Tax File Number provided - Foreign
FIVE 5 - Full exemption from Medicare levy
SIX 6 - Half exemption from Medicare levy
H H - Working Holiday
W W - Seasonal Workers
A_ACTOR A-Actor - Employee has claimed the tax-free threshold
B_ACTOR B-Actor - Employee has not claimed the tax-free threshold
CONTRACTOR_VOLUNTARY CIR - Voluntary Withholding Agreement
SINGLE Single
ILLNESS_SEPARATE Illness-separated
MEMBER_OF_A_COUPLE Member of a couple
kiwiSaverRate Yes Number Kiwisaver Employee Contribution rate of the employee
employerSubsidy Yes Number KiwiSaver employer contribution
esctRate Yes Number NZ only: Tax rate that will be deducted from Superannuation Employer Contribution
kiwiSaverOptOutDate No String Opt out date of employee from Kiwisaver
Mandatory if kiwiSaverStatus is Opted Out Address Line 1, City and Post Code are mandatory if an Opt Out Date exists
existingKiwiSaverMember No Boolean Indication of whether employee is existing KiwiSaver member. This attribute is legacy as of 21-Nov-2018.
specialTax No Number NZ: Special tax rate of the employee
AU: Specified rate of the employee
specialStudentLoan No Number 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
hasDebt No Boolean AU only: Higher Education Loan Program (HELP), VET Student Loan (VSL), Financial Supplement (FS), Student Start-up Loan (SSL) or Trade Support Loan (TSL) Debt
helpDebt No Boolean AU only: HELP Debt. This attribute is legacy as of 15-Nov-2021 and is replaced by hasDebt.
sfssDebt No Boolean AU only: SFSS Debt. This attribute is legacy as of 15-Nov-2021 and is replaced by hasDebt.
medicareLevyVariationDeclaration No Boolean AU only: Has the employee filled a Medicare levy variation declaration
hasSpouse No Boolean AU only: Spouse
incomeLessThanRelevantAmount No Boolean AU only: Is the combined weekly income of payee and payee's spouse, or the payee's income as a sole parent, less than the relevant amount in table A
payrollTaxExempt No Boolean AU only: Payroll Tax Exempt
dependentChildren No Number AU only: Number of dependent children of the employee
surchargeIncrease No Number AU only: Surcharge increase
employmentBasisType Yes String AU only
proprietorStatus Code Description
NA (company / contractor) LABOUR_HIRE Labour Hire
  CONTRACTOR_PAYG Voluntary Agreement
  OTHER Other
NO (employee) FULLTIME Full Time
  PARTTIME Part Time
  CASUAL Casual
residenceType Yes String AU only: Mandatory excluding if proprietorshipStatus is NA and employmentBasisType is LABOUR_HIRE.
Code Description
AUSTRALIAN Australian resident for tax purposes
FOREIGN Foreign resident for tax purposes
WORKING_HOLIDAY Working Holiday Maker
taxTreatmentType Yes String AU only: Note: See Tax Treatment Type table at end of the attributes list to determine when a Tax Treatment Type can be applied.
Code Description
NONE None
REGULAR Regular
ACTORS Actors
SEASONAL Seasonal Worker Program
SENIORS Seniors and Pensioners
FOREIGN_HOLIDAY Foreign Resident
WORKING_HOLIDAY Working Holiday Maker
COMMISSIONER_INSTALMENT Commissioner’s Instalment Rate
NO_COMMISSION_INSTALMENT No Commissioner’s Instalment Rate
workPerformedOverseas No Boolean AU only: True if employee is working overseas.
Organisation setting must be enabled.
workOverSeasCountry No String AU only: Overseas country employee is working in.
closelyHeldPayee No Boolean AU only: True if individual is directly related to entity.
Organisation setting must be enabled.
taxFreeThresholdType No String AU only: Mandatory if taxTreatmentType is either REGULAR or ACTORS.
Code Description
CLAIMED Claimed
NOT_CLAIMED Not Claimed
specialTaxTypes No String Array AU only
Code Description
TIME Time (Ordinary, Overtime, Penal Time, Leave)
BACKPAY Back Payments & Overtime Backpay
TAXABLE_ALLOWANCES Taxable & Overtime Allowance (not itemised)
BONUS Bonus & Overtime Bonus
COMMISSION Commission & Overtime Commission
CAR Itemised – Cents per KM
TRANSPORT Itemised – Award Transport Payments
LAUNDRY Itemised – Laundry
MEALS Itemised – Overtime Meal Allowances
TRAVEL Itemised – Domestic or overseas travel & overseas accommodation allowances
TOOLS Itemised – Tool Allowances
TASKS Itemised – Tasks
QUALIFICATIONS Itemised – Qualifications
OTHER Itemised – Other
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
This attribute is legacy as of 15-Nov-2021 and is replaced by proprietorStatus NA and employmentBasisType LABOUR_HIRE.
FOREIGN_EMPLOYMENT 3, foreign, foreign employment
This attribute is legacy as of 15-Nov-2021 and is replaced by proprietorStatus NO and workPerformedOverseas = true.
surnameIsBusinessName No Boolean AU only: When proprietorStatus = company/contractor. Flag to indicate when surname is contractor's business name.
includeInTaxablePaymentReport No Boolean AU only: When proprietorStatus = company/contractor. Flag to include contractor in 'Contractor Taxable Payments Annual Report Interface' and 'Amended Contractor Taxable Payments Annual Report Interface'
contractorsAbn No String Contractors ABN
address arrow_drop_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 NZ only: 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 Not applicable for 'Under 18'
Pre-existing member Not applicable for 'Under 18'
Opted Out kiwiSaverOptOutDate, addressLine1, city and postCode are mandatory for this status
'65 plus' must opt out of KiwiSaver with ‘Not Eligible’ status
Savings Suspension - IRD Approved kiwisaverHolidayEndDate is mandatory for this status
Not applicable for 'Under 18'
Savings Suspension - IRD Approved with Employer Contribution kiwisaverHolidayEndDate is mandatory for this status
Not applicable for 'Under 18'
Not Eligible kiwiSaverRate must be 0.00 (excluding 'Under 18')
employerSubsidy must be 0.00 (excluding 'Under 18')
Status for '65 plus' to opt out of KiwiSaver
Casual / Temporary First 28 Days kiwiSaverCasualAutoEnrollExempt must be true
kiwiSaverRate must be 0.00
employerSubsidy must be 0.00
Must be a new employee
Not applicable for 'Under 18' or '65 plus'
 Casual / Temporary Over 28 Days kiwiSaverCasualAutoEnrollExempt must be true
Must be an existing employee
Not applicable for 'Under 18' or '65 plus'
Not a Member Internal iPayroll status
Not available for POST or PUT
kiwiSaverAgeRange No   New Zealand only.
Age range for kiwisaver. Ignored if employee has birthDate. Mandatory if employee does not have birthDate. Code or description is supported
Code Description
UNDER 0, under 18
EIGHTEEN_TO_SIXTY_FOUR 1, 18 to 64, 18 to 64 and if age is unknown
OVER 2, 65, 65 plus
kiwiSaverCasualAutoEnrollExempt No Boolean New Zealand only.
True if employee is excempt from auto enroling in KiwiSaver. Only available if employee age is between 18 and 64
timecardEmployeeSettingsarrow_drop_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.

Path Parameters
Name Required Type Description
employeeId Yes String Unique ID to identify an employee within an organisation.
Limited to a-z, A-Z, 0-9, _ (underscore) and - (hyphen).
Request Body Properties
Name Required Type Description
id No String Unique ID to identify an employee within an organisation.
Limited to a-z, A-Z, 0-9, _ (underscore) and - (hyphen).
birthDate No String Date of birth (multiple date formats supported, dd/mm/yyyy preferred)
defaultCostCentre No String Default cost centre for the employee - value expected is one of the cost centre codes defined for the organisation.
If Xero Tracking Categories are used, the chart of account code and each tracking category must be split by a pipe, e.g. "477|Sales|Wellington".
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)
QUARTERLY Q1 Quarterly
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. 
AU TFN is masked in all responses, for example, "*** *** 123"
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
Code
CAE
M
M_SL
ME
ME_SL
ND
NSW
NONE
S
S_SL
SA
SA_SL
SB
SB_SL
SH
SH_SL
ST
ST_SL
STC
WT
taxScale Yes String Australian Tax scale of the employee.
Tax Scale if proprietorStatus is Employee or Labour Hire.
Contractor Tax if proprietorStatus is Company/Contractor.
Note: See Tax Scale table at end of the attributes list to determine when a tax code can be applied.
Code Description
ONE 1 - Tax-free threshold not claimed
TWO 2 - Claimed Tax-free threshold and with or without Leave Loading
THREE 3 - Foreign Residents
FOUR_A 4a - No Tax File Number provided - Resident
FOUR_B 4b - No Tax File Number provided - Foreign
FIVE 5 - Full exemption from Medicare levy
SIX 6 - Half exemption from Medicare levy
H H - Working Holiday
W W - Seasonal Workers
A_ACTOR A-Actor - Employee has claimed the tax-free threshold
B_ACTOR B-Actor - Employee has not claimed the tax-free threshold
CONTRACTOR_VOLUNTARY CIR - Voluntary Withholding Agreement
SINGLE Single
ILLNESS_SEPARATE Illness-separated
MEMBER_OF_A_COUPLE Member of a couple
kiwiSaverRate Yes Number Kiwisaver Employee Contribution rate of the employee
employerSubsidy Yes Number KiwiSaver employer contribution
esctRate Yes Number NZ only: Tax rate that will be deducted from Superannuation Employer Contribution
kiwiSaverOptOutDate No String Opt out date of employee from Kiwisaver
Mandatory if kiwiSaverStatus is Opted Out Address Line 1, City and Post Code are mandatory if an Opt Out Date exists
existingKiwiSaverMember No Boolean Indication of whether employee is existing KiwiSaver member. This attribute is legacy as of 21-Nov-2018.
specialTax No Number NZ: Special tax rate of the employee
AU: Specified rate of the employee
specialStudentLoan No Number 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
hasDebt No Boolean AU only: Higher Education Loan Program (HELP), VET Student Loan (VSL), Financial Supplement (FS), Student Start-up Loan (SSL) or Trade Support Loan (TSL) Debt
helpDebt No Boolean AU only: HELP Debt. This attribute is legacy as of 15-Nov-2021 and is replaced by hasDebt.
sfssDebt No Boolean AU only: SFSS Debt. This attribute is legacy as of 15-Nov-2021 and is replaced by hasDebt.
medicareLevyVariationDeclaration No Boolean AU only: Has the employee filled a Medicare levy variation declaration
hasSpouse No Boolean AU only: Spouse
incomeLessThanRelevantAmount No Boolean AU only: Is the combined weekly income of payee and payee's spouse, or the payee's income as a sole parent, less than the relevant amount in table A
payrollTaxExempt No Boolean AU only: Payroll Tax Exempt
dependentChildren No Number AU only: Number of dependent children of the employee
surchargeIncrease No Number AU only: Surcharge increase
employmentBasisType Yes String AU only
proprietorStatus Code Description
NA (company / contractor) LABOUR_HIRE Labour Hire
  CONTRACTOR_PAYG Voluntary Agreement
  OTHER Other
NO (employee) FULLTIME Full Time
  PARTTIME Part Time
  CASUAL Casual
residenceType Yes String AU only: Mandatory excluding if proprietorshipStatus is NA and employmentBasisType is LABOUR_HIRE.
Code Description
AUSTRALIAN Australian resident for tax purposes
FOREIGN Foreign resident for tax purposes
WORKING_HOLIDAY Working Holiday Maker
taxTreatmentType Yes String AU only: Note: See Tax Treatment Type table at end of the attributes list to determine when a Tax Treatment Type can be applied.
Code Description
NONE None
REGULAR Regular
ACTORS Actors
SEASONAL Seasonal Worker Program
SENIORS Seniors and Pensioners
FOREIGN_HOLIDAY Foreign Resident
WORKING_HOLIDAY Working Holiday Maker
COMMISSIONER_INSTALMENT Commissioner’s Instalment Rate
NO_COMMISSION_INSTALMENT No Commissioner’s Instalment Rate
workPerformedOverseas No Boolean AU only: True if employee is working overseas.
Organisation setting must be enabled.
workOverSeasCountry No String AU only: Overseas country employee is working in.
closelyHeldPayee No Boolean AU only: True if individual is directly related to entity.
Organisation setting must be enabled.
taxFreeThresholdType No String AU only: Mandatory if taxTreatmentType is either REGULAR or ACTORS.
Code Description
CLAIMED Claimed
NOT_CLAIMED Not Claimed
 specialTaxTypes  No String Array  AU only
Code Description
TIME Time (Ordinary, Overtime, Penal Time, Leave)
BACKPAY Back Payments & Overtime Backpay
TAXABLE_ALLOWANCES Taxable & Overtime Allowance (not itemised)
BONUS Bonus & Overtime Bonus
COMMISSION Commission & Overtime Commission
CAR Itemised – Cents per KM
TRANSPORT Itemised – Award Transport Payments
LAUNDRY Itemised – Laundry
MEALS Itemised – Overtime Meal Allowances
TRAVEL Itemised – Domestic or overseas travel & overseas accommodation allowances
TOOLS Itemised – Tool Allowances
TASKS Itemised – Tasks
QUALIFICATIONS Itemised – Qualifications
OTHER Itemised – Other
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
This attribute is legacy as of 15-Nov-2021 and is replaced by proprietorStatus NA and employmentBasisType LABOUR_HIRE.

FOREIGN_EMPLOYMENT

 3, foreign, foreign employment
This attribute is legacy as of 15-Nov-2021 and is replaced by proprietorStatus NO and workPerformedOverseas = true.
surnameIsBusinessName No Boolean AU only: When proprietorStatus = company/contractor. Flag to indicate when surname is contractor's business name.
includeInTaxablePaymentReport No Boolean AU only: When proprietorStatus = company/contractor. Flag to include contractor in 'Contractor Taxable Payments Annual Report Interface' and 'Amended Contractor Taxable Payments Annual Report Interface'
contractorsAbn No String Contractors ABN
address arrow_drop_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 NZ only: 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 Not applicable for 'Under 18'
Pre-existing member Not applicable for 'Under 18'
Opted Out kiwiSaverOptOutDate, addressLine1, city and postCode are mandatory for this status
'65 plus' must opt out of KiwiSaver with ‘Not Eligible’ status
Savings Suspension - IRD Approved kiwisaverHolidayEndDate is mandatory for this status
Not applicable for 'Under 18'
Savings Suspension - IRD Approved with Employer Contribution kiwisaverHolidayEndDate is mandatory for this status
Not applicable for 'Under 18'
Not Eligible kiwiSaverRate must be 0.00 (excluding 'Under 18')
employerSubsidy must be 0.00 (excluding 'Under 18')
Status for '65 plus' to opt out of KiwiSaver
Casual / Temporary First 28 Days kiwiSaverCasualAutoEnrollExempt must be true
kiwiSaverRate must be 0.00
employerSubsidy must be 0.00
Must be a new employee
Not applicable for 'Under 18' or '65 plus'
 Casual / Temporary Over 28 Days kiwiSaverCasualAutoEnrollExempt must be true
Must be an existing employee
Not applicable for 'Under 18' or '65 plus'
Not a Member Internal iPayroll status
Not available for POST or PUT
kiwiSaverAgeRange No String New Zealand only.
Age range for kiwisaver. Ignored if employee has birthDate. Mandatory if employee does not have birthDate. Code or description is supported
Code Description
UNDER 0, under 18
EIGHTEEN_TO_SIXTY_FOUR 1, 18 to 64, 18 to 64 and if age is unknown
OVER 2, 65, 65 plus
kiwiSaverCasualAutoEnrollExempt No Boolean New Zealand only.
True if employee is excempt from auto enroling in KiwiSaver. Only available if employee age is between 18 and 64
timecardEmployeeSettingsarrow_drop_down No JSON Object A JSON object representing the standard hours worked each day

PUT /api/v1/employees/{employeeId}

Request Body Example

{
   "id": "newCustomId",
   "surname": "Caroline",
   "firstNames": "Jackie",
   "preferredName": "Jackie",
   "address": {
      "addressLine1": "10 Leinster St",
      "addressLine2": "abc",
      "suburb": "suburb",
      "city": "Wellington",
      "postCode": "6611",
      "country": "New Zealand"
   },
   "startDate": "18-Jul-2017",
   "birthDate": "03-Jul-1992",
   "paidToDate": "31-Dec-2017",
   "defaultCostCentre": "CostCenter",
   "userDefinedGroup": "AAAA",
   "email": "email@gmail.com",
   "phone": "0123456786",
   "title": "SSE",
   "gender": "Male",
   "payFrequency": "Weekly",
   "fullTimeHoursWeek": 10,
   "paymentMethod": "Bank",
   "bankAccountNumber": "123456789",
   "taxNumber": "00-000-000",
   "taxCode": "A",
   "kiwiSaverRate": 4,
   "employerSubsidy": 4.2,
   "esctRate": 17.5,
   "kiwiSaverOptOutDate": "26-Dec-2017",
   "existingKiwiSaverMember": false,
   "specialTax": 2.7,
   "specialStudentLoan": 1.2,
   "specialEarnerLevy": 0.3,
   "specialExtraPayRate": "HIGH",
   "proprietorStatus": "Yes",
   "holidayCalendar": "Wellington",
   "defineSetHoursPerDay": true,
   "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"
      },
      { 
         "rel": "userDefinedGroup", 
         "href": "https://secure2.ipayroll.co.nz/api/v1/userdefinedgroups/AAAA" 
      }
   ]
}

GET /api/v1/employees

Retrieve all employees

(Scope: employees)

Returns all the active employees of an organisation. Optionally, use status=inactive, to retrieve the inactive employees.

AU TFN is masked in all responses, for example, "*** *** 123".

Query Parameters
Name Required Type Description
status No String Use status=inactive to retrieve the inactive employees: /api/v1/employees?status=inactive

GET /api/v1/employees

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"
            },
            { 
               "rel": "userDefinedGroup", 
               "href": "https://secure2.ipayroll.co.nz/api/v1/userdefinedgroups/AAAA" 
            }
         ]
      }
   ],
   "page": {
      "size": 20,
      "totalElements": 114,
      "totalPages": 6,
      "number": 0
   }
}

GET /api/v1/employees/{employeeId}

Retrieve an employee's details

(Scope: employees)

Returns an employee.

AU TFN is masked in all responses, for example, "*** *** 123".

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

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"
      },
      { 
         "rel": "userDefinedGroup", 
         "href": "https://secure2.ipayroll.co.nz/api/v1/userdefinedgroups/AAAA" 
      }
   ]
}

Pay Rates

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

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

GET /api/v1/payrates

Retrieve pay rates for all employees

(Scopes: payrates employees)

Returns details of all pay rates for active employees associated with an organisation.

Query Parameters
Name Required Type Description
status No String Use status=inactive to retrieve the pay rates for inactive employees: /api/v1/payrates?status=inactive

GET /api/v1/payrates

Response Example

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

GET /api/v1/payrates/{payRateId}

Retrieve a specific pay rate

(Scopes: payrates employees)

Returns details of a particular pay rate.

Path Parameters
Name Required Type Description
payRateId Yes String Unique ID to identify a pay rate.

GET /api/v1/payrates/{payRateId}

Response Example

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

POST /api/v1/payrates

Update one or more pay rates

(Scopes: payrates employees)

Update one or more pay rates for one or more employees for an organisation.

Request Body Properties
Name Required Type Description
employeeId Yes String Unique ID to identify an employee within an organisation.
Limited to a-z, A-Z, 0-9, _ (underscore) and - (hyphen).
code Yes String Indicates the position of the rate on Personal Details
Code Description
1 Pay Rate from Personal Details
2 Pay Rate 2 from Personal Details
3 Pay Rate 3 from Personal Details
4 Pay Rate 4 from Personal Details
5 Pay Rate 5 from Personal Details
divisor Yes * String If an organisation specific divisor is associated, this field should contain a description of it. If not, a global divisor's name, e.g. "per hour", "per annum", "pa (Govt: 14/365th's)" or "pa (Aust: 12/313th's)".
* divisor is mandatory when updating an organisation specific or global divisor.
rate Yes * String Value of pay rate as entered in iPayroll.
* rate is mandatory when updating an organisation specific or global divisor.
payScale Yes ** String Pay Scales are designed to allow pay rates to be set up under a code that can then be used for multiple people. Displayed if Pay Scales are used and a Pay Scale is selected for employee, e.g. K1P107.
** payScale is mandatory when employee pay rate is associate with pay scales.

POST /api/v1/payrates

Request Body Example

[ 
    { 
        "employeeId": "11290",
        "code": 1,
        "rate": 45,
        "divisor": "per hour"
    },
    {
        "employeeId": "11290",
        "code": 2,
        "rate": 500000,
        "divisor": "per annum" 
    },
    { 
        "employeeId": "1e",
        "code": 1,
        "rate": 90000,
        "divisor": "per annum" 
    },
    ... 
]

Response Example

[
    {
        "hourlyRate": 45,
        "annualRate": 93600,
        "rate": 45,
        "code": "1",
        "divisor": "per hour",
        "employeeId": "11290",
        "links": [
            {
                "rel": "self",
                "href": "https://secure2.ipayroll.co.nz/api/v1/payrates/26077"
            },
            {
                "rel": "employee",
                "href": "https://secure2.ipayroll.co.nz/api/v1/employees/11290"
            }
        ],
        "id": "26077"
    },
    {
        "hourlyRate": 240.3848,
        "annualRate": 500000,
        "rate": 500000,
        "code": "2",
        "divisor": "per annum",
        "employeeId": "11290",
        "links": [
            {
                "rel": "self",
                "href": "https://secure2.ipayroll.co.nz/api/v1/payrates/26078"
            },
            {
                "rel": "employee",
                "href": "https://secure2.ipayroll.co.nz/api/v1/employees/11290"
            }
        ],
        "id": "26078"
    },
    {
        "hourlyRate": 43.2693,
        "annualRate": 90000,
        "rate": 90000,
        "code": "1",
        "divisor": "per annum",
        "employeeId": "1e",
        "links": [
            {
                "rel": "self",
                "href": "https://secure2.ipayroll.co.nz/api/v1/payrates/26022"
            },
            {
                "rel": "employee",
                "href": "https://secure2.ipayroll.co.nz/api/v1/employees/1e"
            }
        ],
        "id": "26022"
    },
    ...
]

 

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

Retrieve all of an employee’s pay rates

(Scopes: payrates employees)

Returns details of all pay rates associated with an employee.

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

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

Response Example

{
    "links": [ 
        { 
            "rel": "self", 
            "href": "https://secure2.ipayroll.co.nz/api/v1/employees/1111/payrates" 
        } 
    ],
    "content": [
        {
            "id": "26077",
            "code": "1",
            "hourlyRate": 14.25,
            "annualRate": 29640,
            "rate": 14.25,
            "divisor": "per hour",
            "employeeId": "1111",
            "links": [
                {
                    "rel":"self",
                    "href":"https://secure2.ipayroll.co.nz/api/v1/payrates/26077"
                },
                {
                    "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/{code}

Retrieve a specific pay rate for an employee

(Scopes: payrates employees)

Returns details of a particular pay rate of an employee.

Path Parameters
Name Required Type Description
employeeId Yes String Unique ID to identify an employee within an organisation.
Limited to a-z, A-Z, 0-9, _ (underscore) and - (hyphen).
code Yes String Indicates the position of the rate on Personal Details
Code Description
1 Pay Rate from Personal Details
2 Pay Rate 2 from Personal Details
3 Pay Rate 3 from Personal Details
4 Pay Rate 4 from Personal Details
5 Pay Rate 5 from Personal Details

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

Response Example

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

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

Update a specific pay rate for an employee

(Scopes: payrates employees)

Update a particular pay rate of an employee.

Path Parameters
Name Required Type Description
employeeId Yes String Unique ID to identify an employee within an organisation.
Limited to a-z, A-Z, 0-9, _ (underscore) and - (hyphen).
code Yes String Indicates the position of the rate on Personal Details
Code Description
1 Pay Rate from Personal Details
2 Pay Rate 2 from Personal Details
3 Pay Rate 3 from Personal Details
4 Pay Rate 4 from Personal Details
5 Pay Rate 5 from Personal Details
Request Body Properties
Name Required Type Description
divisor Yes * String If an organisation specific divisor is associated, this field should contain a description of it. If not, a global divisor's name, e.g. "per hour", "per annum", "pa (Govt: 14/365th's)" or "pa (Aust: 12/313th's)".
* divisor is mandatory when updating an organisation specific or global divisor.
rate Yes * String Value of pay rate as entered in iPayroll.
* rate is mandatory when updating an organisation specific or global divisor.
payScale Yes ** String Pay Scales are designed to allow pay rates to be set up under a code that can then be used for multiple people. Displayed if Pay Scales are used and a Pay Scale is selected for employee, e.g. K1P107.
** payScale is mandatory when employee pay rate is associate with pay scales.

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": "1",
    "divisor": "per annum",
    "usePayScale": false,
    "employeeId": "111111",
    "links": [
        {
            "rel":"self",
            "href":"https://secure2.ipayroll.co.nz/api/v1/payrates/26077"
        },
        {
            "rel":"employee",
            "href":"https://secure2.ipayroll.co.nz/api/v1/employees/111111"
        }
    ],
    "id": "26077"
}

Timesheets

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

Attributes
Name Type Description
id String Unique ID to identify a timesheet. This id is the same as the employeeId
employeeId String Unique ID to identify an employee within an organisation.
Limited to a-z, A-Z, 0-9, _ (underscore) and - (hyphen).
daysInPeriod Number Number of days an employee has worked within the period of the timesheet. May be omitted, it is only relevant for organisations that have "record day on timesheet" option on
totalHours Number Total hours inside a timesheet
paidFromDate String The start date of the pay period (multiple date formats supported, dd/mm/yyyy preferred)
paidToDate String The end date of the pay period (multiple date formats supported, dd/mm/yyyy preferred)
message String A message to be appended to the employee payslip
transactions arrow_drop_down JSON Object List of timesheet transactions for the employee

GET /api/v1/timesheets

Retrieve all of the timesheets in the latest payroll

(Scope: timesheets)

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

GET /api/v1/timesheets

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.

Path 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 the timesheets in a specific payroll

(Scopes: timesheets payrolls)

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

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

GET /api/v1/payrolls/{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 a specific payroll

(Scopes: timesheets payrolls)

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

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

GET /api/v1/payrolls/{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.

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

Note: The payroll won't automatically open, if it is the very first payroll. You'll need to manually open the first payroll in the application.

Request Body Properties
Name Required Type Description
daysInPeriod No Number Number of days an employee has worked within the period of the timesheet. May be omitted, it is only relevant for organisations that have "record day on timesheet" option on
employeeId Yes String Unique ID to identify an employee within an organisation. The employee should already be added to the payroll before posting timesheets against.
paidToDate No String The end date of the pay period (multiple date formats supported, dd/mm/yyyy preferred)
message No String If supplied, the message will be appended to the person's payslip message
transactions arrow_drop_down Yes Array List of timesheet transactions for the employee. An empty array is allowed

 

Employee Not Found in Payroll
Standard Codes Standard Message Description
125 Employee does not exist Employee Id cannot be found.
126 Employee does not have a start date The employee does not have a start date in Personal Details.
127 Employee does not have the correct pay frequency The pay frequency of the current payroll is different from the pay frequency of the employee.
128 Employee does not have hours on timesheet template The current payroll only accepts timesheets for employees with hours on their timesheet template.
129 Employee's start date is after the paid to date The employee's start date is after the paid to date of the current payroll.
130 Employee has already been paid Employee has a paid to date on or after the paid to date of the current payroll.
131 Employee has already finished The employee’s finish date is on or before the paid to date of the current payroll.

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.

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

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

Empty response.

Leave Balances

Attributes
Name Type Description
id String Unique ID to identify a leave balance
employeeId String Unique ID to identify an employee within an organisation.
Limited to a-z, A-Z, 0-9, _ (underscore) and - (hyphen).
entitled Number The number of units given since records started up to and including the current pay if a payroll is open
accrued Number The number of units accrued since last anniversary up to and including the current pay if a payroll is open
taken Number The total number of units taken from the leave balance up to and including the current pay if a payroll is open
balance Number The number of leave units remaining for an employee based on the following equation: Entitled + Accrued - Taken (up to and including the current pay if a payroll is open)
committedEntitled Number The number of units given since records started as at last pay
committedAccrued Number The number of units accrued since last anniversary as at last pay
committedTaken Number The total number of units taken from the leave balance as at last pay
committedBalance Number The number of leave units remaining for an employee based on the following equation: committedEntitled + committedAccrued - committedTaken as at last pay
nextAnniversaryDate String Next anniversary date (multiple date formats supported, dd/mm/yyyy preferred)
lastAnniversaryDate String Last anniversary date (multiple date formats supported, dd/mm/yyyy preferred)
leaveBalanceType arrow_drop_down JSON Object Leave Balance Type
approvedQuantity Number The number of outstanding leave request units already approved for an employee

GET /api/v1/leaves/balances

Retrieve leave balances for all employees

(Scopes: leavebalances employees)

Returns details of all leave balances for active employees associated with an organisation.

Query Parameters
Name Required Type Description
status No String Use status=inactive to retrieve the leave balances for inactive employees: /api/v1/leaves/balances?status=inactive

GET /api/v1/leaves/balances

Response Example

{
 "links": [
   {
     "rel": "self",
     "href": "https://secure2.ipayroll.co.nz/api/v1/leaves/balances"
   }
 ],
 "content": [
 {
  "links": [
    {
      "rel": "self",
      "href": "https://secure2.ipayroll.co.nz/api/v1/leaves/balances/10620"
    },
    {
      "rel": "employee",
      "href": "https://secure2.ipayroll.co.nz/api/v1/employees/1"
    }
  ],
  "id": "10620",
  "employeeId": "1",
  "entitled": 0,
  "accrued": 0,
  "taken": 8,
  "balance": -8,
  "committedEntitled": 0,
  "committedAccrued": 0,
  "committedTaken": 8,
  "committedBalance": -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/leaves/balances/{leaveBalanceId}

Retrieve a specific leave balance

(Scopes: leavebalances employees)

Returns details of a particular leave balance.

Path Parameters
Name Required Type Description
leaveBalanceId Yes String Unique ID to identify a leave balance.

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

Response Example

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

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

Retrieve all of an employee's leave balances

(Scopes: leavebalances employees)

Returns details of all leave balances associated with an employee.

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

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

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/leaves/balances/10620"
    },
    {
      "rel": "employee",
      "href": "https://secure2.ipayroll.co.nz/api/v1/employees/1"
    }
  ],
  "id": "10620",
  "employeeId": "1",
  "entitled": 0,
  "accrued": 0,
  "taken": 8,
  "balance": -8,
  "committedEntitled": 0,
  "committedAccrued": 0,
  "committedTaken": 8,
  "committedBalance": -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/{leaveBalanceTypeName}

Retrieve a specific leave balance for an employee

(Scopes: leavebalances employees)

Returns details of a particular leave balance of an employee.

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

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

Response Example

{
  "links": [
    {
      "rel": "self",
      "href": "secure2.ipayroll.co.nz/api/v1/leaves/balances/10638"
    },
    {
      "rel": "employee",
      "href": "secure2.ipayroll.co.nz/api/v1/employees/12345"
    }
  ],
  "id": "10638",
  "employeeId": "12345",
  "entitled": 0,
  "accrued": 0,
  "taken": 8,
  "balance": -8,
  "committedEntitled": 0,
  "committedAccrued": 0,
  "committedTaken": 8,
  "committedBalance": -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 String First day of leave (multiple date formats supported, dd/mm/yyyy preferred)
leaveToDate String Last day of leave (multiple date formats supported, dd/mm/yyyy preferred)
reason String Reason for leave
status String Processing status of a leave request. The status can be one of the following:
  • 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.

Query 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/{requestId}

Retrieve details of a leave request

(Scope: leaverequests)

Returns a leave request.

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

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

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.

Path Parameters
Name Required Type Description
employeeId Yes String Unique ID to identify an employee within an organisation.
Limited to a-z, A-Z, 0-9, _ (underscore) and - (hyphen).
Query Parameters
Name Required Type Description
status No String Processing status of a leave request. The status can be one of the following:
  • 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.

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

GET /api/v1/employees/{employeeId}/leaves/requests/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.

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

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.

Request Body Properties
Name Required Type Description
employeeId Yes String Unique ID to identify an employee within an organisation.
Limited to a-z, A-Z, 0-9, _ (underscore) and - (hyphen).
hours Yes * Number Total number of hours of requested leave.
* hours is not mandatory in case that the employee is defined as ADP and the payElement's Leave Balance saved in days e.g Sick, Bereavement
days Yes ** Number Total number of days of requested leave (applies if a leave balance is stored in days)
** days is not mandatory for payElement whose Leave Balance saved in hours e.g Annual, Lieu
leaveFromDate Yes String First day of leave (multiple date formats supported, dd/mm/yyyy preferred)
leaveToDate Yes String Last day of leave (multiple date formats supported, dd/mm/yyyy preferred)
reason No String Reason for leave
status Yes String Processing status of a leave request. The status can be one of the following:
  • 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.

Path Parameters
Name Required Type Description
requestId Yes Number Unique ID to identify a leave request
Request Body Properties
Name Required Type Description
employeeId Yes String Unique ID to identify an employee within an organisation.
Limited to a-z, A-Z, 0-9, _ (underscore) and - (hyphen).
hours Yes * Number Total number of hours of requested leave.
* hours is not mandatory in case that the employee is defined as ADP and the payElement's Leave Balance saved in days e.g Sick, Bereavement
days Yes ** Number Total number of days of requested leave (applies if a leave balance is stored in days)
** days is not mandatory for payElement whose Leave Balance saved in hours e.g Annual, Lieu
leaveFromDate Yes String First day of leave (multiple date formats supported, dd/mm/yyyy preferred)
leaveToDate Yes String Last day of leave (multiple date formats supported, dd/mm/yyyy preferred)
reason No String Reason for leave
status Yes String Processing status of a leave request. The status can be one of the following:
  • 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/{employeeId}

Retrieve a single employee's payslip in the latest payroll

(Scopes: payslips payrolls)

Returns payslip of the specified employee.

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

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

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/current/payslips/{employeeId}/download

Retrieve a single employee's payslip in the latest payroll in PDF format

(Scopes: payslips payrolls)

Returns a pdf file with the payslip of the specified employee. 

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

GET /api/v1/payrolls/current/payslips/{employeeId}/download

Response Example

The response is a byte array of content type “application/pdf” containing the payslip information. 

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

Retrieve all payslips in a specific payroll

(Scopes: payslips payrolls)

Returns all payslips associated with the specified payroll.

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

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

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

Retrieve specific employee's payslip in a specific payroll

(Scopes: payslips payrolls)

Returns specified employee's payslip in the specified payroll.

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

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

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"
}

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

Retrieve specific employee's payslip in a specific payroll in PDF format

(Scopes: payslips payrolls)

Returns a pdf file with the specified employee's payslip in the specified payroll. 

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

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

Response Example

The response is a byte array of content type “application/pdf” containing the payslip information. 

GET /api/v1/payrolls/payslips/{employeeId}/download?payDateFrom={payDateFrom}&payDateTo={payDateTo}

Retrieve specific employee's payslips for a date range in PDF format

(Scopes: payslips payrolls)

Returns a pdf file with the specified employee's payslips from a date range.

Path Parameters
Name Required Type Description
employeeId Yes String Unique ID to identify an employee within an organisation.
Limited to a-z, A-Z, 0-9, _ (underscore) and - (hyphen).
Query Parameters
Name Required Type Description
payDateFrom Yes String The start date of the period (multiple date formats supported, dd/mm/yyyy preferred)
payDateTo Yes String The end date of the period (multiple date formats supported, dd/mm/yyyy preferred)

GET /api/v1/payrolls/payslips/{employeeId}/download?payDateFrom={payDateFrom}&payDateTo={payDateTo}

Response Example

The response is a byte array of content type “application/pdf” containing the payslip information.

Pay Elements

A Pay Element defines the rules used to calculate transactions. Pay elements form the basis of transactions for Payments, Deductions and Leave. Pay elements are divided into Standard Pay elements (shared across all organisations) and specific - which are defined for and by a specific organisation.

Attributes
Name Type Description
id String Unique ID to identify a pay element. Same as code.
code String Element code. This is unique for standard pay elements and unique within an organisation for the specific ones.
description String Free-form description of the pay element
payslipDescription String When used, displays on the payslip in place of the "description" attribute
displayValue String The on screen value for the Pay element. This is the same as code for most pay elements
calculationRule String Code for the calculation rule used with the pay element. Different rules apply to different types of pay element
group String The pay element group. Possible values are Payment, Deduction and Leave
type String Pay element type within its group
multiplier Number The multiplier used in rate calculations
expired Boolean Whether this pay element is active or inactive (expired)
accLevyLiable Boolean New Zealand only.
True if the pay element is ACC levy liable
superableEarning Boolean True if the pay element is Superable Earning type
holidayPayLiable String True if the pay element is holiday pay liable
notKiwiSaverLiable Boolean New Zealand only.
True if the pay element is not kiwi saver liable
payrollTaxLiable Boolean Australia only.
True if the pay element is payroll tax liable
rdoLiable Boolean Australia only.
True if the pay element is rdo liable
lslLiable Boolean Australia only.
True if the pay element is ls liable
casLiable Boolean Australia only.
True if the pay element is cas liable
reducing Boolean True if the pay element is reducing
payableOnFinalPay Boolean True if the pay element is payable on final pay
itemisedOnPaymentSummary Boolean Australia only.
True if the pay element is itemised on payment summary
itemisedCategory String Australia only.
The itemised category when pay element is itemised on payment summary
allowPartialDeduction Boolean True if the pay element allows partial deduction
consolidateTransactions Boolean True if the pay element applies consolidate transactions
payeeReference String Payee Reference
payeeCode String New Zealand only.
Payee code
destinationAccountName String New Zealand only.
Destination account name for the deduction pay element.
accountName String Australia only.
Account name for the deduction pay element.
bankAccountNumber String New Zealand only.
Bank account of the deduction by the pay element
bsbAccountNumber String Australia only.
The bsb account number of the deduction by the pay element
reduceSuperable String True if the pay element reduces superable
priority Number Pay element priority
costCentresRule String The rule applied to discern the pay element's cost centre
paymentMethod String Payment method
payeeParticulars String New Zealand only.
Payee particulars
doneeAddress String New Zealand only.
Donee address
doneeName String New Zealand only.
Donee name
unusedLeavePayment Boolean True if the pay element is an unused leave payment
employmentTerminationPayment Boolean Australia only.
True if the pay element is an employment termination payment
employmentTerminationPaymentNoLumpD Boolean Australia only.
True if the pay element is an employment termination payment with no LumpD
lumpeLiable Boolean Australia only.
True if the pay element is lump E liable
availableForLeaveRequest Boolean True if the pay element is available for leave request
leaveTaxType String Tax type of the leave
paymentGroup String Payment group of the pay element
calculationAccumulator String The name of the calculation accumulator for the pay element
debitCostCentreRule String The name of the debit cost centre rule
excessRedundancy String The pay element is Employment Termination Payment (ETP) excluded or not
derivedFrom String If the pay element is defined by the organisation, the value will be "organisation". Otherwise, the value is "system"
customField String The name of the custom field for the pay element
rates arrow_drop_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/{payElementId}

Retrieve a pay element

(Scope: payelements)

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

Path Parameters
Name Required Type Description
payElementId Yes String Unique ID to identify a pay element. Same as code. If the pay element code has special characters, use the GET /api/v1/payelement?code={payElementId} endpoint.

GET /api/v1/payelements/{payElementId}

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
}

GET /api/v1/payelement?code={payElementId}

Retrieve a pay element (includes special characters)

(Scope: payelements)

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

Query Parameters
Name Required Type Description
payElementId Yes String Unique ID to identify a pay element. Same as code. If the code has special characters, the special characters must be encoded.

GET /api/v1/payelement?code={payElementId}

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 Integer The category id of the custom field.
categoryName String The category name of the custom field.
customFieldId Integer The id for this custom field.
name String Name of the custom field.
date String Date the custom field was added to the employee (multiple date formats supported, dd/mm/yyyy preferred)
description String Description of the custom field (if blank this will default to the name).
contactDetails String Contact Only.
Contact's full name.
relationship String Contact Only.
Relationship of contact to the employee.
phoneNumber String Contact Only.
Phone number of contact.
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.
Full Time Equivalent for the contract.
contractEnd String Contract only.
Contract end date (multiple date formats supported, dd/mm/yyyy preferred)
fte Number Position only.
Full Time Equivalent for the position.
hayPoints Integer Position only.
Hay points for the position.
hayProfile Number Position only.
Hay profile for the position.
finish String Position only.
Date String for the position's finish date (multiple date formats supported, dd/mm/yyyy preferred)
start String Position only.
Date String for the position's start date (multiple date formats supported, dd/mm/yyyy preferred)
reportsFrom String Position only.
List of people reporting to the position (will not display if none exist).
reportsTo String Position only.
Who the position reports to.
renumerationType String Remuneration only.
The type of renumeration.
annualBenefit String Remuneration only.
The formatted annual benefit.
employeeId String Unique ID to identify an employee within an organisation. Limited to a-z, A-Z, 0-9, _ (underscore) and - (hyphen).

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

Retrieve all custom fields for employee

(Scopes: customfields employees)

Returns all the custom fields including values for an employee.

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

GET /api/v1/employees/{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/{employeeId}/customfields/{categoryId}

Retrieve all custom fields of a single category for an employee

(Scopes: customfields employees)

Returns all the custom fields including values of the specified category id for an employee.

Path Parameters
Name Required Type Description
employeeId Yes String Unique ID to identify an employee within an organisation.
Limited to a-z, A-Z, 0-9, _ (underscore) and - (hyphen).
categoryId Yes Integer The id of the category for which to retrieve the custom fields values.

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

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.

Path Parameters
Name Required Type Description
employeeId Yes String Unique ID to identify an employee within an organisation.
Limited to a-z, A-Z, 0-9, _ (underscore) and - (hyphen).
category Yes Integer The id of the custom field category.
id Yes Integer The id of the custom field.

GET /api/v1/employees/{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.

Query Parameters
Name Required Type Description
employeeId No String Unique ID to identify an employee within an organisation.
Limited to a-z, A-Z, 0-9, _ (underscore) and - (hyphen).
categoryId No Integer The category id of the custom field.
categoryName No String The category name of the custom field. Not case sensitive.
customFieldId No Integer The id for this custom field.
customFieldName No String Name of the custom field. Not case sensitive. Needs to be used together with categoryId or categoryName.
Sample requests

GET /api/v1/employees/customfields?categoryName=CONTACT&customFieldName=NEXT OF KIN&employeeId=2

GET /api/v1/employees/customfields?categoryName=CONTACT&customFieldName=NEXT OF KIN

GET /api/v1/employees/customfields?categoryName=CONTACT&employeeId=2

GET /api/v1/employees/customfields?employeeId=2

GET /api/v1/employees/customfields?categoryName=CONTACT

GET /api/v1/employees/customfields?categoryId=137

GET /api/v1/employees/customfields?categoryId=137&customFieldId=177&employeeId=2

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 (multiple date formats supported, dd/mm/yyyy preferred)
message String Payroll message.
status String Status of the payroll.
status String Status of the payroll. The status can be one of the following:
  • 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.

Query Parameters
Name Required Type Description
dateFrom No String The start date of the period (multiple date formats supported, dd/mm/yyyy preferred)
dateTo No String The end date of the period (multiple date formats supported, dd/mm/yyyy preferred)
Sample requests

GET /api/v1/payrolls?dateFrom=01/01/2021&dateTo=31/01/2021

GET /api/v1/payrolls?dateFrom=01/01/2021

GET /api/v1/payrolls?dateTo=31/01/2021

GET /api/v1/payrolls

GET /api/v1/payrolls

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/1111/payslips"
            }
         ]
      },
      {
         "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/2222/payslips"
            }
         ]
      }
   ],
   "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/1111/payslips"
      }
   ]
}

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/1111/payslips"
      }
   ]
}

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.

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

GET /api/v1/employees/{employeeId}/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.

Path Parameters
Name Required Type Description
employeeId Yes String Unique ID to identify an employee within an organisation.
Limited to a-z, A-Z, 0-9, _ (underscore) and - (hyphen).
Request Body Properties
Name Required Type Description
amount Yes* Number Amount of transaction. Only used for Member Voluntary, Super Sacrifice and Reportable Superannuation Contribution type pay elements.
costCentre No String Cost centre of the transaction. Only required to override the default cost centre.
If Xero Tracking Categories are used, the chart of account code and each tracking category must be split by a pipe, e.g. "477|Sales|Wellington".
payElement 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.

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

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.

Path Parameters
Name Required Type Description
employeeId Yes String Unique ID to identify an employee within an organisation.
Limited to a-z, A-Z, 0-9, _ (underscore) and - (hyphen).
transactionId Yes String Unique ID to identify a transaction for an employee.
Request Body Properties
Name Required Type Description
amount No Number Amount of transaction. Only used for Member Voluntary, Super Sacrifice and Reportable Superannuation Contribution type pay elements.
costCentre No String Cost centre of the transaction. Only required to override the default cost centre.
If Xero Tracking Categories are used, the chart of account code and each tracking category must be split by a pipe, e.g. "477|Sales|Wellington".
payElement 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.

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

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

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

GET /api/v1/userdefinedgroups/{value}

Retrieve a user defined group details

(Scopes: employees)

Returns a user defined group.

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

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"
}

General Ledger

Post payroll journal entries to a general ledger.

Attributes
Name Type Description
date String Pay date of the payroll or dateTo when using date filters (multiple date formats supported, dd/mm/yyyy preferred)
accounts arrow_drop_down JSON Object List of accounts for the general ledger

GET /api/v1/generalledger/{payrollId}

Retrieve the general ledger from a specific payroll

(Scope: generalledger)

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

GET /api/v1/generalledger/{payrollId}

Response Example

{
    "date": "05-Aug-2019",
    "accounts": [
        {
            "accountCode": "TAX-ACCOUNT",
            "description": "",
            "amount": 196.27,
            "credit": true,
            "links": []
        },
        {
            "accountCode": "BANK-ACCOUNT",
            "description": "",
            "amount": 659.73,
            "credit": true,
            "links": []
        },
        {
            "accountCode": "PAYROLL-CLEARING",
            "description": "",
            "amount": 856,
            "credit": true,
            "links": []
        },
        {
            "accountCode": "PAYROLL-CLEARING",
            "description": "",
            "amount": 856,
            "credit": false,
            "links": []
        },
        {
            "accountCode": "IPAYROLL-PROCESSING-FEES",
            "description": "",
            "amount": 20.87,
            "credit": false,
           "links": []
        }
    ],
    "links": []
}

GET /api/v1/generalledger

Retrieve the general ledger from a date range

(Scope: generalledger)

Query Parameters
Name Required Type Description
dateFrom Yes String Starting date for the period (multiple date formats supported, dd/mm/yyyy preferred)
dateTo Yes String End date for the period (multiple date formats supported, dd/mm/yyyy preferred)

GET /api/v1/generalledger?dateFrom={dateFrom}&dateTo={dateTo}

Response Example

{
    "date": "05-Aug-2019",
    "accounts": [
        {
            "accountCode": "TAX-ACCOUNT",
            "description": "",
            "amount": 196.27,
            "credit": true,
            "links": []
        },
        {
            "accountCode": "BANK-ACCOUNT",
            "description": "",
            "amount": 659.73,
            "credit": true,
            "links": []
        },
        {
            "accountCode": "PAYROLL-CLEARING",
            "description": "",
            "amount": 856,
            "credit": true,
            "links": []
        },
        {
            "accountCode": "PAYROLL-CLEARING",
            "description": "",
            "amount": 856,
            "credit": false,
            "links": []
        },
        {
            "accountCode": "IPAYROLL-PROCESSING-FEES",
            "description": "",
            "amount": 20.87,
            "credit": false,
           "links": []
        }
    ],
    "links": []
}