API Reference

The iPayroll REST API allows you to query and manipulate data held by iPayroll about organisations and their employees. It uses predictable, resource-oriented URLs, and communicates API errors using HTTP response codes.

The iPayroll API uses standard HTTP Verbs, JSON and Oauth2.

The API can be used directly by clients developing their own applications. Third party applications can also be authorised by clients to access information on their behalf.

Base URL

All URLs referenced in the documentation have the following base:
https://secure2.ipayroll.co.nz/api/v1

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

Functionality

The iPayroll API supports the following actions:

  • Get employees
  • Create employees
  • Get pay rates for an employee
  • Get payslips
  • Get leave balances for an employee
  • Get leave requests
  • Get timesheets associated with the latest payroll
  • Get cost centres
  • Create cost centres
  • Get pay elements

Scopes

Data available via The iPayroll API is grouped into scopes.

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

The iPayroll API supports the following scopes:

  • Employees
  • Timesheets
  • Pay Rates
  • Costcentres
  • Leave Balances
  • Leave Requests
  • Payslips
  • Pay Elements

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

Getting Started

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

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

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

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

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

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

Developer Overview

Technologies used

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

Environments

iPayroll provides two API environments.

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

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

Remember: Those environments require use of HTTPS.

Requests

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

We provide a detailed authentication and authorisation guide in the Authorisation How to.

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

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

Retrieving Resources with HTTP GET

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

Response Format

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

Date Formats

Definition of letters used:

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

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

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

Pagination

Some of the end points provided by the iPayroll API return multiple elements. These would typically be 'get all' requests such as 'list employees' or 'list cost centres'.

To avoid large payloads, the iPayroll API supports pagination for this type of requests, and will default to returning maximum 20 elements.

{ 
  "content": [
    {element 1},
    {element 2},
    {element 3},
    {element 4},
  ],
  "page": {
    "size": 20,
    "totalElements": 4,
    "totalPages": 1,
    "number": 0
  }
}

The iPayroll API lets you control page data by using the page and size request parameters:

http://sandbox.ipayroll.co.nz/api/v1/employees?size=5
http://sandbox.ipayroll.co.nz/api/v1/employees?size=5&page=2
  • size: an integer denoting how many elements to return per page
  • page: an integer denoting the page number (zero based) required.

When paging is applicable, the response will contain links to navigate through pages:

{
  "content": [
    ...elements of this page...
  ],
  "page": {
    "size": 5,
    "totalElements": 23,
    "totalPages": 5,
    "number": 0
  },
  "links": [
    {
      "rel": "first",
      "href": "http://sandbox.ipayroll.co.nz/api/v1/employees?page=0&size=5"
    },
    {
      "rel": "self",
      "href": "http://sandbox.ipayroll.co.nz/api/v1/employees?size=5"
    },
    {
    "rel": "next",
    "href": "http://sandbox.ipayroll.co.nz/api/v1/employees?page=1&size=5"
    },
    {
      "rel": "last",
      "href": "http://sandbox.ipayroll.co.nz/api/v1/employees?page=4&size=5"
    }
  ]
}

Error handling

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

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

Resources

Cost Centres

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

Attributes
Name Type Description
costCentreId Integer Unique system generated id
code String The name of the cost centre. Unique within an organisation
description String Cost centre description

GET /api/v1/costcentres

Retrieve All Cost Centres

Returns all the cost centres of an organisation.

GET /api/v1/costcentres

Response Example

{
  "content": [
	{
	  "links": [
		{
		  "rel": "self",
		  "href": "http://secure2.ipayroll.co.nz/api/v1/costcentres/0"
		}
	  ],
	  "costCentreId": 0,
	  "code": "Software",
	  "description": "Software Developers Department"
	},
	{
	  "links": [
		{
		  "rel": "self",
		  "href": "http://secure2.ipayroll.co.nz/api/v1/costcentres/1"
		}
	  ],
	  "costCentreId": 1,
	  "code": "Marketing",
	  "description": "The Marketing Team"
	},
	...
  ]
}

POST /api/v1/costcentres

Create One Or More Cost Centres

Create one or more cost centres in an organisation.

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

POST /api/v1/costcentres

Request Body Example

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

Response Example

[
  {    
	"code": "Software",
	"description": "Software Developers Department"
	"links": [
		{
		  "rel": "self",
		  "href": "http://secure2.ipayroll.co.nz/api/v1/costcentres/0"
		}
	]
  }, 
  {    
	"code": "Marketing",
	"description": "The Marketing Team"
	"links": [
		{
		  "rel": "self",
		  "href": "http://secure2.ipayroll.co.nz/api/v1/costcentres/1"
		}
	]
  }, 
  ...
]

GET /api/v1/costcentres/{costcentreId}

Retrieve A Cost Centre

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

Parameters
Name Required Type Description
costcentreId Yes Integer Unique system generated id

GET /api/v1/costcentres/{costcentreId}

Response Example

[
  {
	"code": "Software",
	"description": "Software Developers Department",    
	"links": [
	  {
		"rel": "self",
		"href": "http://secure2.ipayroll.co.nz/api/v1/costcentres/0"
	  }
	]
  }, 
  ...
]

Employees

Attributes
Name Type Description
employeeId String Unique ID to identify an employee within an organisation
birthDate String Date of birth (multiple date formats supported, dd/mm/yyyy preferred)
defaultCostCentre String Default cost centre for the employee - value expected is one of the cost centre codes defined for the organisation
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 Male or Female
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)
FORTNIGHTLY_3 F3 Fortnightly (3)
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)
surname String Surname of the employee
title String Job title
address arrow_drop_down JSON Object A JSON object representing the address.

GET /api/v1/employees

Retrieve All Employees

Returns all the active employees of an organisation

GET /api/v1/employees

Response Example

{
  "content": [
	{
	  "address": {
		"addressLine1": "Apartment 212",
		"addressLine2": "123 Main Street",
		"city": "Wellington",
		"country": "New Zealand",
		"postCode": "6011",
		"suburb": "CBD"
	  },
	  "birthDate": "1-Feb-1980",
	  "defaultCostCentre": "Software",
	  "email": "email@email.com",
	  "employeeId": "1111",
	  "firstNames": "Jackie",
	  "fullTimeHoursWeek": 33,
	  "gender": "Female",
	  "links": [
		{
		  "href": "http://secure2.ipayroll.co.nz/api/v1/employees/1111",
		  "rel": "self"
		}
	  ],
	  "organisation": 10000,
	  "paidToDate": "1-Aug-2016",
	  "payFrequency": "Fortnightly",
	  "phone": "021 123 4567",
	  "startDate": "1-May-2014",
	  "surname": "Smith",
	  "title": "Mrs"
	},
   ...
  ],    
  "links": [
   {
	 "rel": "first",
	 "href": "http://secure2.ipayroll.co.nz/api/v1/employees?page=0&size=20"
   },
   {
	 "rel": "self",
	 "href": "http://secure2.ipayroll.co.nz/api/v1/employees"
   },
   {
	 "rel": "next",
	 "href": "http://secure2.ipayroll.co.nz/api/v1/employees?page=1&size=20"
   },
   {
	 "rel": "last",
	 "href": "http://secure2.ipayroll.co.nz/api/v1/employees?page=9&size=20"
   }
  ],
  "page": {
	"size": 20,
	"totalElements": 184,
	"totalPages": 10,
	"number": 0
  }
}

POST /api/v1/employees

Create one or more employees

Create one or more employees in an organisation. This cannot be used to update details of an existing employee.

Parameters
Name Required Type Description
employeeId Yes String Unique ID to identify an employee within an organisation
birthDate No String Date of birth (multiple date formats supported, dd/mm/yyyy preferred)
defaultCostCentre No String Default cost centre for the employee - value expected is one of the cost centre codes defined for the organisation
email No String Email address
firstNames Yes String All first names
surname Yes String Surname of the employee
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 Male or Female
organisation Yes Integer Unique identification of the organisation that the employee belongs to
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)
FORTNIGHTLY_3 F3 Fortnightly (3)
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 No String State in which the employee works - only applicable to Australian organisations (refer address state for possible values)
address arrow_drop_down No JSON Object A JSON object representing the address.

POST /api/v1/employees

Request Body Example

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

Response Example

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

GET /api/v1/employees/{employeeId}

Retrieve an employee's details

Returns an employee.

Parameters
Name Required Type Description
employeeId Yes String Unique ID to identify an employee within an organisation

GET /api/v1/employees/{employeeId}

Response Example

{
  "address": {
	"addressLine1": "Apartment 212",
	"addressLine2": "123 Main Street",
	"city": "Wellington",
	"country": "New Zealand",
	"postCode": "6011",
	"suburb": "CBD"
  },
  "birthDate": "1-Feb-1980",
  "defaultCostCentre": "Software",
  "email": "email@email.com",
  "employeeId": "1111",
  "firstNames": "Jackie",
  "fullTimeHoursWeek": 33,
  "gender": "Female",
  "links": [
	{
	  "href": "http://secure2.ipayroll.co.nz/api/v1/employees/1111",
	  "rel": "self"
	}
  ],
  "organisation": 10000,
  "paidToDate": "1-Aug-2016",
  "payFrequency": "Fortnightly",
  "phone": "021 123 4567",
  "startDate": "1-May-2014",
  "surname": "Smith",
  "title": "Mrs"
}

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

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

Retrieve all of an employee’s pay rates

Returns details of all pay rates associated with an employee.

Parameters
Name Required Type Description
employeeId Yes String Unique ID to identify an employee within an organisation

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

Response Example

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

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

Retrieve a specific payrate for an employee

Returns details of a particular payrate of an employee.

Parameters
Name Required Type Description
employeeId Yes String Unique ID to identify an employee within an organisation
code Yes String Indicates the position of the rate on Personal Details

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

Response Example

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

Timesheets

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

Attributes
Name Type Description
employeeId String Unique ID to identify an employee within an organisation
daysInPeriod Number Number of days an employee has worked within the period of the timsheet. May be omitted, it is only relevant for organisations that have "record day on timesheet" option on
totalHours Number Total hours inside a timesheet
paidFromDate Date The start date of the pay period
paidToDate Date The end date of the pay period
message String A message to be appended to the employee payslip
transactions arrow_drop_down JSON Object List of timesheet transactions for the employee

GET /api/v1/timesheets

Retrieve all of timesheets in the latest payroll

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

GET /api/v1/timesheets

Response Example

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

GET /api/v1/timesheets/{employeeId}/payrolls/{payrollNumber}

Retrieve an employee's timesheet in the given payroll

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

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

GET /api/v1/timesheets/{employeeId}/payrolls/{payrollNumber}

Response Example

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

POST /api/v1/timesheets

Create one or more timesheets

Create one or more timesheets in the current payroll of an organisation. If there's no open payroll found for the organisation, system will open a new payroll provided that all pre-conditiions for opening a payroll are met.

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

POST /api/v1/timesheets

Request Body Example

[
  {    
    "employeeId": "123456",    
    "transactions": [
      {
        "links": [],
        "timesheetTransactionId": 993590,
        "amount": 0,
        "quantity": 1,
        "rate": 0,
        "description": "BANK - Take Home Pay to BANK_NUMBER",
        "costCentre": "",
        "payElement": "BANK"
      },
      {
        "links": [],
        "timesheetTransactionId": 993589,
        "amount": 0,
        "quantity": 1,
        "rate": 0,
        "description": "WT - Withholding Tax to TAX_NUMBER",
        "costCentre": "",
        "payElement": "WT"
      },
      ...
    ],
    "links": [
      {
        "rel": "self",
        "href": "http://secure2.ipayroll.co.nz/api/v1/timesheets/123456"
      },
      {
        "rel": "employee",
        "href": "http://secure2.ipayroll.co.nz/api/v1/employees/123456"
      }
    ]
  }
  ...
]

Response Example

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

GET /api/v1/timesheets/{employeeId}

Retrieve an employee's latest timesheet

Returns the latest timesheet of an employee.

Parameters
Name Required Type Description
employeeId Yes String Unique ID to identify an employee within an organisation

GET /api/v1/timesheets/{employeeId}

Response Example

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

Leave Balances

Attributes
Name Type Description
employeeId String Unique ID to identify an employee within an organisation
entitled Number The number of units given since records started
accrued Number Number of units accrued since last anniversary
taken Number The total number of units taken from the leave balance
balance Number The number of leave units remaining for an employee based on the following equation: Entitled + Accrued - Taken
leaveBalanceType arrow_drop_down JSON Object Leave Balance Type

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

Retrieve all of an employee's leave balances

Returns details of all leave balances associated with an employee.

Parameters
Name Required Type Description
employeeId Yes String Unique ID to identify an employee within an organisation

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

Response Example

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

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

Retrieve a specific leave balance for an employee

Returns details of a particular leave balance of an employee.

Parameters
Name Required Type Description
employeeId Yes String Unique ID to identify an employee within an organisation
name Yes String The name used to identify the leave balance type

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

Response Example

{
  "links": [
    {
      "rel": "self",
      "href": "secure2.ipayroll.co.nz/api/v1/employees/12345/leaves/ACC%20Leave"
    },
    {
      "rel": "employee",
      "href": "secure2.ipayroll.co.nz/api/v1/employees/12345"
    }
  ],
  "employeeId": "12345",
  "entitled": 0,
  "accrued": 0,
  "taken": 8,
  "balance": -8,
  "leaveBalanceType": {
    "leaveType": "ACC First Week",
    "name": "ACC Leave",
    "unit": "hours"
  }
}

Leave Requests

Attributes
Name Type Description
requestId Number Unique ID to identify a request
employeeId String Unique ID to identify an employee within an organisation
hours Number Total number of hours of requested leave
days Number Total number of days of requested leave (applies if a leave balance is stored in days)
leaveFromDate Date First day of leave
leaveToDate Date Last day of leave
reason String Reason for leave
status String Processing status of a leave request. The status can be one of the following:
  • Pending
  • Approved
  • Declined
  • Cancelled
  • Closed
payElement String Description of pay element that is used to process the request in a payroll
leaveBalanceType arrow_drop_down JSON Object Leave Balance Type

GET /api/v1/leaves/requests

Retrieve All Leave Requests

Returns details of all leave requests associated with an organisation.

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

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

GET /api/v1/leaves/requests

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

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

Response Example

{
  "links": [
    {
      "rel": "self",
      "href": "http://secure2.ipayroll.co.nz/api/v1/leaves/requests?status=Approved&leaveBalanceType=Annual%20Leave"
    }
  ],
  "content": [
    {
      "links": [
        {
          "rel": "self",
          "href": "http://secure2.ipayroll.co.nz/api/v1/leaves/requests/255"
        },
        {
          "rel": "employee",
          "href": "http://secure2.ipayroll.co.nz/api/v1/employees/1"
        }
      ],
      "employeeId": "1",
      "requestId": 255,
      "hours": 32,
      "leaveFromDate": "07-Mar-2017",
      "leaveToDate": "10-Mar-2017",
      "reason": "Annual Holidays Break",
      "status": "Approved",
      "payElement": "Annual Leave",
      "leaveBalanceType": {
        "leaveType": "Annual",
        "name": "Annual Leave",
        "unit": "hours"
      }
    }
  ],
  "page": {
    "size": 20,
    "totalElements": 1,
    "totalPages": 1,
    "number": 0
  }
}

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

Retrieve details of a leave request

Returns a leave request.

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": "http://secure2.ipayroll.co.nz/api/v1/leaves/requests/255"
    },
    {
      "rel": "employee",
      "href": "http://secure2.ipayroll.co.nz/api/v1/employees/1"
    }
  ],
  "employeeId": "1",
  "requestId": 255,
  "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"
  }
}

GET /api/v1/leaves/requests/current

Retrieve current leave requests

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

GET /api/v1/leaves/requests/current

Response Example

{
  "links": [
    {
      "rel": "self",
      "href": "http://secure2.ipayroll.co.nz/api/v1/employees/1/leaves/requests/current"
    }
  ],
  "content": [
    {
      "links": [
        {
          "rel": "self",
          "href": "http://secure2.ipayroll.co.nz/api/v1/leaves/requests/254"
        },
        {
          "rel": "employee",
          "href": "http://secure2.ipayroll.co.nz/api/v1/employees/1"
        }
      ],
      "employeeId": "1",
      "requestId": 254,
      "hours": 12,
      "days": 3,
      "leaveFromDate": "09-Mar-2017",
      "leaveToDate": "13-Mar-2017",
      "reason": "Holidays",
      "status": "Pending",
      "payElement": "Alternative Holiday",
      "leaveBalanceType": {
        "leaveType": "Alternative Holiday",
        "name": "Alternative Holiday",
        "unit": "days"
      }
    },
    {
      "links": [
        {
          "rel": "self",
          "href": "http://secure2.ipayroll.co.nz/api/v1/leaves/requests/255"
        },
        {
          "rel": "employee",
          "href": "http://secure2.ipayroll.co.nz/api/v1/employees/1"
        }
      ],
      "employeeId": "2",
      "requestId": 255,
      "hours": 24,
      "leaveFromDate": "01-Feb-2017",
      "leaveToDate": "03-Feb-2017",
      "reason": "Annual Holidays Break",
      "status": "Approved",
      "payElement": "Annual Leave",
      "leaveBalanceType": {
        "leaveType": "Annual",
        "name": "Annual Leave",
        "unit": "hours"
      }
    }
  ],
  "page": {
    "size": 20,
    "totalElements": 2,
    "totalPages": 1,
    "number": 0
  }
}

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

Retrieve all of an employee's leave requests

Returns details of all leave requests associated with an employee.

Parameters
Name Required Type Description
employeeId Yes String Unique ID to identify an employee within an organisation
status No String Processing status of a leave request. The status can be one of the following:
  • Pending
  • Approved
  • Declined
  • Cancelled
  • Closed

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

Response Example

{
  "links": [
    {
      "rel": "self",
      "href": "http://secure2.ipayroll.co.nz/api/v1/employees/1/leaves/requests?status=Pending"
    }
  ],
  "content": [
    {
      "links": [
        {
          "rel": "self",
          "href": "http://secure2.ipayroll.co.nz/api/v1/leaves/requests/254"
        },
        {
          "rel": "employee",
          "href": "http://secure2.ipayroll.co.nz/api/v1/employees/1"
        }
      ],
      "employeeId": "1",
      "requestId": 254,
      "hours": 12,
      "days": 3,
      "leaveFromDate": "09-Mar-2017",
      "leaveToDate": "13-Mar-2017",
      "reason": "Holidays",
      "status": "Pending",
      "payElement": "Alternative Holiday",
      "leaveBalanceType": {
        "leaveType": "Alternative Holiday",
        "name": "Alternative Holiday",
        "unit": "days"
        }
  ],
  "page": {
    "size": 20,
    "totalElements": 1,
    "totalPages": 1,
    "number": 0
  }
}

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

Retrieve current leave requests of an employee

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

Parameters
Name Required Type Description
employeeId Yes String Unique ID to identify an employee within an organisation

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

Response Example

{
  "links": [
    {
      "rel": "self",
      "href": "http://secure2.ipayroll.co.nz/api/v1/employees/1/leaves/requests/current"
    }
  ],
  "content": [
    {
      "links": [
        {
          "rel": "self",
          "href": "http://secure2.ipayroll.co.nz/api/v1/leaves/requests/254"
        },
        {
          "rel": "employee",
          "href": "http://secure2.ipayroll.co.nz/api/v1/employees/1"
        }
      ],
      "employeeId": "1",
      "requestId": 254,
      "hours": 12,
      "days": 3,
      "leaveFromDate": "09-Mar-2017",
      "leaveToDate": "13-Mar-2017",
      "reason": "Holidays",
      "status": "Pending",
      "payElement": "Alternative Holiday",
      "leaveBalanceType": {
        "leaveType": "Alternative Holiday",
        "name": "Alternative Holiday",
        "unit": "days"
      }
    },
    {
      "links": [
        {
          "rel": "self",
          "href": "http://secure2.ipayroll.co.nz/api/v1/leaves/requests/255"
        },
        {
          "rel": "employee",
          "href": "http://secure2.ipayroll.co.nz/api/v1/employees/1"
        }
      ],
      "employeeId": "1",
      "requestId": 255,
      "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"
      }
    }
  ],
  "page": {
    "size": 20,
    "totalElements": 2,
    "totalPages": 1,
    "number": 0
  }
}

Payslips

Attributes
Name Type Description
totalPayments Number Gross payment for the period
overpayment Number Indicates recovery of money in this payroll (might have been caused by overpayment in a previous payroll)
taxCredit Number Tax credited for donations made
yearToDateTotals Map A map containing year-to-date totals as value (Number) for various pay elements as key (String)
nettPay Number Nett payment
payslipMessage String Organisation specific payslip message
abn String The Australia Business Number (only applicable to Australian organisations). This field would not be there for non-Australian organisations.
payroll arrow_drop_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/payslips

Retrieve all payslips in the latest payroll

Returns all payslips generated in the latest pay run.

GET /api/v1/payslips

Response Example

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

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

Retrieve a single employee's payslip in the latest payroll

Returns payslip of the specified employee.

Parameters
Name Required Type Description
employeeId Yes String Unique ID to identify an employee within an organisation

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

Response Example

 {
  "links": [
    {
      "rel": "self",
      "href": "http://secure2.ipayroll.co.nz/api/v1/payslips/employees/101"
    },
    {
      "rel": "employee",
      "href": "http://secure2.ipayroll.co.nz/api/v1/employees/101"
    }
  ],
  "totalPayments": -254.35,
  "deductions": [
    {
      "amount": 30.24,
      "quantity": 1,
      "description": "PAYE (Tax Code M) to 26-109-719"
    }
  ],
  "otherBenefits": [],
  "yearToDateTotals": {
    "Taxable Earnings": 2272.49,
    "PAYE": 662.47
  },
  "leaveBalances": [
    {
      "balanceName": "Annual Leave",
      "hours": 229,
      "days": 28.5
    }
  ],
  "timesheet": {
    "links": [
      {
        "rel": "self",
        "href": "http://secure2.ipayroll.co.nz/api/v1/timesheets/101/payrolls/0040"
      }
    ],
    "employeeId": "101",
    "totalHours": -9.16,
    "transactions": [
      {
        "timesheetTransactionId": 1130873,
        "amount": -254.35,
        "quantity": -9.16,
        "rate": 27.7675,
        "description": "SICK - Sick Leave (01-Nov-2016 to 02-Nov-2016)",
        "costCentre": "new",
        "leaveFrom": "01-Nov-2016",
        "leaveTo": "02-Nov-2016",
        "leaveDays": "-0.9200",
        "payElement": "SICK"
      }
    ],
    "paidToDate": "12-Nov-2016",
    "paidFromDate": "04-Aug-2015"
  },
  "payments": [
    {
      "description": "Sick Leave (01-Nov-2016 to 02-Nov-2016) -0.92 days @ $27.7675",
      "quantity": -9.16,
      "amount": -254.35,
      "notes": ""
    }
  ],  
  "nettPay": 0,
  "payroll": {
    "payrollNumber": "0040",
    "payDate": "25-Nov-2016"
  },
  "payslipMessage": "Best Wishes!"
}

GET /api/v1/payslips/{payrollNumber}

Retrieve all payslips in a specific payroll

Returns all payslips associated with the specified payroll.

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

GET /api/v1/payslips/{payrollNumber}

Response Example

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

GET /api/v1/payslips/{payrollNumber}/employees/{employeeId}

Retrieve specific employee's payslip in a specific payroll

Returns specified employee's payslip in the specified payroll.

Parameters
Name Required Type Description
payrollNumber Yes String Unique identifier of the payroll
employeeId Yes String Unique identifier of the employee

GET /api/v1/payslips/{payrollNumber}/employees/{employeeId}

Response Example

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

Pay Element

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

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

Returns all the pay elements of an organisation.

GET /api/v1/payelements

Response Example

{
  "links": [
    {
      "rel": "self",
      "href": "http://secure2.ipayroll.co.nz/api/v1/payelements?size=100&page=0"
    }
  ],
  "content": [
    {
      "links": [
        {
          "rel": "self",
          "href": "http://secure2.ipayroll.co.nz/api/v1/payelements/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/{code}

Retrieve A Pay Element

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

Parameters
Name Required Type Description
code Yes String The name of the pay element.

GET /api/v1/payelements/{code}

Response Example

{
  "links": [
    {
      "rel": "self",
      "href": "http://secure2.ipayroll.co.nz/api/v1/payelements/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
}