Introduction
This site explains how to use the SimplePay API in order to send and receive data. The SimplePay API is an HTTP RESTful service. It is recommended that you familiarise yourself with RESTful APIs before browsing this site.
Please contact us at api@simplepay.ie if you have any queries or issues related to API functionality.
SimplePay Terminology
Before using the API, please take note of the following terminology:
Resource | Details |
---|---|
client | A company |
wave | A pay frequency, i.e. the frequency with which employees are paid |
pay_point | Means of grouping employees, e.g. by department |
calculation | A payslip item. System-defined calculations are specified by their name, e.g. basic_salary. Custom calculations are specified using a numeric ID e.g. 12345 |
Authentication
Authentication involves two steps. Firstly, API users should generate a key to be used with API requests. Then this key should be added to all API requests as a header in a specific format. The process is as follows:
- Log into your SimplePay account.
- Go to the following URL:
https://www.simplepay.ie/external_users
- In the 'API Users' section, click on the 'Add' button to create a new API user and an associated authorization key for use with the API.
- Use this key with all authentication requests as a header in the following format:
Authorization: the_api_key_from_simplepay
Depending on which tool or programming environment you use, headers are added to HTTP requests in different ways.
Example Request with Correct Authentication
Request
# With the command line you can pass the correct header with each request
curl -i -X GET https://api.payroll.simplepay.cloud/v1/clients/ -H 'Content-Type: application/json' -H 'Authorization: the_api_key_from_simplepay'
You can test that you are able to access the API using this key with the following request for a list of clients, using the command line tool called cURL.
Make sure to replace the_api_key_from_simplepay
with your API key.
Response
[
{
"client":{...},
},{
"client":{...},
}
]
When you run this command from your command line you, should see a response body that looks something like this snippet ->
If you can successfully retrieve a list of clients, you have authenticated your API call successfully.
Available Resources
The SimplePay API currently allows you to interact with clients and employees on SimplePay.
Bulk Inputs
- Update Employees and Payslips
Client Information
- Get a List of All Clients
Employee Profiles
- Get a List of All Employees for a Client
- Get a Specific Employee
- Create an Employee
- Employee Attributes
- Update an Employee
- Delete an Employee
Payment Frequencies
- Get a List of All Payment Frequencies (Waves) for a Client
- Create a Pay Frequency
Pay Points
- Get a List of All Pay Points for a Client
Payslips
- Get a List of Payslips for an Employee
- Get a Specific Payslip for an Employee in JSON Format
- Get a Specific Payslip for an Employee in PDF Format
Pay Runs
- Get a List of Pay Runs for a Client
- Get a List of Payslips in a Pay Run
- Get the Accounting Journal Information for a Pay Run
Reports
- Transaction History Report
- Variance Report
- Comparison Leave Report
- Leave Liabilities Report (BETA)
- Tracked Balances Report (BETA)
- Large Reports
Calculations
- Get a List of Calculations for Either Client, Employee or Payslip
- Get a Specific Calculation
- Create/Update Calculations on Either an Employee or Payslip
- Delete a Specific Calculation
Inherited Calculations
- Get a List of Inherited Calculations for Either a Client or Employee
- Get a Specific Inherited Calculation
- Inherited Calculation Attributes
- Update Inherited Calculations for Either an Employee or Client
Calculations and Accounts
- Get a List of All Available System Items, Custom Items and Accounts
Service Periods
- Get a List of Service Periods for an Employee
- Update Service Period Termination Information
- Reinstate an Employee
- Undo Termination of an Employee
Leave
- Get the Leave Balance for an Employee
- Get a List of Available Leave Types
- Get a List of All Leave Days for an Employee in JSON Format
- Create a New Leave Day
- Create Multiple New Leave Days
- Update an Existing Leave Day
- Delete an Existing Leave Day
Template Profile Mappings
- Get a List of Profile Mappings
- Create a Profile Mapping
- Delete a Profile Mapping
- Update a Profile Mapping
Custom Employee Fields
- Get a List of Custom Employee Fields
** Additional functionality is being assessed and developed incrementally based on user requirements
Bulk Inputs
Update Employees and Payslips
Request
Request
https://api.payroll.simplepay.cloud/v1/clients/:client_id/bulk_input
This is an HTTP POST request to this URL ->
Where the parameter :client_id
is the ID of a specific client obtained from the call to get a list of clients.
Request Body
Request Body
{ "entities": [
{
"id": "243",
"payslip_id": "4257689",
"attributes": {
"first_name": "Juliet",
"calc.basic_salary.fixed_amount": "4300",
"calc.commission.commission_input": "160",
"calc.extra_pay.amount": "100",
"calc.annual_bonus.amount": "220",
"calc.76523.amount": "122"
}
},{
"id": "243",
"payslip_id": "12765",
"attributes": {
"calc.commission.commission_input": "120"
}
},{
"id": "9003",
"payslip_id": "1235",
"attributes": {
"calc.basic_salary.fixed_amount": "3450",
"calc.commission.commission_input": "400"
}
},{
"id": "21103",
"payslip_date": "2020-12-31",
"attributes": {
"calc.annual_bonus.amount": "220",
}
},{
"id": "8792",
"attributes": {
"first_name": "Mitchell",
"calc.basic_salary.hourly_paid": "true",
"calc.basic_salary.normal_rate_input": "20"
}
}
] }
The request body should be a JSON object. It contains a list of entity hashes. Each entity hash refers to a single employee and contains the following keys
Name | Description |
---|---|
id | The employee ID |
payslip_id | A payslip identifier. This is only relevant when payslip specific inputs are included in the attributes. |
payslip_date | A payslip identifier that can be used instead of "payslip_id". The regular payslip for the pay period that ends on "payslip_date" will be updated. Once-off payslips cannot be specified by date. This is only relevant when payslip specific inputs are included in the attributes. |
attributes | A hash containing the inputs to be added or updated for the employee. Valid calculation attribute IDs and inputs can be found using the “Get a list of Calculations” request. These calculation IDs must be prefixed with "calc." to indicate that they are calculation attributes e.g. "calc.annual_bonus.amount" or "calc.76523.amount" for a custom calculation. |
Note: Finalised payslips cannot be updated.
An example is shown ->
Response
Response
[
{
"id": "243",
"payslip_id": "4257689",
"success": "true",
"message": "Information for Juliet Bordet was saved successfully"
},{
"id": "243",
"payslip_id": "12765",
"success": "true",
"message": "Information for Juliet Bordet was saved successfully"
},{
"id": "9003",
"payslip_id": "1235",
"success": "false",
"message": "Information for Hannes Hvilken failed to save"
"errors": {
"calc.commission.commission_input": “Commission is not enabled”
}
},{
"id": "21103",
"payslip_id": "20762",
"payslip_date": "2020-12-31",
"success": "true",
"message": "Information for Henry Browning was saved successfully"
},{
"id": "8792",
"success": "true",
"message": "Information for Mitchell Sykler was saved successfully”
}
]
If executed correctly the response body is a JSON object with details of which entities were saved correctly. The response contains a list of entity hashes that correspond to those in the request. The entity hashes contain the employee id, a payslip identifier if necessary, and a success or failure message and boolean. If any of the attributes failed to save, the message will indicate failure and an errors hash will also be included. The errors hash’s key are the attributes that did not save and the values are the error messages.
An example is shown ->
Clients
Get a List of Clients
Request
Request
https://api.payroll.simplepay.cloud/v1/clients/
This is an HTTP GET request to URL ->
Response
Response
[
{"client":{
"id":36818,
"name":"API QA Company",
"physical_address":{
"unit_no": "10878",
"complex":"Bridge Towers",
"st_name": "5 North Bridge Road",
"postal_code": "149281"
},
...
}}
]
If executed correctly the response body is a JSON array with a list of clients, which should be similar to this snippet ->
Employees
Get a List of Employees
Request
Request
https://api.payroll.simplepay.cloud/v1/clients/:client_id/employees
This is an HTTP GET request to URL ->
Where the parameter :client_id
is the ID of a specific client obtained from the call to get a list of clients.
You can use the include
query parameter to specify a comma-separated list of entities that you want included.
For example, appending ?include=service_periods,recent_payslips
to the URL will include the service periods and recent 12 payslips of the employee in the response.
Allowed entities: service_periods (will return all service periods), recent_payslips (will return last 12 payslips), and recent_payslips_with_data (will return last 12 payslips with their payslip items).
Note 1: When recent_payslips_with_data
is requested, api may respond with 202
status with an error message when there are payslips which require calculations.
Please try after a while to get the prepared result.
Note 2: Payslips whose calculations are still in progress will have the dirty
attribute set to true
, and nett_pay
attribute unavailable in the response.
Please try again later to obtain nett pay
.
Response
Response
[
{"employee":{
"first_name": "Kenneth",
"last_name": "Parker",
"birthdate": "1985-02-06",
"appointment_date": "2010-02-06",
"wave_id": 2,
"payment_method": "cash",
"physical_address": {
"unit_no": "22",
"st_name": "North Bridge Rd",
"postal_code": "149281"
},
...
}}
]
If executed correctly the response body is a JSON array with a list of employees, which should be similar to this snippet ->
Request
https://api.payroll.simplepay.cloud/v1/clients/:client_id/employees?include=service_periods
Response
[
{"employee": {
"first_name": "Kenneth",
"last_name": "Parker",
"birthdate": "1985-02-06",
"appointment_date": "2010-02-06",
...
"service_periods": [
{"service_period": {
"id": 1110,
"employee_id": 12345,
"start_date": "2016-08-01",
"end_date": "2019-10-18",
"negative": false,
"created_at": "2016-08-02T12:57:20.313+02:00",
"updated_at": "2019-09-11T09:56:16.415+02:00",
"attribs": null,
"termination_code": 2
}},
...
]
}}
]
Request
https://api.payroll.simplepay.cloud/v1/clients/:client_id/employees?include=recent_payslips
Response
[
{"employee": {
"first_name": "Kenneth",
"last_name": "Parker",
"birthdate": "1985-02-06",
...
"recent_payslips": [
{"payslip": {
"id": 43,
"date": "2017-09-27",
"special": false,
"finalised": true,
"ss_released": true,
"payment_run_id": 87908,
"dirty": false,
"nett_pay": 3480.02
}},
...
]
}}
]
Request
https://api.payroll.simplepay.cloud/v1/clients/:client_id/employees?include=recent_payslips_with_data
Response
[
{"employee": {
"first_name": "Kenneth",
"last_name": "Parker",
"birthdate": "1985-02-06",
...
"recent_payslips_with_data": [
{"payslip": {
"id": 24017537,
"date": "2017-09-27",
"special": false,
"finalised": true,
"ss_released": true,
"payment_run_id": nil,
"dirty": false,
"nett_pay": 3480.02,
"data": {
"income": [["Extra Pay", "2000.0"], ["Total", "2000.0"]],
"deduction": [["UIF - Employee", "20.0"], ["Tax (PAYE)", "360.0"], ["Total", "380.0"]],
"grand_total": [["Nett Pay", "1620.0"]],
"sideline": [["Employer contribution", [["SDL - Employer", "20.0"], ["UIF - Employer", "20.0"], ["Total", "40.0"]]]],
"leave_payments": {},
}
}},
...
]
}}
]
Get a Specific Employee
Request
Request
https://api.payroll.simplepay.cloud/v1/employees/:id
This is an HTTP GET request to URL ->
Where the parameter :id
is the ID of a specific employee obtained from the call to get a list of employees.
Response
Response
{
"employee":{
"first_name": "Kenneth",
"last_name": "Parker",
"birthdate": "1985-02-06",
"appointment_date": "2010-02-06",
"wave_id": 2,
"payment_method": "cash",
"physical_address": {
"unit_no": "22",
"st_name": "North Bridge Rd",
"postal_code": "149281"
},
"custom_fields":
{
"7651": "4",
"53621": "011 568 0721"
},
...
}
}
If executed correctly the response body is a JSON array with a list of employees, which should be similar to this snippet ->
Create an Employee
Request
Request
https://api.payroll.simplepay.cloud/v1/clients/:client_id/employees
This is an HTTP POST request to URL ->
Where the parameter :client_id
is the ID of a specific client obtained from the call to get a list of clients.
Request Body
Request Body
{ "employee": {
"wave_id": 1350675273,
"first_name": "Alice",
"last_name": "Williams"
...
}}
The request body should be a JSON object containing the details of the employee to be saved. An abbreviated request body sample is shown to the right ->
There are several required attributes for creating an employee, as well as certain optional ones. The applicability of the various attributes will vary depending on the individual employee. Please see the examples to the right of the Employee Attributes tables below.
Response
Response
{
"message": "Employee has been created/updated",
"id": 22304,
"number: "0012"
}
If executed correctly the response body is a JSON object with details of the transaction and the ID of the created employee, and should be similar to this snippet ->
Employee Attributes
Request body - Employee with bank account and address
{ "employee": {
"wave_id": 1350676447,
"first_name": "Juliet",
"last_name": "Dean",
"birthdate": "1985-02-06",
"appointment_date": "2010-02-06",
"ppsn": "8765432A",
"number": "00002",
"payment_method": "eft_manual",
"bank_account": {
"account_number": "123456778",
"branch_code": "ABCDIE21"
},
"physical_address":
{
"line_1": "22 Heron Road",
"line_2": "Terenure",
"line_3": "Dublin"
},
"custom_fields":
{
"70922": "Julie",
"53621": "011 568 0721"
}
}}
The following attributes may be required for the creation of an employee. Certain attributes are always required while others are only conditionally required based on the value of another attribute. There are also certain optional attributes, which can be ignored for creation and added during an update if required.
Parent Attributes
Attribute | Details | Type | Applicability |
---|---|---|---|
wave_id | The ID of the wave to which the employee belongs | Integer | Required |
first_name | Employee first name | String | Required |
last_name | Employee last name | String | Required |
birthdate | Employee date of birth in the format YYYY-MM-DD | Date String | Optional |
appointment_date | The date of appointment in the format YYYY-MM-DD | Date String | Required |
ppsn | Employee's PPS number | String | Optional |
prsi_class | Employee's PRSI class. The following are valid values:
|
String | Optional, will default to "a" if left blank |
prsi_exempt | Indicates whether the employee is PRSI exempt | Boolean | Optional |
director | Indicates whether the employee is the director of the company | Boolean | Optional |
The employee's email address | String | Optional. This can be used for self-service. | |
payment_method | The method with which the employee will be paid. The following are valid values:
|
String | Required |
number | Employee identifying number for payroll purposes. | String | Required if client employee_number_mode is "EMPLOYEE_NUMBER_MANUAL" - must be set via UI |
job_title | Employee's job title | String | Optional |
bank_account_attributes | Employee bank details object. Please see the Child Attributes table below | Hash | Optional |
physical_address | Employee address object. Please see the Child Attributes table below | Hash | Optional |
custom_fields | Custom employee fields object. Please see the Child Attributes table below | Hash | Optional |
Child Attributes
Parent | Attribute | Details | Type | Applicability |
---|---|---|---|---|
bank_account_attributes | account_number | The employee's bank account number (IBAN) | String | Optional |
branch_code | Employee bank branch code (BIC) | String | Optional | |
physical_address | line_1 | First line of the address | String | Optional |
line_2 | Second line of the address | String | Optional | |
line_3 | Third line of the address | String | Optional | |
custom_fields | [Custom Field ID] | Custom employee fields are identified using numerical ID keys. Values for dropdown options are also returned as IDs. There is currently no endpoint to retrieve custom fields so, for now, these can both be found by inspecting the HTML of the input element on an employee's Basic Info page. |
Specified in field definition | Specified in field definition |
Update an Employee
Request
Request
https://api.payroll.simplepay.cloud/v1/employees/:id
This is an HTTP PATCH request to URL ->
Where the parameter :id
is the SimplePay system ID of an employee.
Request Body
Request body
{ "employee": {
"first_name": "Alice",
"last_name": "Williams",
"birthdate": "1985-02-06",
}}
The request body should be a JSON object containing the details of the employee to be changed. An example is shown ->
You only need to send those attributes which need to be changed for an employee.
Response
Response
{
"message": "Employee has been created/updated",
"id": 1,
"number": "0001"
}
If executed correctly the response body is a JSON object with details of the transaction, and should be similar to this snippet ->
Delete an Employee
Request
Request
https://api.payroll.simplepay.cloud/v1/employees/:id
This is an HTTP DELETE request to URL ->
Where the parameter :id
is the SimplePay system ID of an employee.
Response
Response
{
"message": "Employee with number 1100 has been deleted."
}
If executed correctly the response body is a JSON object with details of the transaction, and should be similar to this snippet ->
Payment Frequencies
Get a List of Payment Frequencies
Request
Request
https://api.payroll.simplepay.cloud/v1/clients/:client_id/waves
This is an HTTP GET request to URL ->
Where the parameter :client_id
is the ID of a specific client obtained from the call to get a list of clients.
Including the parameter format=simplified
will result in simplified descriptions of the payment frequencies that use a text frequency
value instead of describing the frequency using length_months
and length_weeks
.
Note that, for most frequency types, first_end_date
as provided by this request is normalised to be a date in January 2008 or 2009. The period_offset
can be used to determine the end date specified during the pay frequency creation. The period_offset
is the number of pay periods (e.g. months) between the normalised first_end_date
and the date provided during creation.
If it applies to the frequency, interim_first_end_date
is also a normalised date.
Response
Response
[
{"wave":{
"id":1350761618,
"length_months":1,
"length_weeks":0,
"first_end_date":"2008-01-31",
"first_period_offset":139,
"notification_days_before":null,
"finalisation_days_before":null,
"client_id":84407,
"interim_first_end_date":null,
"created_at":"2019-08-22T16:52:08.336+02:00",
"updated_at":"2019-08-22T16:52:08.336+02:00",
"payslip_payment_day":null,
"custom_name":null,
"pay_dates":{
"enabled":false
},
"name": "Monthly, ending on the 31st"
}}
...
]
Response - Simplified Format
[
{"wave":{
"id":1350761618,
"first_end_date":"2008-01-31",
"client_id":84407,
"interim_first_end_date":null,
"created_at":"2019-08-22T16:52:08.336+02:00",
"updated_at":"2019-08-22T16:52:08.336+02:00",
"custom_name":null,
"pay_dates":{
"enabled":false},
"frequency":"monthly",
"name": "Monthly, ending on the 31st"
}},
...
]
If executed correctly the response body is a JSON array with a list of payment frequencies (called 'waves' on the SimplePay system), which should be similar to this snippet ->
Create a Pay Frequency
Request
Request
https://api.payroll.simplepay.cloud/v1/clients/:client_id/waves
This is an HTTP POST request to URL ->
Where the parameter :client_id
is the ID of a specific client obtained from the call to get a list of clients.
Request Body
Request Body
{
"frequency": "monthly",
"last_day_of_month": "31",
"first_end_date": "2019-05-31"
}
The request body should be a JSON object containing the details of the pay frequency to be saved. A request body sample is shown to the right ->
There are several required attributes for creating a pay frequency, as well as certain optional ones. The applicability of the various attributes will vary depending on the client and the type of frequency. Please see the Pay Frequency Attributes table below for details.
Pay Frequency Attributes
Attribute | Details | Type | Applicability |
---|---|---|---|
frequency | The following are valid values:
|
String | Required |
last_day_of_month | The last day of the month. A number between 1 and 31. | Integer | Optional unless frequency is "monthly" |
first_end_date | The end date of the first period in the format YYYY-MM-DD. Note that first_end_date is not stored in the database exactly as provided here. See Get a list of Payment Frequencies for details. |
Date String | Required |
custom_name | A custom name for the pay frequency | String | Optional. Setting this will throw an error unless the feature is enabled for the client. |
Response
Response
{
"message": "Wave has been created/updated",
"id": 234
}
If executed correctly the response body is a JSON object with details of the transaction and the ID of the created wave (pay frequency), and should be similar to this snippet ->
Pay Points
Get a List of Pay Points
Request
Request
https://api.payroll.simplepay.cloud/v1/clients/:client_id/pay_points
This is an HTTP GET request to URL ->
Where the parameter :client_id
is the ID of a specific client obtained from the call to get a list of clients.
Response
Response
[
{"pay_point":{
"id":1,
"name":"Pay Point 1",
"created_at":"2017-08-10T16:01:01.471+02:00",
"updated_at":"2017-08-10T16:01:01.471+02:00",
"client_id":2,
"physical_address":{
"unit_no": "107",
"st_name": "Rivonia Rd.",
"postal_code": "2196"
},
}}
...
]
If executed correctly the response body is a JSON array with a list of pay points, which should be similar to this snippet ->
Payslips
Get a List of Payslips for an Employee
Request
Request
https://api.payroll.simplepay.cloud/v1/employees/:employee_id/payslips
This is an HTTP GET request to URL ->
Where the parameter :client_id
is the ID of a specific client, obtained from the call to get a list of clients, and the parameter :employee_id
is the ID of a specific employee, obtained from the call to get a list of employees.
Note: Payslips whose calculations are still in progress will have the dirty
attribute set to true
, and nett_pay
attribute unavailable in the response.
Please try again later to obtain nett pay
.
Response
Response
[
{
"payslip": {
"id":43,
"date":"2017-09-27",
"special":false,
"finalised":true,
"dirty":false,
"nett_pay":3480.02,
"ss_released": true,
"payment_run_id": 87908
}
},
{
"payslip": {
"id":44,
"date":"2017-10-04",
"special":false,
"finalised":false,
"dirty":true,
"ss_released": false,
"payment_run_id": 89879
}
}
]
If executed correctly the response body is a JSON array with a list of payslips, which should be similar to this snippet ->
Get a Specific Payslip for an Employee
Request
Request
https://api.payroll.simplepay.cloud/v1/payslips/:payslip_id
This is an HTTP GET request to URL ->
Where the parameter :payslip_id
is the ID of a particular payslip, obtained from the above call to list the payslips.
Response
Response
{"payslip":
{"income":[
["basic_salary","10000.0"],
["total","10000.0"]
],
"deduction":[
["sinda","12.0"],
["cpf_employee","450.0"],
["total","462.0"]
],
"grand_total":[
["nett_pay","9538.0"]
],
"sideline":[
["employer_contribution",
[["cpf_employer","540.0"],
["sdl_employer","11.25"],
["total","551.25"]
]
]
],
"leave":{
"annual_leave":{
"accrual":"1.1667",
"taken":0,
"balance":"3.5001"
},
"sick_leave":{
"accrual":0,
"taken":0,
"balance":"14.0"
},
"id":1701992
}
}
}
If executed correctly the response body is a JSON object containing the relevant information for the payslip, similar to this snippet ->
The contents of the first hash after the ID correspond to the various items on the particular payslip. This information will therefore depend on how each employee's payslip is set up, i.e. what income, deduction, allowance etc items they have:
- System items will each be contained an array made up of the item name and the amount, e.g. an employee's salary would be returned as ["basic_salary", 123456.0]
- Custom items are also returned as arrays, but with the item's ID in place of the item name, e.g. [34567, 65422.0]
The contents of the second hash relate to the employee's leave types and balances.
Requesting a PDF Payslip
Request
https://api.payroll.simplepay.cloud/v1/payslips/:payslip_id.pdf
This is an HTTP GET request to URL ->
Response
If successful, this will return the binary data for the PDF version of the payslip. Note: you should ideally send the Content-Type: application/pdf
header as part of the request.
Pay Runs
Get a List of Pay Runs
Request
This is an HTTP GET request to URL ->
Where the parameter :client_id is the ID of a specific client obtained from the call to get a list of clients.
Request
https://api.payroll.simplepay.cloud/v1/clients/:client_id/payment_runs
Response
If executed correctly the response body is a JSON array with a list of pay runs, which should be similar to this snippet ->
Response
[
{
"payment_run": {
"id": 2890831,
"wave_id": 1350864197,
"period_offset": 171,
"period_end_date": "2022-04-30",
"total": 22809.55,
"created_at": "2022-05-27T09:45:59.592+02:00",
"updated_at": "2022-05-27T09:45:59.592+02:00",
"special": false
}
},
{
"payment_run": {
"id": 2890811,
"wave_id": 1350864197,
"period_offset": 170,
"period_end_date": "2022-03-31",
"total": 22966.38,
"created_at": "2022-05-27T09:45:05.843+02:00",
"updated_at": "2022-05-27T09:45:05.843+02:00",
"special": false
}
}
]
Get a List of Payslips in a Pay Run
Request
This is an HTTP GET request to URL ->
Where the parameter :payment_run_id is the ID of a specific pay run obtained from the call to get a list of pay runs in a client.
Request
https://api.payroll.simplepay.cloud/v1/payment_runs/:payment_run_id/payslips
Response
If executed correctly the response body is a JSON array with a list of payslips in the pay run, which should be similar to this snippet ->
- Please see Get a Specific Payslip for an Employee for more information.
Response
[
{
"payslip": {
"id": 30796888,
"date": "2023-04-30",
"special": false,
"finalised": true,
"ss_released": false,
"payment_run_id": 2890831,
"dirty": false,
"nett_pay": 9536.25,
"data": {
"income": [
[
"Basic Salary",
"10000.0"
],
[
"Total",
"10000.0"
]
],
"deduction": [
[
"UIF - Employee",
"100.0"
],
[
"Tax (PAYE)",
"363.75"
],
[
"Total",
"463.75"
]
],
"grand_total": [
[
"Nett Pay",
"9536.25"
]
],
"sideline": [
[
"Employer contribution",
[
[
"SDL - Employer",
"100.0"
],
[
"UIF - Employer",
"100.0"
],
[
"Total",
"200.0"
]
]
]
],
"leave_payments": {}
}
}
}
...
]
Get the Accounting Journal Info of a Pay Run
Request
This is an HTTP GET request to URL ->
Where the parameter :payment_run_id is the ID of a specific pay run obtained from the call to get a list of pay runs in a client.
Request
https://api.payroll.simplepay.cloud/v1/payment_runs/:payment_run_id/accounting
Response
If executed correctly the response body is a JSON array with the accounting journal info of the pay run, which should be similar to this snippet -> If Accounting Splits are not set up, they will not be included in the response. See the second example response.
Response - With Accounting Splits
[
{
"accounting_splits": [
{
"id": "9940",
"name": "Split A"
},
{
"id": "9941",
"name": "Split B"
}
],
"debit": [
{
"category": "salary_expense",
"line_item": "basic_salary",
"label": "Basic Salary",
"amount": {
"9940": 10000,
"9941": 20000
}
},
{
"category": "expense",
"line_item": "sdl_employer",
"label": "SDL - Employer",
"amount": {
"9940": 100,
"9941": 200
}
},
{
"category": "expense",
"line_item": "uif_employer",
"label": "UIF - Employer",
"amount": {
"9940": 100,
"9941": 200
}
}
],
"credit": [
{
"category": "liability",
"line_item": "tax",
"label": "Tax (PAYE)",
"amount": {
"9940": 363.75,
"9941": 727.5
}
},
{
"category": "liability",
"line_item": "nett_pay",
"label": "Nett Pay",
"amount": {
"9940": 9536.25,
"9941": 19072.5
}
},
{
"category": "liability",
"line_item": "uif_total",
"label": "UIF Total",
"amount": {
"9940": 200,
"9941": 400
}
},
{
"category": "liability",
"line_item": "sdl_employer",
"label": "SDL - Employer",
"amount": {
"9940": 100,
"9941": 200
}
}
]
}
...
]
Response - Without Accounting Splits being set up
[
{
"accounting_splits": [],
"debit": [
{
"category": "salary_expense",
"line_item": "basic_salary",
"label": "Basic Salary",
"amount": {
"": 30000
}
},
{
"category": "expense",
"line_item": "sdl_employer",
"label": "SDL - Employer",
"amount": {
"": 300
}
},
{
"category": "expense",
"line_item": "uif_employer",
"label": "UIF - Employer",
"amount": {
"": 300
}
}
],
"credit": [
{
"category": "liability",
"line_item": "tax",
"label": "Tax (PAYE)",
"amount": {
"": 1091.25
}
},
{
"category": "liability",
"line_item": "nett_pay",
"label": "Nett Pay",
"amount": {
"": 28608.75
}
},
{
"category": "liability",
"line_item": "uif_total",
"label": "UIF Total",
"amount": {
"": 600
}
},
{
"category": "liability",
"line_item": "sdl_employer",
"label": "SDL - Employer",
"amount": {
"": 300
}
}
]
}
...
]
Reports
General
Filtering on Employee IDs and Wave IDs
- When retrieving any of the reports, we will filter employees by what you give us (this includes wave_ids as an additional filter)
- However, if you leave employee_ids out of the request we won't apply any filters.
Humanizing the Data
- In the future we plan to offer an option that will allow you to choose whether you'd like your response columns and data humanized or not.
- For now, you can leave it out of your request if you prefer.
Backwards Compatibility
The following section has been updated to use our advised method of retrieving reports through POST requests, however we will continue to support the GET requests as described previously.
Transaction History Report
Request
https://api.payroll.simplepay.cloud/v1/clients/:client_id/reports/transaction_history
Request
This is an HTTP POST request to URL ->
Where the parameter :client_id
is the ID of a specific client, obtained from the call to get a list of clients.
transaction_history
is the ID for this report
Request Body
{
"start_date": "2017-12-01",
"end_date": "2017-12-31",
"wave_ids": [1,2],
"employee_ids": [6,2],
"account_names": ["basic_salary","tax"],
"humanize": true
}
Request Body
The request body should be a JSON object. It contains the fields that will determine which information is included in the report.
Name | Type | Examples |
---|---|---|
start_date | String | "2016-11-23" |
end_date | String | "2017-02-13" |
wave_ids | Array | null or [2, 3] |
employee_ids | Array | null or [6, 7, 9] |
account_names | Array | ["basic_salary", "medical_aid_self", "pension_fund_employee", "tax"] |
custom_fields | Array | null or ["first_name", "last_name", "pay_point_id", "appointment_date"] |
humanize | Boolean | null, true, false |
Account Names
Unfortunately for now, in order to retrieve the account names, you'll have to generate a report on the front end with the accounts selected and inspect the request URL.
Custom Fields
As with Account Names, in order to retrieve the available custom fields, you'll have to generate a report on the front end with the custom fields (Additional Fields) selected and then inspect the request URL. In addition, "first_name" and "last_name" have been made available as custom fields.
Response
[
{"employee":"6","Date":"2017-12-31","Basic Salary":"R 15,000.00","Tax":"R 1,473.75"},
{"employee":"2","Date":"2017-12-31","Basic Salary":"R 12,000.00","Tax":"R 1,023.75"}
]
Response
If executed correctly the response body is a JSON object containing the relevant information for the report, similar to this snippet ->
The response comes back in the form of an array of hashes, each hash containing the data relevant to a certain employee, identified by the employee number as given in the request.
Variance Report
Request
https://api.payroll.simplepay.cloud/v1/clients/:client_id/reports/variance
Request
This is an HTTP POST request to URL ->
Where the parameter :client_id
is the ID of a specific client, obtained from the call to get a list of clients.
variance
is the ID for this report
Request Body
{
"wave_id": 1,
"period_offset": 119,
"employee_ids": [6],
"humanize": true
}
Request Body
The request body should be a JSON object. It contains the fields that will determine which information is included in the report.
Name | Type | Examples |
---|---|---|
wave_id | Number | 131 |
employee_ids | Array | null or [6, 7, 9] |
period_offset | Number | 112 |
humanize | Boolean | null, true, false |
Period Offset ID
In order to get this ID, please generate a report on the front end and check for the IDs you need in the request URL.
Response
[
{"employee":"6","Type":"Benefit","Transaction":{"taxable_income":1,"retirement_funding_income":0,"non_retirement_funding_income":1,"uif_income":1,"sdl_income":1,"type":"benefit","cost_to_company_account":"pension_fund_employer","code":3817,"name":"pension_fund_benefit","formula":{},"frequency":"regular","calculation_output":true},"Previous":"R 300.00","Selected":"R 300.00","Variance":"R 0.00"},
{"employee":"6","Type":"Deduction","Transaction":{"type":"deduction","caption":"Pension Fund - Employee","code":4001,"accounting":{"group":"exclude"},"name":"pension_fund_employee","formula":{},"frequency":"regular","calculation_output":true},"Previous":"R 500.00","Selected":"R 500.00","Variance":"R 0.00"},
{"employee":"6","Type":"Deduction","Transaction":{"name":"tax","caption":"Tax","description":"Tax","type":"deduction","trace":true},"Previous":"R 1,473.75","Selected":"R 1,473.75","Variance":"R 0.00"},
{"employee":"6","Type":"Deduction","Transaction":{"name":"uif_self","caption":"UIF - Employee","description":"UIF - Employee","type":"deduction","accounting":{"group":"exclude"}},"Previous":"R 148.72","Selected":"R 148.72","Variance":"R 0.00"},
{"employee":"6","Type":"Employer contribution","Transaction":{"type":"employer_contribution","caption":"Pension Fund - Employer","taxable_income":0,"code":4472,"name":"pension_fund_employer","formula":{},"frequency":"regular","calculation_output":true},"Previous":"R 300.00","Selected":"R 300.00","Variance":"R 0.00"},
{"employee":"6","Type":"Employer contribution","Transaction":{"name":"sdl_employer","caption":"SDL - Employer","description":"SDL - Employer","type":"employer_contribution","accounting_addition":{"group":"liability"},"code":4142},"Previous":"R 145.00","Selected":"R 145.00","Variance":"R 0.00"},
{"employee":"6","Type":"Employer contribution","Transaction":{"name":"uif_employer","caption":"UIF - Employer","description":"UIF - Employer","type":"employer_contribution"},"Previous":"R 148.72","Selected":"R 148.72","Variance":"R 0.00"},
{"employee":"6","Type":"Income","Transaction":{"taxable_income":1,"uif_income":1,"sdl_income":1,"type":"income","caption":"Basic Salary","frequency":"regular","fractional":true,"name":"basic_salary","formula":{},"calculation_output":true},"Previous":"R 15,000.00","Selected":"R 15,000.00","Variance":"R 0.00"},
{"employee":"6","Type":"Summary","Transaction":{"name":"gross_remuneration","caption":null,"type":"summary"},"Previous":"R 15,300.00","Selected":"R 15,300.00","Variance":"R 0.00"},
{"employee":"6","Type":"Summary","Transaction":{"name":"taxable_income","caption":"Gross Remuneration - Taxable Portion (before deductions)","description":"Gross Remuneration - Taxable Portion (before deductions)","type":"summary"},"Previous":"R 15,300.00","Selected":"R 15,300.00","Variance":"R 0.00"},
{"employee":"6","Type":"Taxable income deduction","Transaction":{"name":"retirement_deduction","caption":null,"type":"taxable_income_deduction"},"Previous":"R 800.00","Selected":"R 800.00","Variance":"R 0.00"},
{"employee":"6","Type":"Total","Transaction":{"name":"nett_pay","caption":"Nett Pay","description":"Nett Pay","type":"total"},"Previous":"R 12,877.53","Selected":"R 12,877.53","Variance":"R 0.00"}
]
Response
If executed correctly the response body is a JSON object containing the relevant information for the report, similar to this snippet ->
The response comes back in the form of an array of hashes, each hash containing the data relevant to a certain employee, identified by the employee number as given in the request.
Comparison Leave Report
Request
https://api.payroll.simplepay.cloud/v1/clients/:client_id/reports/comparison_leave
Leave Types
In order to get the leave type IDs, generate a report on the front end with the leave types selected and inspect the request URL.
Request
This is an HTTP POST request to URL ->
Where the parameter :client_id
is the ID of a specific client, obtained from the call to get a list of clients.
comparison_leave
is the ID for this report
Request Body
The request body should be a JSON object. It contains the fields that will determine which information is included in the report.
{
"start_date": "2017-12-01",
"end_date": "2017-12-31",
"wave_ids": [1,2],
"employee_ids": [6,2],
"leave_types": [5,6],
"humanize": true
}
Request Body
Name | Type | Examples |
---|---|---|
start_date | String | "2016-11-23" |
end_date | String | "2017-02-13" |
wave_ids | Array | null or [2, 3] |
employee_ids | Array | null or [6, 7, 9] |
leave_types | Array | [5, 6] |
humanize | Boolean | null, true, false |
Response
[
{"employee":"6","leave_type":"Annual","Date":"2017-12-31","Accrual":"1.25","Entitlement":"3.75","Taken":null,"Adjustment":null,"Balance":"18.75"},
{"employee":"6","leave_type":"Sick","Date":"2017-12-31","Accrual":null,"Entitlement":"30.00","Taken":null,"Adjustment":null,"Balance":"30.00"},
{"employee":"2","leave_type":"Annual","Date":"2017-12-31","Accrual":"1.25","Entitlement":"5.81","Taken":null,"Adjustment":null,"Balance":"5.81"},
{"employee":"2","leave_type":"Sick","Date":"2017-12-31","Accrual":null,"Entitlement":"30.00","Taken":null,"Adjustment":null,"Balance":"30.00"}
]
Response
If executed correctly the response body is a JSON object containing the relevant information for the report, similar to this snippet ->
The response comes back in the form of an array of hashes, each hash containing the data relevant to a certain employee, identified by the employee number as given in the request.
Leave Liabilities Report (BETA)
Request
https://api.payroll.simplepay.cloud/v1/clients/:client_id/reports/leave_liability_v2
Request
This is an HTTP POST request to URL ->
Where the parameter :client_id
is the ID of a specific client, obtained from the call to get a list of clients.
leave_liability_v2
is the ID for this report
Request Body
{
"date": "2017-12-31",
"wave_ids": [1,2],
"employee_ids": [6,2],
"humanize": true
}
Request Body
The request body should be a JSON object. It contains the fields that will determine which information is included in the report.
Name | Type | Examples |
---|---|---|
date | String | "2016-11-23" |
wave_ids | Array | null or [2,3] |
employee_ids | Array | null or [6,7,9] |
humanize | Boolean | null, true, false |
Response
Response
[
{"employee":"6","Days":"18.75","Daily Rate":"R 692.31","Liability":"R 12,980.78"},
{"employee":"2","Days":"5.81","Daily Rate":"R 553.85","Liability":"R 3,215.91"}
]
If executed correctly the response body is a JSON object containing the relevant information for the report, similar to this snippet ->
The response comes back in the form of an array of hashes, each hash containing the data relevant to a certain employee, identified by the employee number as given in the request.
Tracked Balances Report (BETA)
Parameters
Request
https://api.payroll.simplepay.cloud/v1/clients/:client_id/reports/tracked_balances
Request
This is an HTTP POST request to URL ->
Where the parameter :client_id
is the ID of a specific client, obtained from the call to get a list of clients.
tracked_balances
is the ID for this report
Request Body
{
"wave_ids": [1,2],
"employee_ids": [6,2],
"date": "2017-12-31",
"humanize": true
}
Request Body
The request body should be a JSON object. It contains the fields that will determine which information is included in the report.
Name | Type | Examples |
---|---|---|
date | String | "2016-11-23" |
wave_ids | Array | null or [2,3] |
employee_ids | Array | null or [6,7,9] |
humanize | Boolean | null, true, false |
Response
Response
[
{"employee":"6","Loans":"R 10000.00","Savings":"R 110.00","Garnishees":"R 0.00"},
{"employee":"2","Loans":"R 2000.00","Savings":"R 0.00","Garnishees":"R 0.00"}
]
If executed correctly the response body is a JSON object containing the relevant information for the report, similar to this snippet ->
The response comes back in the form of an array of hashes, each hash containing the data relevant to a certain employee, identified by the employee number as given in the request.
Large Reports
This section should be used if the caller expects significant data to be pulled from a specific report and is likely to time out. There is no guarantee that the report will get executed immediately (as it gets queued), so please ensure that this is used from a batch process or appropriate UI is shown to the end user and the status polled every 10 seconds (at the minimum).
By following the below steps, the report can be run and later retrieved with a Universally Unique Identifier (UUID).
Request 1
https://api.payroll.simplepay.cloud/v1/clients/:client_id/reports/:report/async
Request 1
This is an HTTP POST request to URL ->
Where the only change to the report endpoint is the addition of the /async
in the path.
Request Body 1
The Request Body is specific to the report.
Response 1
[
{"message":"Started","uuid":"ad8b49de-fa5c-4603-8831-b26cb086941a"}
]
Response 1
If executed correctly the response status is HTTP 200 and the response body is a JSON object containing the UUID, similar to this snippet ->
A response status of HTTP 429 signifies that too many requests are already queued.
The UUID can be used in the Request 2 section to verify the status of the report.
Request 2
https://api.payroll.simplepay.cloud/v1/clients/:client_id/reports/poll/:uuid
Request 2
This is an HTTP GET request to URL ->
Where the parameter :client_id
is the ID of the specific client used in Request 1.
:uuid
is the UUID response retrieved in Response 1.
Response 2
If the report is still running, you may get HTTP 204 and you should check back later with the same request. If the report is complete, you will get HTTP 200 with the response body as the JSON object of the report -- same as if you'd got it from the regular endpoint.
HTTP Status
The SimplePay API utilizes conventional HTTP response codes to indicate the success or failure of a request.
Code | Error Message | Description |
---|---|---|
200 | Success | Report is running or completed with results |
429 | Too Many Requests | Too many reports have already been queued |
404 | Requested Resource Not Found | UUID not found |
204 | No Content | Report still running |
Calculations
Get a List of Calculations
Note: Inherited calculations will be displayed with a null id
field.
Request
Request
https://api.payroll.simplepay.cloud/v1/employees/:employee_id/calculations
https://api.payroll.simplepay.cloud/v1/payslips/:payslip_id/calculations
This is an HTTP GET request to URL ->
Since a calculation can be associated with a client, an employee, or a payslip, there are 3 types of requests that can be used.
Response
Response
[
{"id":172,"employee_id":9,"payslip_id":null,"inputs":{"no_autopay_public_holidays":"false","fixed_amount":15000.0,"additional_paid_hours":"false","override_calculated_rate":"false"},"calculation_id":null,"account_components":{},"deleted":false,"account_outputs":{},"client_id":2,"created_at":"2018-01-09T16:08:06.287+02:00","updated_at":"2018-01-09T16:08:06.287+02:00","calculation_def_id":null,"profile_id":null,"skip":false,"multiplier":null,"input_formulas":{},"skip_rule":false,"overrides":{},"outputs":{},"system_type":"basic_salary"},
{"id":170,"employee_id":9,"payslip_id":null,"inputs":{"full_day_hours_input":8.0,"schedule":"fixed","works_mon":"true","day_type_mon":"full","works_tue":"true","day_type_tue":"full","works_wed":"true","day_type_wed":"full","works_thu":"true","day_type_thu":"full","works_fri":"true","day_type_fri":"full","works_sat":"false","works_sun":"false"},"calculation_id":null,"account_components":{},"deleted":false,"account_outputs":{},"client_id":2,"created_at":"2018-01-09T16:08:06.257+02:00","updated_at":"2018-01-09T16:08:06.257+02:00","calculation_def_id":null,"profile_id":null,"skip":false,"multiplier":null,"input_formulas":{},"skip_rule":false,"overrides":{},"outputs":{"full_day_hours":8.0,"avg_working_day":0.0,"full_days_per_week":5.0,"scheduled_days_per_week":5.0,"annual_leave_entitlement":15.0,"scheduled_hours_per_week":40.0},"system_type":"week_hours"},
{"id":121,"employee_id":9,"payslip_id":null,"inputs":{"fixed_amount":9000.0},"calculation_id":null,"account_components":{},"deleted":false,"account_outputs":{},"client_id":2,"created_at":"2018-01-09T16:07:47.823+02:00","updated_at":"2018-02-19T13:17:03.036+02:00","calculation_def_id":null,"profile_id":null,"skip":false,"multiplier":null,"input_formulas":{},"skip_rule":false,"overrides":{},"outputs":{},"system_type":"annual_bonus"},
{"id":122,"employee_id":9,"payslip_id":null,"inputs":{"fixed_amount":9001.0},"calculation_id":null,"account_components":{},"deleted":false,"account_outputs":{},"client_id":2,"created_at":"2018-01-09T16:07:47.835+02:00","updated_at":"2018-01-09T16:07:48.097+02:00","calculation_def_id":5465465,"profile_id":null,"skip":false,"multiplier":null,"input_formulas":{},"skip_rule":false,"overrides":{},"outputs":{},}
]
If executed correctly the response body is a JSON array with a list of calculations, which should be similar to this snippet ->
Get a Specific Calculation
Note: If you wish to view a specific inherited calculation, use Get a specific Inherited Calculation instead.
Request
Request
https://api.payroll.simplepay.cloud/v1/calculations/:id
This is an HTTP GET request to URL ->
Where the parameter :id
is the ID of a specific calculation obtained from the call to get a list of calculations.
Response
Response
{"id":60,"employee_id":null,"payslip_id":16,"inputs":{"fixed_amount":9000.0},"calculation_id":9,"account_components":{},"deleted":false,"account_outputs":{},"client_id":2,
"created_at":"2018-01-09T16:07:30.880+02:00","updated_at":"2018-01-09T16:07:30.938+02:00","calculation_def_id":null,"profile_id":null,"skip":false,"multiplier":null,
"input_formulas":{},"skip_rule":"false","overrides":{},"outputs":{"short_pay":0.0,"normal_pay":0.0,"sunday_pay":0.0,"normal_rate":51.92307692,"short_hours":0.0,"sunday_rate":103.8462,
"basic_salary":9000.0,"holiday_rate":103.8462,"normal_hours":0.0,"overtime_pay":0.0,"sunday_hours":0.0,"overtime_rate":77.8846,"shifts_worked":0.0,"overtime_hours":0.0,"sick_leave_pay":0.0,
"sunday_overtime":0.0,"annual_leave_pay":0.0,"custom_leave_pay":0.0,"public_holiday_pay":0.0,"sunday_overtime_rate":103.8462,"additional_normal_pay":0.0,"sunday_overtime_hours":0.0,
"annual_leave_pay_extra":0.0,"directors_remuneration":0.0,"sunday_pay_fluctuating":0.0,"compassionate_leave_pay":0.0,"hours_worked_plus_payable":0.0,"labour_broker_remuneration":0.0,
"non_directors_remuneration":0.0,"unpaid_leave_negative_income":0.0,"independent_contractor_remuneration":0.0},"system_type":"basic_salary"}
If executed correctly the response body is a JSON object of the requested calculation, which should be similar to this snippet ->
Create/Update a Calculation
This request can be used to either create or update a calculation. If a calculation of the same type exists, the calculation will be updated with the details provided. When doing an update, only the supplied attributes are updated, existing attributes are kept as-is.
Note:
- Request 1 can also be used to update inherited calculations associated with an employee. Please see Inherited Calculation Attributes for more information.
- For finding the list of
calc_type
and the attributes to be provided incalculation_details
, it is recommended to set up calculations via the UI and examine the output via API. effective_date
field is only applicable when creating/updating an inherited calculation.
Request 1
https://api.payroll.simplepay.cloud/v1/employees/:employee_id/calculations
Request 1
This is an HTTP POST request to URL ->
Request 2
https://api.payroll.simplepay.cloud/v1/payslips/:payslip_id/calculations
Request 2
This is an HTTP POST request to URL ->
Example Request body
{
"calc_type”:”annual_bonus",
"calculation_details":{
“amount”:123
}
}
Response
Response
{
"message": "Calculation annual_bonus has been created/updated",
"id": 910490037
}
If executed correctly the response body is a success message with the ID of the created or updated calculation, which should be similar to the 'Response' snippet ->
Delete a Calculation
Request
Request
https://api.payroll.simplepay.cloud/v1/calculations/:id
This is an HTTP DELETE request to this URL ->
Where the parameter :id
is the ID of a specific calculation obtained from the call to get a list of calculations.
Response
Response
{
"message": "Calculation with id 9104 has been deleted."
}
If executed correctly the response body is a success message containing the ID of the deleted calculation, which should be similar to this snippet ->
Inherited Calculations
Get a List of Inherited Calculations
Request
https://api.payroll.simplepay.cloud/v1/employees/:employee_id/inherited_calculations
Request
This is an HTTP GET request to URL ->
Response
Response
[
{
"id": 3278, "profile_id": null, "employee_id": 4535, "short_name": "week_hours", "calculation_def_id": null, "created_at": "2020-02-19T23:27:18.909+08:00", "updated_at": "2020-02-19T23:27:18.909+08:00",
"inputs": { "full_day_hours_input": 8.8, "schedule": "fixed", "leave_any_day": "true", "works_mon": "false", "works_tue": "true", "works_wed": "true", "works_thu": "true", "works_fri": "false", "works_sat": "true", "works_sun": "true", "day_type_mon": "full", "day_type_tue": "full", "day_type_wed": "full", "day_type_thu": "full", "day_type_fri": "full", "day_type_sat": "full", "day_type_sun": "full", "full_days_per_week": 5.0 },
"inputs_history": {
"2020-03-01": { "works_fri": "false", "works_mon": "false", "leave_any_day": "true" },
"2019-07-01": { "works_sat": "true", "works_sun": "true", "day_type_sat": "full", "day_type_sun": "full", "full_days_per_week": "5.0" },
"": { "full_day_hours_input": "8.8", "schedule": "fixed", "works_mon": "true", "works_tue": "true", "works_wed": "true", "works_thu": "true", "works_fri": "true", "works_sat": "false", "works_sun": "false", "day_type_mon": "full", "day_type_tue": "full", "day_type_wed": "full", "day_type_thu": "full", "day_type_fri": "full" }
}
},
...
]
If executed correctly the response body is a JSON array with a list of inherited calculations associated with the employee, which should be similar to this snippet ->
Get a Specific Inherited Calculation
Request
https://api.payroll.simplepay.cloud/v1/inherited_calculations/:id
Request
This is an HTTP GET request to URL ->
Where the parameter :id
is the ID of a specific inherited calculation obtained from the call to get a list of inherited calculations.
Response
Response
{
"id": 3278, "profile_id": null, "employee_id": 4535, "short_name": "week_hours", "calculation_def_id": null, "created_at": "2020-02-19T23:27:18.909+08:00", "updated_at": "2020-02-19T23:27:18.909+08:00",
"inputs": { "full_day_hours_input": 8.0, "schedule": "fixed", "leave_any_day": "true", "works_mon": "false", "works_tue": "true", "works_wed": "true", "works_thu": "true", "works_fri": "true", "works_sat": "true", "works_sun": "true", "day_type_mon": "full", "day_type_tue": "full", "day_type_wed": "full", "day_type_thu": "full", "day_type_fri": "full", "day_type_sat": "full", "day_type_sun": "full", "full_days_per_week": 5.0 },
"inputs_history": {
"2020-03-01": { "works_mon": "false", "leave_any_day": "true" },
"2019-07-01": { "works_sat": "true", "works_sun": "true", "day_type_sat": "full", "day_type_sun": "full", "full_days_per_week": "5.0" },
"": { "full_day_hours_input": "8.0", "schedule": "fixed", "works_mon": "true", "works_tue": "true", "works_wed": "true", "works_thu": "true", "works_fri": "true", "works_sat": "false", "works_sun": "false", "day_type_mon": "full", "day_type_tue": "full", "day_type_wed": "full", "day_type_thu": "full", "day_type_fri": "full" }
}
}
If executed correctly the response body is a JSON object of the requested inherited calculation, which should be similar to this snippet ->
Inherited Calculation Attributes
Note:
- A "v2" requirement indicates that the client will need to have been migrated to v2 by the support team.
- Regular Hours v1 should be handled as a Calculation.
Name | calc_type | Associated with | Requirements |
---|---|---|---|
Regular Hours | week_hours | Employee | v2 |
Attribute | Details | Type | Applicability |
---|---|---|---|
calc_type | The inherited calculation to be updated or created. | String | Required |
effective_date | The date on which the Inherited Calculation takes effect. In the format YYYY-MM-DD. | Date String | See Request under Update an Inherited Calculation |
calculation_details | Please see Available Attributes table(s) below. | Hash | Required |
Available Regular Hours Attributes
Note: # refers to a day of the week and can be either mon, tue, wed, thu, fri, sat or sun.
Attribute | Details | Type | Applicability |
---|---|---|---|
full_day_hours_input | Hours per day | Integer | Optional |
schedule | See Help Site for more information.
|
String | Optional |
leave_any_day | Allow leave on any day | Boolean | Optional. Applicable if schedule is "fixed" and enabled by Customer Support |
works_# | Does the employee work on the specified weekday. | Boolean | Optional. Applicable if schedule is "fixed" |
day_type_# |
|
String | Optional. Applicable if works_# is true |
partial_hours_# | Amount of hours the employee works on the specified weekday | Integer | Optional. Applicable if day_type_# is "partial" |
full_days_per_week | See Help Site for more information.
|
Blank or Integer | Optional, will default to number of works_# unless overridden. |
Update an Inherited Calculation
Only the supplied attributes are updated, existing attributes are kept as-is.
Request
https://api.payroll.simplepay.cloud/v1/employees/:employee_id/inherited_calculations
Request
This is an HTTP PATCH request to this URL ->
The effective_date
field is required if the employee has finalised payslips.
Example Request body
{
"calc_type": "week_hours",
"effective_date": "2020-04-01",
"calculation_details": {
"full_day_hours_input": 8.0,
"schedule": "fixed",
...
}
}
Response
Response
{
"message": "Inherited calculation Week Hours has been created/updated",
"id": 3226
}
If executed correctly the response body is a success message with the ID of the created or updated inherited calculation, which should be similar to the 'Response' snippet ->
Calculations and Accounts
Get a List of All Available System Items, Custom Items and Accounts
Request
Request
https://api.payroll.simplepay.cloud/v1/clients/:client_id/items_and_outputs
This is an HTTP GET request to URL ->
Where the parameter :client_id
is the ID of a specific client, obtained from the call to get a list of clients.
Response
Response
[
{
"system_items": [
{
"name": "annual_bonus",
"label": "Annual Bonus",
"item_type": "income",
"once_off": true
},
{
"name": "bike",
"label": "Bike to Work Scheme",
"item_type": "benefit",
"once_off": false
},
...
],
"custom_items": [
{
"id": 145963,
"label": "Parking Fee",
"item_type": "deduction",
"once_off": false
},
{
"id": 145964,
"label": "Gym Fee",
"item_type": "benefit",
"once_off": false
},
...
],
"accounts": [
{
"type": "system_item",
"name": "pension_fund_rac_employee",
"label": "RAC",
"account_type": "deduction",
"system_item": "pension_fund"
},
{
"type": "derived",
"name": "annual_leave_balance",
"label": "Annual Leave Balance",
"account_type": "leave"
},
{
"type": "custom_item",
"id": 469068,
"label": "Parking Fee",
"account_type": "deduction",
"custom_item": 145963
},
{
"type": "custom_item",
"id": 469079,
"label": "Gym Fee",
"account_type": "benefit",
"custom_item": 145964
},
...
]
}
]
If executed correctly the response body is a JSON array with a list of the system items, custom items and accounts, which should be similar to this snippet ->
Service Periods
Get a List of Service Periods for an Employee
Request
Request
https://api.payroll.simplepay.cloud/v1/employees/:employee_id/service_periods
This is an HTTP GET request to URL ->
Where the parameter :employee_id
is the ID of a specific employee, obtained from the call to get a list of employees.
Meanings for termination_code
values can be found by viewing the Reason For Termination drop-down list on the End Service page.
The negative
field indicates that the service period termination did not actually refer to employment termination but was used to indicate long term leave (e.g. maternity leave).
The attribs
field may contain the ie_employment_identifier
field which provides the employee's employment number for the period.
Response
Response
[{
"service_period":
{
"id": 1111,
"employee_id": 12345,
"start_date": "2019-11-02",
"end_date": null,
"negative": false,
"created_at": "2019-09-11T10:01:41.539+02:00",
"updated_at": "2019-09-11T10:01:41.539+02:00",
"attribs": { "ie_employment_identifier": "2" },
"termination_code": null
}
},
{
"service_period":
{
"id": 1110,
"employee_id": 12345,
"start_date": "2016-08-01",
"end_date": "2019-10-18",
"negative": false,
"created_at": "2016-08-02T12:57:20.313+02:00",
"updated_at": "2019-09-11T09:56:16.415+02:00",
"attribs": { "ie_employment_identifier": "1" },
"termination_code": 2
}
}]
If executed correctly the response body is a JSON hash containing the list of service period hashes, which should be similar to this snippet ->
Update Service Period Termination Information
Request
Request
https://api.payroll.simplepay.cloud/v1/employees/:employee_id/service_periods/end_service
This is an HTTP POST request to URL ->
Where the parameter :employee_id
is the ID of a specific employee, obtained from the call to get a list of employees.
This request can be used both to end an employee's service and to update termination information that was previously recorded.
Request Body
Request Body
{
"employee_action": {
"termination_date": "2019-10-18",
"termination_code": 3
}
}
The request body should be a JSON object containing the details of the termination. A request body sample is shown to the right ->
Response
Response
{
"message":"Employee has been terminated"
}
If executed correctly the response body is a success message indicating that the employee has been terminated, which should be similar to this snippet ->
Reinstate an Employee
Request
Request
https://api.payroll.simplepay.cloud/v1/employees/:employee_id/service_periods/reinstate
This is an HTTP POST request to URL ->
Where the parameter :employee_id
is the ID of a specific employee, obtained from the call to get a list of employees.
Request Body
Request Body
{
"employee_action": {
"appointment_date": "2019-11-02"
}
}
The request body should be a JSON object containing the appointment date of the new service period. A request body sample is shown to the right ->
Response
Response
{
"message":"Employee has been reinstated"
}
If executed correctly the response body is a success message indicating that the employee has been reinstated, which should be similar to this snippet ->
Undo Termination of an Employee
Request
Request
https://api.payroll.simplepay.cloud/v1/employees/:employee_id/service_periods/undo_end_service
This is an HTTP DELETE request to URL ->
Where the parameter :employee_id
is the ID of a specific employee, obtained from the call to get a list of employees.
Response
Response
{
"message":"Termination has been cancelled"
}
If executed correctly the response body is a success message indicating that the most recent termination has been cancelled, which should be similar to this snippet ->
Leave
Get an Employee's Leave Balances
Request
Request
https://api.payroll.simplepay.cloud/v1/employees/:employee_id/leave_balances
This is an HTTP GET request to URL ->
Where the parameter :employee_id
is the ID of a specific employee, obtained from the call to get a list of employees.
The desired date is passed through as a parameter, as you can see in the added parameters, we are first requesting the leave balance on 2022-12-01.
Alternatively, instead of a specific date, latest
can be used to get the balances as of the last day that they were updated.
Added Parameters - Desired Date
?date=2022-12-01
Response
Response
{
"5":4.5968,
"6":30,
"7":3
}
Added Parameters -
latest
?date=latest
Response
{
"type_id":5,
"balance":8.1331,
"date":"2023-07-14"
},
{
"type_id":6,
"balance":27,
"date":"2023-05-20"
},
{
"type_id":7,
"balance":1,
"date":"2023-05-20"
}
If executed correctly the response body is a JSON hash containing the ID key and the leave balances, which should be similar to this snippet ->
Get a List of Available Leave Types
Request
Request
https://api.payroll.simplepay.cloud/v1/clients/:client_id/leave_types
This is an HTTP GET request to URL ->
Where the parameter :client_id
is the ID of a specific client, obtained from the call to get a list of clients.
Response
Response
{
"5":"Annual",
"6":"Sick",
"7":"Compassionate",
"8":"Unpaid"
}
If executed correctly the response body is a JSON hash containing the ID key and leave type value, which should be similar to this snippet ->
Get a List of Leave Days for an Employee
Request
Request
https://api.payroll.simplepay.cloud/v1/employees/:employee_id/leave_days
This is an HTTP GET request to URL ->
Where the parameter :employee_id
is the ID of a specific employee, obtained from the call to get a list of employees.
Response
Response
[
[{"id":46,"date":"2018-02-12","hours":null,"leave_type":"annual_leave","type_id":5}],
[{"id":47,"date":"2018-02-13","hours":null,"leave_type":"annual_leave","type_id":5}],
[{"id":49,"date":"2018-02-15","hours":null,"leave_type":"compassionate_leave","type_id":7}],
[{"id":52,"date":"2018-02-18","hours":null,"leave_type":"sick_leave","type_id":6}],
[{"id":54,"date":"2018-02-20","hours":null,"leave_type":"sick_leave","type_id":6}],
[{"id":152,"date":"2018-01-12","hours":null,"leave_type":"annual_leave","type_id":5}],
[{"id":151,"date":"2018-01-11","hours":7.0,"leave_type":"annual_leave","type_id":5}],
[{"id":155,"date":"2018-01-11","hours":1.0,"leave_type":"compassionate_leave","type_id":7}],
]
If executed correctly the response body is a JSON array containing each of the employees' approved leave days similar to this snippet ->
The hash contains the ID of the leave day (used to update and delete), the date, number of hours taken (null
hours represent a full day of leave), the leave type and the leave type id.
Create a New Leave Day
Request
Request
https://api.payroll.simplepay.cloud/v1/employees/:employee_id/leave_days
This is an HTTP POST request to URL ->
Where the parameter :employee_id
is the ID of a specific employee, obtained from the call to get a list of employees.
Request Body
Request Body
{
"date":"2017-12-11",
"hours":"2",
"type_id":"2"
}
The request body should be a JSON object containing the details of the leave day to be saved. A request body sample is shown to the right ->
The type_id
can be obtained from the call to get a list of available leave types.
If hours are set to null
, or simply left out, a full day of leave will be created.
Response
Response
{
"message": "Leave day created",
"id": 157
}
If executed correctly the response body is a JSON object with details of the transaction and the ID of the created leave day, and should be similar to this snippet ->
Create Multiple New Leave Days
Request
Request
https://api.payroll.simplepay.cloud/v1/employees/:employee_id/leave_days/create_multiple
This is an HTTP POST request to URL ->
Where the parameter :employee_id
is the ID of a specific employee, obtained from the call to get a list of employees.
Request Body
Request Body
{
"dates": [
{"date": "2017-12-01", "hours": 1, "type_id": 3},
{"date": "2017-12-05", "hours": 3, "type_id": 2},
{"date": "2017-12-06", "hours": 2, "type_id": 4}
]
}
The request body should be a JSON object containing the details of the leave days to be saved. A request body sample is shown to the right ->
The type_id
can be obtained from the call to get a list of available leave types.
If hours are set to null
, or simply left out, a full day of leave will be created.
Response
Response
{
"message": "Leave dates have been created",
"ids": [1234, 1235, 1236]
}
If executed correctly the response body is a JSON object with details of the transaction and an array containing the IDs of the created leave dates, and should be similar to this snippet ->
Update an Existing Leave Day
Request
Request
https://api.payroll.simplepay.cloud/v1/leave_days/:leave_day_id
This is an HTTP PATCH request to URL ->
Where the parameter :leave_day_id
is the ID of the leave day you wish to update, obtained from the call to get a list of leave days for an employee.
Request Body
Request body
{
"date":"2017-12-11",
"hours":"2",
"type_id":"2"
}
The request body should be a JSON object containing the details of the leave day to be changed. An example is shown ->
You only need to send those attributes which need to be changed for the leave day.
Response
Response
{
"message": "Leave day successfully updated.",
"id": 157
}
If executed correctly the response body is a JSON object with details of the transaction as well as the ID of the updated leave day, and should be similar to this snippet ->
Delete an Existing Leave Day
Request
Request
https://api.payroll.simplepay.cloud/v1/leave_days/:leave_day_id
This is an HTTP DELETE request to URL ->
Where the parameter :leave_day_id
is the ID of the leave day you wish to update, obtained from the call to get a list of leave days for an employee.
Response
Response
{
"message": "Leave day with id 157 has been deleted."
}
If executed correctly the response body is a JSON object with details of the transaction as well as the ID of the deleted leave day, and should be similar to this snippet ->
Template Profile Mappings
Get a List of Profile Mappings
Profile mappings are mappings between a template and an employee.
Request
Request
https://api.payroll.simplepay.cloud/v1/employees/:employee_id/profile_mappings
This is an HTTP GET request to URL ->
Where the parameter :employee_id
is the ID of a specific employee, obtained from the call to get a list of employees.
Response
Response
[{
"profile_mapping": {
"id":1000,
"employee_id":1234,
"profile_id":123345,"inputs":{},
"created_at":"2019-02-05T09:46:16.623+02:00",
"updated_at":"2019-02-05T09:46:41.061+02:00",
"excluded_calculations":[],
"included_calculations":[111, 222]
}
}]
If executed correctly the response body is a JSON array with a list of the profile mappings associated with the employee, which should be similar to this snippet ->
Create a Profile Mapping
Request
Request
https://api.payroll.simplepay.cloud/v1/employees/:employee_id/profile_mappings
This is an HTTP POST request to URL ->
Where the parameter :employee_id
is the ID of an employee.
Request Body
Request Body
{
"profile_mapping": {
"profile_id": "12344",
"employee_id": "5678"
}
}
The request body should be a JSON object defining the profile mapping, which contains the IDs for the profile and the employee. The profile_id
is the template's ID and can be found on the website in Settings > Templates. An example is shown ->
Response
Response
{
"message": "Profile mapping has been created/updated",
"id":123345
}
If executed correctly the response body is a JSON object with confirmation of the creation and the ID of the new profile mapping, and should be similar to this snippet ->
Delete a Profile Mapping
Request
Request
https://api.payroll.simplepay.cloud/v1/profile_mappings/:profile_mapping_id
This is an HTTP DELETE request to URL ->
Where the parameter :profile_mapping_id
is the ID of a profile mapping, obtained from the call to get a list of profile mappings for an employee.
Response
Response
{
"message": "Profile mapping has been deleted",
"id":123345
}
If executed correctly the response body is a JSON object with confirmation of the deletion and the ID of the deleted profile mapping, and should be similar to this snippet ->
Update a Profile Mapping
Request
Request
https://api.payroll.simplepay.cloud/v1/profile_mappings/:profile_mapping_id
This is an HTTP PUT request to URL ->
Where the parameter :profile_mapping_id
is the ID of a profile mapping, obtained from the call to get a list of profile mappings for an employee.
Request Body
Request Body
{
"profile_mapping":{
"optional_calculation_ids":[123, 234]
}
}
The request body should be a JSON object containing the profile mapping details. The optional_calculation_ids
provided will be enabled on the mapping. Any excluded IDS will be disabled on the mapping. An example is shown ->
Response
Response
{
"message": "Profile mapping has been created/updated",
"id":123345
}
If executed correctly the response body is a JSON object with confirmation of the update and the ID of the updated profile mapping, and should be similar to this snippet ->
Custom Employee Fields
Get a List of Custom Employee Fields
Request
Request
https://api.payroll.simplepay.cloud/v1/clients/:client_id/custom_employee_fields
This is an HTTP GET request to URL ->
Where the parameter :client_id
is the ID of a specific client, obtained from the call to get a list of clients.
Response
Response
[
{
"id": 9109,
"sequence": 1,
"name": "Division",
"hint": "The employee's company division",
"input_type": "dropdown",
"required": false,
"dropdown_options": {
"0": "Finance MA",
"1": "Finance ZA"
},
"show_on_payslip": true,
"edit_via_self_service": false,
"include_in_reports": false
},
{
"id": 9110,
"sequence": 2,
"name": "Contract Expiry Date",
"hint": "The employee's employment contract end date",
"input_type": "date",
"required": false,
"show_on_payslip": false,
"edit_via_self_service": false,
"include_in_reports": true
},
]
If executed correctly the response body is a JSON array with a list of the non-deleted custom employee fields, which should be similar to this snippet ->
Rate Limits
The SimplePay API makes use of rate limits. The default maximum number of requests per hour is 1000. The below headers communicate information about these limits:
X-RateLimit-Limit
: the maximum number of allowed requests in a 60 minute window, with every window being an hour in UTC.X-RateLimit-Remaining
: the number of remaining requests in the current 60 minute window.X-RateLimit-Reset
: A unix timestamp (in UTC) indicating when the current window ends; after this timestamp, the rate limit resets to the value inX-RateLimit-Limit
.
The default limit of 1000 can be raised by contacting Support, along with justification that it is required.
We also have a per-source IP rate limit which cannot be raised due to system stability concerns – if the HTTP 429 doesn't include the above headers, API users are advised to contact Support as they should never hit it in practice.
Errors
Response
{
message: "API User is not authorized or does not exist."
}
The SimplePay API utilizes conventional HTTP response codes to indicate the success or failure of a request. There will also be a JSON response containing a message, similar to the example on the right ->
HTTP Code | Meaning |
---|---|
200 | Success |
400 | Validation Error |
404 | Requested Resource Not Found |
429 | Indicates that the request rate limit has been reached. Currently the limit is 1000 requests and is reset on the hour. Limit information will be communicated through the HTTP header fields X-RateLimit-Limit , X-RateLimit-Remaining , and X-RateLimit-Reset as described above. |
500 | Indicates that an exception occurred in our code. Retrying may or may not help. If this persists, please contact support. |
503 | Down for maintenance. All API callers MUST be able to gracefully recover from this code, and wait at least 10 minutes before retrying. |