Developer's Guide

Getting Started

  1. To get started, apply for a developer account by completing a Developer Account Application.

  2. Complete the Annual Security Questionnaire.
    Note: This will be supplied to you when you receive the details of your developer account.
    The iPayroll Security Team must review this questionnaire before a production account can be provided.

  3. Develop and test your API integration.
    Note: Your developer account will be disabled after 6 months if you have not applied for a production account or a time extension.

  4. Email api@ipayroll.co.nz or api@cloudpayroll.com.au with your request for a production account.
    Note: The production account cannot be provided until the Annual Security Questionnaire has been submitted and approved by the iPayroll Security Team.
    You may be asked to demo your API integration.

If you have any general API enquiries, please email api@ipayroll.co.nz or api@cloudpayroll.com.au.

Developer Agreement

Terms and Conditions

Welcome to the iPayroll API Developer Platform

The iPayroll Group and its affiliates including CloudPayroll (referred to as “iPayroll”, “we”, “our” or “us”) have created these API Developer Platform Terms and Conditions (these “Terms”) so that developers and vendors like you can enjoy the benefits of our API Developer Platform while protecting both our and its users’ rights.

API Development Accounts will come from one of three parties:

  • Vendors (third party who owns a product that multiple iPayroll organisations could potentially use)
  • Contractors (third party hired by an organisation or group to develop API integration on behalf of the organisation or group)
  • Developers/Organisations (where an organisation or group has their own inhouse developers that will build API integration for their own organisation or group)

By agreeing to use the API Developer Platform, you agree to be bound by these Terms. You may not use the API Developer Platform if you do not agree to these Terms. In these Terms, you are referred to as “Developer”, “Contractor“, “Vendor“, or “you”.

Agreement on Behalf
If you are agreeing to these Terms not as an individual but on behalf of your company, then “Developer” or “you” means your company and you are binding your company to these Terms.

If you are providing application development services or are otherwise acting as a Contractor for an organisation that will receive or otherwise benefit from data obtained through the API Developer Platform (that is, you are a “Contractor”), you represent that you are acting as an agent of the Ultimate Recipient and you have the authority to bind the Ultimate Recipient to these Terms. In that case, “Developer” or “you” includes the Ultimate Recipient as well.

If you subcontract the development of Your Applications, you will ensure that any third party subcontractor complies with these Terms.

These Terms include any terms provided separately to you for the API Developer Platform, including guidelines specific to certain types of developers and/or use cases. These Terms govern your access to, and use of our APIs and developer webpages and documentation (“Documentation”) (collectively, the “API Developer Platform”).

The API Developer Platform is designed to allow you to connect your new and existing applications, products and services (“Your Applications”) with our applications, products and services (collectively, the “iPayroll Service”).

These Terms may change as we continue to improve the API Developer Platform. We will provide notice of modifications as described in the Modifications to Terms section.

Platform Access / Registration

In order to access the API Developer Platform, you must follow the registration process established by iPayroll. We may approve or deny access to the API Developer Platform in our sole discretion.

When you register, you are also subject to:

  • The API Developer Platform Terms and Conditions (this page)
  • Standard Terms of Use (agreed to as an iPayroll Organisation)
  • iPayroll Privacy Policy

Additionally you agree to understand and follow:

and

  • Complete the API Consumer Security Standards Questionnaire, and agree to update the questionnaire yearly

Your Use Rights

Subject to these Terms, you may use our API Developer Platform solely to enable Your Applications to access or interface with the iPayroll Service as set forth in these Terms (your “Use Rights”).

Your use is permitted as described in our Documentation and is subject to call, usage and other limits as described in the API Rate Limits Page which may be modified from time to time, and which are incorporated into these Terms, or as we otherwise notify you. All of your rights are non-assignable, non-transferrable, and non-sublicenseable.

If you are a Contractor, you are only permitted to pass through any User Data to the Ultimate Recipient on behalf of which you are connecting to the API Developer Platform.

If you subcontract the development of Your Applications, you will ensure that any third party engaged by you is only passing through any User Data to you. Such subcontractors shall have no other use rights.

You agree not to use, nor permit any third party to use the API Developer Platform in a manner that violates any applicable law, regulation or these Terms.

If you are unsure whether your intended use case(s) comply with these Terms, please reach out to api@ipayroll.co.nz before investing time and resources into building Your Application’s integration with our APIs.

We reserve the rights to modify or amend this policy, in our sole discretion, at any time.

Support and Modification

While we may provide you with support or modifications for the API Developer Platform, we are not obligated to do so and have no obligation to fix or respond to errors you may encounter.

In our discretion and without liability to you, we may add, remove or modify any features of the API Developer Platform; impose additional eligibility requirements or restrictions for access to the API Developer Platform; or discontinue the API Developer Platform.

If we modify the API Developer Platform, we may require you to use the modified version, which may not be compatible with Your Applications developed using previous versions.

We typically make these changes as part of our overall API Developer Platform program and may not be able to provide you with individual notice of the changes.

Your Responsibilities

If you are a Vendor, Your Applications must include your own legally binding terms of use and privacy policy (“Your Terms”) that are publicly available to your third party users.

If a user of the iPayroll Service allows Your Applications to retrieve any data, content or information of employer or employees, including where such data is aggregated by you across more than one user (“User Data”) from the iPayroll Service, you must (1) access only the minimum data fields Your Application needs to work properly, as permitted by the user and (2) ensure the User Data is collected, processed, transmitted, maintained and used in accordance with Your Terms, all Laws (defined below) and reasonable measures that protect the privacy and security of the User Data.

For clarity, any access or use of the iPayroll Service itself is subject to our Service Terms or other applicable terms agreed by us with the user, not Your Terms. If we receive any Data from or on behalf of a user, including through or enabled by Your Application, we will treat such Data under its applicable terms with such user and such data will no longer be subject to Your Terms.

Do the right thing
You agree to follow the API Developer Agreement and adhere to our Security Expectations and Privacy Guidelines

You will only access (or attempt to access) an API by the means described in the documentation of that API. If iPayroll assigns you developer credentials, you must use them with the applicable APIs. You will not misrepresent or mask either your identity or your API Client's identity when using the APIs or developer accounts.

You agree that iPayroll may monitor the use of APIs to ensure quality, improve iPayroll products and services and verify your compliance with the Terms. iPayroll may suspend access to the APIs by you or your API Client without notice if we reasonably believe that you are in violation of the Terms.

Your Representations and Indemnity
You are solely responsible for your use of the API Developer Platform, Your Applications and any data or content that you use with the API Developer Platform.

You represent and warrant that:

  1. you have full power and authority to enter into and perform these Terms;
  2. your use of the API Developer Platform and Your Applications will not violate any third party rights (including intellectual property rights and rights of privacy or publicity) or any laws, rules, regulations or orders, including those relating to data privacy, data transfer, international communications and the export of technical or personal data (“Laws”);
  3. all information you provide to iPayroll is and will be true, accurate, and complete; and
  4. you will not interfere with iPayroll’s business practices, the way in which it offers the iPayroll Service or the API Developer Platform or any third party products or networks used with the API Developer Platform.

You will indemnify, defend (at iPayroll’s request) and hold harmless iPayroll and its affiliates and their respective directors, officers, employees, agents, contractors, end users and licensees from and against any claims, losses, costs, expenses (including reasonable attorneys’ fees), damages or liabilities based on or arising from:

  1. your use of the API Developer Platform,
  2. your Applications and your relationships or interactions with any users or third party distributors of Your Applications, or
  3. your breach or alleged breach of these Terms.

iPayroll may at its own expense participate in the defense and settlement of any claim with its own counsel, and you may not settle a claim without iPayroll’s prior written consent (not to be unreasonably withheld).

Disclaimer of Warranties

THE API DEVELOPER PLATFORM, iPAYROLL SERVICE ARE PROVIDED “AS IS” AND “WITH ALL FAULTS”. iPAYROLL AND ITS THIRD PARTY LICENSORS DISCLAIM ALL REPRESENTATIONS, WARRANTIES AND GUARANTEES, WHETHER EXPRESS, IMPLIED OR STATUTORY, INCLUDING IMPLIED WARRANTIES OF MERCHANTABILITY, TITLE, NON-INFRINGEMENT AND FITNESS FOR ANY PURPOSE. iPAYROLL MAKES NO REPRESENTATION, WARRANTY OR GUARANTEE (A) RELATED TO RELIABILITY, ACCURACY, OR COMPLETENESS OF THE API DEVELOPER PLATFORM OR ANY iPAYROLL MATERIALS, (B) THAT iPAYROLL WILL CONTINUE TO OFFER THE API DEVELOPER PLATFORM OR (C) THAT USE OF ANY iPAYROLL MATERIALS WILL BE SECURE, TIMELY, UNINTERRUPTED, ERROR-FREE OR MEET PARTNER’S REQUIREMENTS OR EXPECTATIONS.

You may have other statutory rights, in which case the disclaimers above will apply to the full extent permitted by law.

Limitation of Liabilities

TO THE MAXIMUM EXTENT PERMITTED BY LAW: (A) iPAYROLL WILL NOT BE LIABLE FOR ANY LOSS OF USE, LOST OR INACCURATE DATA, FAILURE OF SECURITY MECHANISMS, INTERRUPTION OF BUSINESS, COSTS OF DELAY OR ANY INDIRECT, CONSEQUENTIAL, SPECIAL, EXEMPLARY, PUNITIVE, OR OTHER LIABILITY RELATED TO THE iPAYROLL MATERIALS OR OTHERWISE UNDER THESE TERMS, WHETHER IN CONTRACT, TORT OR ANY OTHER LEGAL THEORY; AND (B) IN ANY EVENT iPAYROLL’S ENTIRE AGGREGATE LIABILITY UNDER THESE TERMS WILL BE LIMITED TO THE GREATER OF (1) THE AMOUNT YOU PAID US (IF ANY) TO USE THE API DEVELOPER PLATFORM IN THE TWELVE (12) MONTHS PRECEDING THE CLAIM OR (2) ONE THOUSAND U.S. DOLLARS (US$1,000).

You acknowledge and agree that this Section reflects a reasonable allocation of risk and that iPayroll would not enter into these Terms without these liability limitations. This Section will survive notwithstanding any limited remedy’s failure of essential purpose.

Intellectual Property Rights and Additional Terms

iPayroll Independent Development and Patent Issues

You understand and acknowledge that iPayroll may be independently creating (or may receive from third parties) features, applications, content, or other products or services that may be similar to or competitive with Your Application, and nothing in these Terms will be construed as restricting or preventing iPayroll from doing so.

In addition, in order to allow others to benefit from the API Developer Platform, you agree not to assert (or assist or encourage anyone in asserting) any patent claims against iPayroll (or its users, customers partners or developers, or iPayroll’s or their respective successors, assigns) where such patent claim relates to the integration, combination or interface of any applications, products or services with the iPayroll Service or our other products or services.

Title Rights
The title rights, copyrights and all other rights of intellectual property whatsoever in any information, software, material, technique, procedure or other know-how produced for or used in providing the Services pursuant to the provisions of this Agreement shall remain vested exclusively in iPayroll.

Confidential Information

a. iPayroll Confidential Information
iPayroll may provide certain information to you that is confidential or proprietary (“iPayroll Confidential Information”). iPayroll Confidential Information consists of

(a) your access keys or logins for the API Developer Platform, any non-public elements of the API Developer Platform or any pre-release information about the iPayroll Service and

(b) anything identified or marked as “Confidential” or “Proprietary” or that you should reasonably understand to be confidential or proprietary under the circumstances. You may use iPayroll Confidential Information only for the purposes of these Terms.

You may not disclose any iPayroll Confidential Information to third parties, other than your employees, agents and advisors with a need to know and for whom you agree to remain responsible under these Terms.

b. Your Confidential Information
You should not disclose any information to iPayroll that you consider to be confidential. To avoid any potential confusion, you agree that any unsolicited information you provide to iPayroll in relation to the API Developer Platform will be non-confidential and that iPayroll may use it under the same terms as for Feedback above. However, this Confidential Information Section (b) does not apply to the extent you have entered into a separate non-disclosure agreement (NDA) or other confidentiality terms with iPayroll addressing your confidential information in relation to the API Developer Platform.

Term and Termination

These Terms remain in effect until terminated. You may terminate these Terms at any time by ceasing all use of the API Developer Platform and notifying iPayroll.

We may terminate these Terms for any reason upon ten (10) days’ notice to you.

In addition, we may suspend or terminate these Terms (or your use of all or any of the API Developer Platform) immediately:

  • if we believe you have violated these Terms,
  • if we believe the use of Your Application with the API Developer Platform is not in our or our users’ best interests,
  • if we cease to offer the API Developer Platform,
  • or as required by Laws.

Upon termination of these Terms:

  • all rights and licenses granted to you will terminate immediately and you must stop using all iPayroll API Services;
  • neither party is liable to the other party just because the agreement has been terminated; and
  • you must permanently delete all iPayroll Confidential Information and any other data which you stored pursuant to your use of the API Developer Platform (other than User Data you have received and are using in accordance with Section 7(a)), and,
  • at iPayroll’s request, you will confirm such destruction.

Modification to Terms

We may modify these Terms or any additional terms that apply to the API Developer Platform occasionally, for example, to reflect changes to the Law, changes to the API Developer Platform or for other reasons in our discretion.

We’ll post notice of modifications to these Terms or the additional terms within the documentation for the API Developer Platform. Changes are effective thirty (30) days after they are posted. However, changes specific to new functionality for the API Developer Platform, changes made for legal reasons, and any changes to our Documentation or referenced policies will be effective immediately.

You may be required to accept the modified Terms in order to continue using the API Developer Platform, and in any event you agree that your continued use of the API Developer Platform after the changes become effective constitutes acceptance of the modified terms.

Except as set forth in this Section, all amendments must be in writing and signed by both parties.

 

Developer Responsibilities

Using an API Developer Account comes with responsibility and you agree to Do the Right Thing when using our APIs.

As a Developer or Vendor using the API Developer Platform you will be using our Platform along with other developers. Our expectation is that you should write and use your API consuming application or service in a responsible manner so that other users are not impacted.

In addition to agreeing to our Terms and Conditions you agree not to use (or permit any third party to use) the API Developer Platform to:

  • Use organisational or employee data to assist with any unsolicited marketing communication (electronic or otherwise) to any person or third party.
  • Submit to the iPayroll or CloudPayroll API Developer Platform or Service any viruses, defects, malware, or other items of a destructive nature.
  • Create an API or similar function for your application or website designed to offer functionality substantially similar to ours for use by third parties.
  • Use the API Developer Platform for competitive purposes including using API Data with a competitive product (or in order to create your own competitive product).
  • Transfer (or resell) any data provided through the API Developer Platform to any third party and/or use (or permit any third party to use) iPayroll or CloudPayroll data for any purpose not directly related to the purpose it was collected (that is, payroll).

  • Exceed or evade limitations on API calls, circumvent security or access controls, automate data interaction outside the API Developer Platform, or use your application in a way that would negatively impact iPayroll or CloudPayroll's service.

Security and Privacy

API Privacy Guidelines

Privacy Guidelines for API Developer Partners

In Australia and New Zealand, the key privacy legislation applying to API Developer Access for iPayroll and CloudPayroll are the Australian Privacy Act 1988 and the New Zealand Privacy Act 2020.

The Australian Privacy Act applies to most private sector organisations operating in Australia and sets a national standard for the collection, use and disclosure, quality and security of “Personal Information”. In particular, the Privacy Act establishes the Australian Privacy Principles (APPs) (effective from 12 March 2014) that sets out these key obligations.

Similar to the Australian Privacy Principles (APP), New Zealand law lays out the NZ Privacy Act as 13 New Zealand Information Privacy Principles (NZ IPPs) for the proper handling of personal information. The Act and 13 IPPs presume that trans-border data flows are permissible provided the APP and NZ IPPs are preserved, which is the case with iPayroll and CloudPayroll.

Privacy Responsibilities

We manage and store a range of organisational, financial and personal information on your behalf for the purposes of processing your payroll.

In line with privacy laws this information is used solely for the completion of this activity.

This information is never made available to any other parties, except for any information transfer directly required to complete your payroll. Our policies for accessing data via the API Developer Platform are compliant with both the Australian Privacy Act and and New Zealand Privacy Act.

For both New Zealand and Australian privacy laws, iPayroll and CloudPayroll act as the processor, not collector of the data, of an organisation's employees. Users of the iPayroll API Developer Platform agree to follow these privacy laws and must specifically agree to the following privacy principles which are directly related to API data access.

Primary Privacy Principles

In addition to agreeing to follow the security expectations, API Developer Partners must ensure privacy principles are followed for any iPayroll or CloudPayroll data retrieved via APIs. In addition to following the overarching standards listed above API Developer Partners must agree to the following principles:

Use of Personal Information
NZ Principles 1, 10 & 11 and AU Principles 1, 6 & 7 refer to the principle that personal information can only be used for the purpose it was collected, or if the person in question gives their permission for their information to be used in a different way (including direct marketing purposes).

NZ Principle 12 and AU Principle 8 also relates to disclosure of personal information and specifies that personal information should not be shared with parties outside New Zealand and/or Australia unless that third party can adequately protect the information and is subject to privacy laws that provide comparable safeguards to the Privacy Act.

Retention
NZ Principle 9 states that an organisation should not keep personal information for longer than it is required for the purpose it may lawfully be used.

Security of Personal Information
NZ Principle 5 and AU Principle 11 specify that organisations must ensure there are safeguards in place that are reasonable in the circumstances to prevent loss, misuse or disclosure of personal information, and from unauthorised access, modification or disclosure.

You must also agree to follow the Security Expectations for API Developer Partners and agree to complete an API Security Questionnaire self assessment and agree to update the questionnaire on an annual basis.

Security Expectations

Security Expectations for API Developer Partners

Certified API Developer Partners must at all times ensure that any iPayroll or CloudPayroll data retrieved via APIs which is held in their systems is accessed and stored in a secure way.

The API Developer guidelines are based on security and privacy industry best practices defined by:

These security and privacy requirements are mandatory for all API Developers, Vendors, Contractors and Organisations that maintain active API connections.

In order to gain access to our API Developer Partner Programme all API Developer Partners must complete an API Security Questionnaire self assessment, and agree to review and update their questionnaire on an annual basis.

Security Breaches
In the event of any breach of security (or possible breach) which has the potential to expose personal or sensitive information such as payroll customer data, public/private key certificates, tokens or other sensitive details, the partner must immediately advise us by emailing security@ipayroll.co.nz or security@cloudpayroll.com.au.

Access Control
Access control mechanisms must exist for your staff and any third parties on your behalf, and you should ensure that policies are set regarding the appropriate access to and use of data. Access control policies should include mechanisms for ensuring access is removed from staff who no longer require access.

Sensitive Data
Highly sensitive data such as security keys or signing certificates used to sign requests should be securely stored. Access to sensitive data should be strictly controlled and not publicly accessible (for example, certificates should not be stored under the public web root).

Privacy policy
All API Developer Partners should have a privacy policy which must be accessible from their website.

Software Development
We encourage API Developer Partners to follow the security best practices for your specific programming language and platform, and to become familiar with web security issues you may encounter (for example, follow best practices for security such as The OWASP top 10).

Hosting
Where vendor integrations have an online presence, shared hosting environments should not be used, as there’s a risk that other users could be able to access your iPayroll or CloudPayroll API credentials, sensitive data or access APIs.

Server infrastructure configuration should follow industry accepted hardening practices.

Authentication
Strong authentication to your systems with multi-factor authentication (MFA) enabled is highly recommended.

Encryption
At a minimum, SSL should be used for application logins. All sensitive or private data must be encrypted during transfer. It is recommended all logged in pages are secured with SSL. (SSL should use TLS version 1.2 using AES 256 or higher).

Data repositories that hold or manage sensitive commercial or personal information should be encrypted at rest, using full-disk encryption and/or container-encryption.

Privacy
Data should only be stored in New Zealand or Australia.

Personally Identifiable Information (PII) should not be made available to third parties without prior consent.

You must agree to follow the privacy principles and guidelines defined under the New Zealand Privacy Principles or Australian Privacy Principles..

Data Collection and Retention
Only data which is relevant and necessary should be accessed or collected (for example, when using APIs, only access the smallest amount of personal information you need to complete a task).

Safeguards must be in place to ensure there is no data loss, misuse or disclosure of personal information.

Personal information may not be kept indefinitely and should not be retained for longer than is necessary for the purposes for which it may lawfully be used.

Non-Compliance
What happens if I don’t fulfil these security standards and how do I gain compliance?

Where a consumer of iPayroll or CloudPayroll’s APIs does not adequately comply with these specifications, we will issue them written notice giving them 30 days to advise the plan for becoming compliant. With up to a further 60 days to complete the required remediation.

 

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

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.

Environments

Both iPayroll and CloudPayroll provide two API environments.

Developer

  • https://demo.ipayroll.co.nz - This is the test environment for iPayroll used when developing and testing your applications.
  • https://demo.cloudpayroll.com.au - This is the test environment for CloudPayroll used when developing and testing your applications.

Production

  • https://secure2.ipayroll.co.nz - This is the live production system for iPayroll.
  • https://secure2.cloudpayroll.com.au - This is the live production system for CloudPayroll.

Remember: These environments require the use of HTTPS.

Base URL

All URLs referenced in the documentation have the following base:

  • https://secure2.ipayroll.co.nz/api/v1 (iPayroll)
  • https://secure2.cloudpayroll.com.au/api/v1 (CloudPayroll)

The iPayroll REST API is served over HTTPS. Plain HTTP is not supported.

Requests

All requests to iPayroll API endpoints 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
JSON Object JavaScript Object Notation {"foo" : "bar"}

Retrieving Resources with HTTP GET

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

Response Format

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

API Reference

Date Formats

Definition of letters used:

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

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

  • dd-MM-yyyy
  • dd-MMM-yyyy
  • yyyy-MM-dd
  • yyyy-MMM-dd
  • dd/MM/yy
  • dd/MM/yyyy
  • dd/MMM/yy
  • dd/MMM/yyyy
  • MM/dd/yy
  • MM/dd/yyyy
  • dd/MM
  • dd/MMM

Links

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

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

Functionality

Functionality includes, but is not limited to:

  • Get, create and 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, create, update and delete parental leave for an employee (NZ only)Get a general ledger journal for a pay date or a payroll
  • Get a list of user defined groups

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:

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

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

See Resources for the list of requests that can be made, along with the scopes that are required to make the specific requests.

API Rate Limits

There are limits to the number of API calls that your application can make against a particular organisation:

  • Concurrent Limit: 5 calls in progress at one time
  • Daily Limit: 5000 calls per day

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"
		}
	]
  },
  ...
]

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

Employee Superannuation

This is only used in Australian organisations so is only applicable to Australian customers.

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

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

Retrieve all employee superannuation transactions

(Scope: employees)

Returns all the superannuation transactions for an employee.

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

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

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

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.

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.
When User Defined Groups are disabled for an organisation, this field is optional. Alternatively, the value ‘DEFAULT’ can be used whether User Defined Groups are enabled or not.
paymentMethod String Method of the employee is being paid. Code and Description are supported.
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 AU only: Termination reason of the employee
deathBenefitSurname String AU only: Death beneficiaries Surname
deathBenefitFirstName String AU only: Death beneficiaries First Name
deathBenefitRecipient String AU only: Death benefit recipient. Code and Description are supported.
Code Description
DEPENDANT Dependent
NON_DEPENDANT Non Dependent
TRUSTEE Trustee
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 NZ only: Special Student Loan rates of the employee
specialEarnerLevy Number NZ only: Special Earner Levy rate of the employee
specialExtraPayRate Number NZ only: Special Extra Pay Rate of the employee
hasDebt Boolean AU only: Higher Education Loan Program (HELP), VET Student Loan (VSL), Financial Supplement (FS), Student Start-up Loan (SSL) or Trade Support Loan (TSL) Debt
helpDebt Boolean AU only: HELP Debt. This attribute is legacy as of 15-Nov-2021 and is replaced by hasDebt.
sfssDebt Boolean AU only: SFSS Debt. This attribute is legacy as of 15-Nov-2021 and is replaced by hasDebt.
medicareLevyVariationDeclaration Boolean AU only: Has the employee filled a Medicare levy variation declaration
hasSpouse Boolean AU only: Spouse
incomeLessThanRelevantAmount Boolean AU only: Is the combined weekly income of payee and payee's spouse, or the payee's income as a sole parent, less than the relevant amount in table A
payrollTaxExempt Boolean AU only: Payroll Tax Exempt
dependentChildren Number AU only: Number of dependent children of the employee
surchargeIncrease Number AU only: Surcharge increase
employmentBasisType String AU only
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_RESIDENT
 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: For workPerformedOverseas=true, this is the overseas country employee is working in. For residenceType=WORKING_HOLIDAY, this is the overseas country employee is from.
closelyHeldPayee Boolean AU only: True if individual is directly related to entity.
Organisation setting must be enabled.
taxFreeThresholdType String AU only: Mandatory if taxTreatmentType is either REGULAR or ACTORS.
Code Description
CLAIMED Claimed
NOT_CLAIMED Not Claimed
specifiedRateAppliesTo String Array AU only: specifies what types of tax the specialTax applies to
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
lastModifiedDate String The date the employee record was last changed by a user.
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 (NZ)
Yes (AU)		 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.
When User Defined Groups are disabled for an organisation, this field is optional. Alternatively, the value ‘DEFAULT’ can be used whether User Defined Groups are enabled or not.
paymentMethod Yes String Method of the employee is being paid. Code and Description are supported.
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 AU only: Termination reason of the employee
deathBenefitSurname No String AU only: Death beneficiaries Surname
deathBenefitFirstName No String AU only: Death beneficiaries First Name
deathBenefitRecipient No String AU only: Death benefit recipient. Code and Description are supported.
Code Description
DEPENDANT Dependent
NON_DEPENDANT Non Dependent
TRUSTEE Trustee
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 NZ only: Special Student Loan rates of the employee
specialEarnerLevy No Number NZ only: Special Earner Levy rate of the employee
specialExtraPayRate No Number NZ only: Special Extra Pay Rate of the employee
hasDebt No Boolean AU only: Higher Education Loan Program (HELP), VET Student Loan (VSL), Financial Supplement (FS), Student Start-up Loan (SSL) or Trade Support Loan (TSL) Debt
helpDebt No Boolean AU only: HELP Debt. This attribute is legacy as of 15-Nov-2021 and is replaced by hasDebt.
sfssDebt No Boolean AU only: SFSS Debt. This attribute is legacy as of 15-Nov-2021 and is replaced by hasDebt.
medicareLevyVariationDeclaration No Boolean AU only: Has the employee filled a Medicare levy variation declaration
hasSpouse No Boolean AU only: Spouse
incomeLessThanRelevantAmount No Boolean AU only: Is the combined weekly income of payee and payee's spouse, or the payee's income as a sole parent, less than the relevant amount in table A
payrollTaxExempt No Boolean AU only: Payroll Tax Exempt
dependentChildren No Number AU only: Number of dependent children of the employee
surchargeIncrease No Number AU only: Surcharge increase
employmentBasisType Yes String AU only
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_RESIDENT
 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: For workPerformedOverseas=true, this is the overseas country employee is working in. For residenceType=WORKING_HOLIDAY, this is the overseas country employee is from.
closelyHeldPayee No Boolean AU only: True if individual is directly related to entity.
Organisation setting must be enabled.
taxFreeThresholdType No String AU only: Mandatory if taxTreatmentType is either REGULAR or ACTORS.
Code Description
CLAIMED Claimed
NOT_CLAIMED Not Claimed
specifiedRateAppliesTo No String Array AU only: specifies what types of tax the specialTax applies to
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 (NZ)
Yes (AU)		 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.
When User Defined Groups are disabled for an organisation, this field is optional. Alternatively, the value ‘DEFAULT’ can be used whether User Defined Groups are enabled or not.
paymentMethod Yes String Method of the employee is being paid. Code and Description are supported.
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 AU only: Termination reason of the employee
deathBenefitSurname No String AU only: Death beneficiaries Surname
deathBenefitFirstName No String AU only: Death beneficiaries First Name
deathBenefitRecipient No String AU only: Death benefit recipient. Code and Description are supported.
Code Description
DEPENDANT Dependent
NON_DEPENDANT Non Dependent
TRUSTEE Trustee
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 NZ only: Special Student Loan rates of the employee
specialEarnerLevy No Number NZ only: Special Earner Levy rate of the employee
specialExtraPayRate No Number NZ only: Special Extra Pay Rate of the employee
hasDebt No Boolean AU only: Higher Education Loan Program (HELP), VET Student Loan (VSL), Financial Supplement (FS), Student Start-up Loan (SSL) or Trade Support Loan (TSL) Debt
helpDebt No Boolean AU only: HELP Debt. This attribute is legacy as of 15-Nov-2021 and is replaced by hasDebt.
sfssDebt No Boolean AU only: SFSS Debt. This attribute is legacy as of 15-Nov-2021 and is replaced by hasDebt.
medicareLevyVariationDeclaration No Boolean AU only: Has the employee filled a Medicare levy variation declaration
hasSpouse No Boolean AU only: Spouse
incomeLessThanRelevantAmount No Boolean AU only: Is the combined weekly income of payee and payee's spouse, or the payee's income as a sole parent, less than the relevant amount in table A
payrollTaxExempt No Boolean AU only: Payroll Tax Exempt
dependentChildren No Number AU only: Number of dependent children of the employee
surchargeIncrease No Number AU only: Surcharge increase
employmentBasisType Yes String AU only
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_RESIDENT
 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: For workPerformedOverseas=true, this is the overseas country employee is working in. For residenceType=WORKING_HOLIDAY, this is the overseas country employee is from.
closelyHeldPayee No Boolean AU only: True if individual is directly related to entity.
Organisation setting must be enabled.
taxFreeThresholdType No String AU only: Mandatory if taxTreatmentType is either REGULAR or ACTORS.
Code Description
CLAIMED Claimed
NOT_CLAIMED Not Claimed
specifiedRateAppliesTo No String Array  AU only: specifies what types of tax the specialTax applies to
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" 
      }
   ]
}

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": []
}

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

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).
surname String Surname of the employee
firstNames String All first names
preferredName String Preferred Name of the employee
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"
dateFrom No String The start date of the leave request (multiple date formats supported, dd/mm/yyyy preferred)
dateTo No String The end date of the leave request (multiple date formats supported, dd/mm/yyyy preferred)
Sample requests

GET /api/v1/leaves/requests?status=Pending&leaveBalanceType=Annual%20Leave&dateFrom=04/10/2024&dateTo=04/10/2024

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

GET /api/v1/leaves/requests

GET /api/v1/leaves/requests?dateFrom=04/10/2024

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

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

Response Example

{
   "links":[
      {
         "rel":"self",
         "href":"https://secure2.ipayroll.co.nz/api/v1/leaves/requests?status=Approved&leaveBalanceType=Annual%20Leave&dateFrom=01/01/2017&andTo=01/01/2025"
      }
   ],
   "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",
         "surname": "Caroline",
         "firstNames": "Jackie",
         "preferredName": "Jackie",
         "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",
   "surname": "Caroline",
   "firstNames": "Jackie",
   "preferredName": "Jackie",
   "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",
         "surname": "Caroline",
         "firstNames": "Jackie",
         "preferredName": "Jackie",
         "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
dateFrom No String The start date of the leave request (multiple date formats supported, dd/mm/yyyy preferred)
dateTo No String The end date of the leave request (multiple date formats supported, dd/mm/yyyy preferred)

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

Response Example

{
   "links":[
      {
         "rel":"self",
         "href":"https://secure2.ipayroll.co.nz/api/v1/employees/1/leaves/requests?status=Pending&dateFrom=01/01/2017&andTo=01/01/2025""
      }
   ],
   "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",
         "surname": "Caroline",
         "firstNames": "Jackie",
         "preferredName": "Jackie",
         "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",
         "surname": "Caroline",
         "firstNames": "Jackie",
         "preferredName": "Jackie",
         "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",
         "surname": "Caroline",
         "firstNames": "Jackie",
         "preferredName": "Jackie",
         "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",
   "surname": "Caroline",
   "firstNames": "Jackie",
   "preferredName": "Jackie",
   "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",
   "surname": "Caroline",
   "firstNames": "Jackie",
   "preferredName": "Jackie",
   "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",   
   "surname": "Caroline",
   "firstNames": "Jackie",
   "preferredName": "Jackie",
   "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"
      }
   ]
}

Parental Leave

This is only used in New Zealand organisations so is only applicable to New Zealand customers.

Attributes
Name Type Description
id Number Unique ID to identify a parental leave
employeeId String Unique ID to identify an employee within an organisation.
Limited to a-z, A-Z, 0-9, _ (underscore) and - (hyphen).
startDate String First day of parental leave (multiple date formats supported, dd/mm/yyyy preferred)
plannedEndDate String Planned end day of parental leave (multiple date formats supported, dd/mm/yyyy preferred)
actualEndDate String Actual end day of parental leave (multiple date formats supported, dd/mm/yyyy preferred)

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

Retrieve all parental leave for an employee

(Scopes: parentalleaves employees)

Returns all current and historical parental leave for an employee.

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

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

Response Example

{
    "links": [
        {
            "rel": "self",
            "href":"https://secure2.ipayroll.co.nz/api/v1/employees/1/leaves/parental"
        }
    ],
    "content": [
        {
            "employeeId": "1",
            "startDate": "29-Jun-2021",
            "plannedEndDate": "29-Jun-2022",
            "actualEndDate": "29-May-2021",
            "links": [
                {
                    "rel": "self",
                    "href":"https://secure2.ipayroll.co.nz/api/v1/employees/1/leaves/parental/76"
                }
            ],
            "id": "76"
        }
    ],
    "page": {
        "size": 20,
        "totalElements": 1,
        "totalPages": 1,
        "number": 0
    }
 }

GET /api/v1/employees/{employeeId}/leaves/parental/{parentalLeaveId}

Retrieve a parental leave

(Scopes: parentalleaves employees)

Returns a specific parental leave for an employee

Path Parameters
Name Required Type Description
employeeId Yes String Unique ID to identify an employee within an organisation.
Limited to a-z, A-Z, 0-9, _ (underscore) and - (hyphen).
parentalLeaveId Yes Number Unique ID to identify a parental leave. Use "current" to retrieve the currently active parental leave for the employee.

GET /api/v1/employees/{employeeId}/leaves/parental/{parentalLeaveId}

Response Example

{
    "employeeId": "1",
    "startDate": "29-Jun-2021",
    "plannedEndDate": "29-Jun-2022",
    "actualEndDate": "29-May-2021",
    "links": [
        {
            "rel": "self",
            "href":"https://secure2.ipayroll.co.nz/api/v1/employees/1/leaves/parental/76"
        }
    ],
    "id": "76"
 }

POST /api/v1/employees/{employeeId}/leaves/parental

Create a parental leave

(Scopes: parentalleaves employees)

Creates a parental leave for an employee.

Path Parameters
Name Required Type Description
employeeId Yes String Unique ID to identify an employee within an organisation.
Limited to a-z, A-Z, 0-9, _ (underscore) and - (hyphen).
Request Body Properties
Name Required Type Description
startDate Yes String First day of parental leave (multiple date formats supported, dd/mm/yyyy preferred)
plannedEndDate Yes String Planned end day of parental leave (multiple date formats supported, dd/mm/yyyy preferred)
actualEndDate No String Actual end day of parental leave. If provided, a historical parental leave will be created. If not provided a current parental leave will be created. (multiple date formats supported, dd/mm/yyyy preferred)
hoursPerPayPeriod Yes Number Total hours per pay period

POST /api/v1/employees/{employeeId}/leaves/parental

Request Body Example

{
    "startDate": "29-Jun-2021",
    "plannedEndDate": "29-Jun-2022",
    "actualEndDate": "29-May-2021",
    "hoursPerPayPeriod": 37.5
}

Response Example

{
    "employeeId": "1",
    "startDate": "29-Jun-2021",
    "plannedEndDate": "29-Jun-2022",
    "actualEndDate": "29-May-2021",
    "hoursPerPayPeriod": 37.5
    "links": [
        {
            "rel": "self",
            "href":"https://secure2.ipayroll.co.nz/api/v1/employees/1/leaves/parental/76"
        }
    ],
    "id": "76"
}

PUT /api/v1/employees/{employeeId}/leaves/parental/{parentalLeaveId}

Update a parental leave

(Scopes: parentalleaves employees)

Update a parental leave for an employee.

Path Parameters
Name Required Type Description
employeeId Yes String Unique ID to identify an employee within an organisation.
Limited to a-z, A-Z, 0-9, _ (underscore) and - (hyphen).
parentalLeaveId Yes Number Unique ID to identify a parental leave. Use "current" to update the currently active parental leave for the employee.
Request Body Properties
Name Required Type Description
startDate No String First day of parental leave (multiple date formats supported, dd/mm/yyyy preferred)
plannedEndDate No String Planned end day of parental leave (multiple date formats supported, dd/mm/yyyy preferred)
actualEndDate No String Actual end day of parental leave. When provided for a current parental leave, this will return the employee from parental leave. (multiple date formats supported, dd/mm/yyyy preferred)

PUT /api/v1/employees/{employeeId}/leaves/parental/{parentalLeaveId}

Request Body Example

{
    "startDate": "29-Jun-2021",
    "plannedEndDate": "29-Jun-2022",
    "actualEndDate": "29-May-2021"
}

Response Example

{
    "employeeId": "1",
    "startDate": "29-Jun-2021",
    "plannedEndDate": "29-Jun-2022",
    "actualEndDate": "29-May-2021"
    "links": [
        {
            "rel": "self",
            "href":"https://secure2.ipayroll.co.nz/api/v1/employees/1/leaves/parental/76"
        }
    ],
    "id": "76"
}

DELETE /api/v1/employees/{employeeId}/leaves/parental/current

Delete a parental leave

(Scopes: parentalleaves employees)

Deletes the current parental leave for an employee.

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

DELETE /api/v1/employees/{employeeId}/leaves/parental/current

Empty response.

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
}

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

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

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 Australia only.
The Australian business number. This field would not be there for non-Australian organisations. This attribute is legacy as of 14-Sep-2022 and is replaced by organisationAbnOrWpn and textAbnOrWpn.
organisationAbnOrWpn String Australia only.
The Australian business number (ABN) or withholding payer number (WPN) - only applicable to Australian organisations.
textAbnOrWpn String Australia only.
The payer type. Either abn or wpn.
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,
        "timesheetType": "byPeriod",
        "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,
        "timesheetType": "byPeriod",
        "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,
        "timesheetType": "byPeriod",
        "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,
        "timesheetType": "byPeriod",
        "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.

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 NZ only: 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,
          "timesheetType": "byPeriod",
          "amount": 0,
          "quantity": 1,
          "rate": 0,
          "description": "BANK - Take Home Pay to BANK_NUMBER",
          "costCentre": "",
          "payElement": "BANK"
        },
        {
          "links": [],
          "timesheetTransactionId": 993589,
          "timesheetType": "byPeriod",
          "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,
        "timesheetType": "byPeriod",
        "amount": 0,
        "quantity": 1,
        "rate": 0,
        "description": "BANK - Take Home Pay to BANK_NUMBER",
        "costCentre": "",
        "payElement": "BANK"
      },
      {
        "links": [],
        "timesheetTransactionId": 993589,
        "timesheetType": "byPeriod",
        "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,
          "timesheetType": "byPeriod",
          "amount": 0,
          "quantity": 1,
          "rate": 0,
          "description": "BANK - Take Home Pay to BANK_NUMBER",
          "costCentre": "",
          "payElement": "BANK"
        },
        {
          "links": [],
          "timesheetTransactionId": 993589,
          "timesheetType": "byPeriod",
          "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,
          "timesheetType": "byPeriod",
          "amount": 0,
          "quantity": 1,
          "rate": 0,
          "description": "BANK - Take Home Pay to BANK_NUMBER",
          "costCentre": "",
          "payElement": "BANK"
        },
        {
          "links": [],
          "timesheetTransactionId": 993589,
          "timesheetType": "byPeriod",
          "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,
        "timesheetType": "byPeriod",
        "amount": 0,
        "quantity": 1,
        "rate": 0,
        "description": "BANK - Take Home Pay to BANK_NUMBER",
        "costCentre": "",
        "payElement": "BANK"
      },
      {
        "links": [],
        "timesheetTransactionId": 993589,
        "timesheetType": "byPeriod",
        "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,
        "timesheetType": "byPeriod",
        "amount": 0,
        "quantity": 1,
        "rate": 0,
        "description": "BANK - Take Home Pay to BANK_NUMBER",
        "costCentre": "",
        "payElement": "BANK"
      },
      {
        "links": [],
        "timesheetTransactionId": 993589,
        "timesheetType": "byPeriod",
        "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 NZ only: 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,
        "timesheetType": "byPeriod",
        "amount": 0,
        "quantity": 1,
        "rate": 0,
        "description": "BANK - Take Home Pay to BANK_NUMBER",
        "costCentre": "",
        "payElement": "BANK"
      },
      {
        "links": [],
        "timesheetTransactionId": 993589,
        "timesheetType": "byPeriod",
        "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.

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