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:

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

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

Child Attributes

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

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.

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.

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

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.

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.

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.

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 in calculation_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.

Available Regular Hours Attributes

Note: # refers to a day of the week and can be either mon, tue, wed, thu, fri, sat or sun.

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 in X-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 ->