NAV Navbar

SimplePay API Docs

  • Introduction
  • Authentication
  • Available Resources
  • Bulk Inputs
  • Clients
  • Employees
  • Get a specific Employee
  • Payment Frequencies
  • Pay Points
  • Payslips
  • Reports
  • Calculations
  • Leave
  • Errors
  • 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.

    SimplePay Terminology

    Before using the API, please take note of the following terminology:

    Resource Details
    client A company
    wave A payment frequency, i.e. the frequency with which employees are paid
    pay_point Means of grouping employees, e.g. by department

    Authentication

    Authentication involves two steps. Firstly, API users should generate a key to be 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:

    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://www.simplepay.com.sg/api/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

    Client Information

    Employee Profiles

    Payslips

    Calculations

    Reports

    Leave

    ** Additional functionality is being assessed and developed incrementally based on user requirements

    Bulk Inputs

    Update Employees and Payslips

    Request

    Request

    https://www.simplepay.com.sg/api/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": "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

    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": "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://www.simplepay.com.sg/api/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://www.simplepay.com.sg/api/v1/clients/:client_id/employees
    

    This is an HTTP GET 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.

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

    Get a specific Employee

    Request

    Request

    https://www.simplepay.com.sg/api/v1/employees/:id
    

    This is an HTTP GET request to this 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"
        },
        ...
      }
    }
    

    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://www.simplepay.com.sg/api/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 abreviated request body sample is shown to the right ->

    There are several required attributes for creating an employee, as well as certain optional ones. These 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": "The employee Alice Williams (Number: 1100) has been created.",
      "id": 1
    }
    

    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 - Female Muslim Chinese Singapore Citizen paid by GIRO

    { "employee": {
      "wave_id": 1350676447,
      "first_name": "Juliet",
      "last_name": "Tang",
      "birthdate": "1985-02-06",
      "appointment_date": "2010-02-06",
      "legal_status": "CITIZEN",
      "nric": "S8785154J",
      "gender": "M",
      "race": "CHINESE",
      "religion": "MUSLIM",
      "sdl_exempt": "false",
      "cpf_exempt": "false",
      "payment_method": "eft_manual",
      "bank_account": {
        "bank_id": 2081327566,
        "account_number": "123456778",
        "branch_code": "456"
      },
      "number": "00002"
    }}
    

    Request body - Male Buddhist Eurasian Singapore Permanent Resident paid via cheque

    { "employee": {
      "wave_id": 1350676447,
      "first_name": "Jeffery",
      "last_name": "Walsh",
      "birthdate": "1985-02-06",
      "appointment_date": "2010-02-06",
      "legal_status": "PR",
      "nationality": "354",
      "nric": "S8785154J",
      "pr_date" : "2009-01-01",
      "gender": "M",
      "race": "EURASIAN",
      "religion": "BUDDHIST",
      "sdl_exempt": false,
      "cpf_exempt": false,
      "payment_method": "cheque",
      "physical_address":
      {
        "type": "L",
        "block_no": "5",
        "st_name": "Orchard Link",
        "level_no": "22",
        "unit_no": "6",
        "postal_code": "237978"
      },
      "number": "1234567"
    }}
    

    Request body - Male Christian Indian Foreigner with a Work Permit and paid cash

    { "employee": {
      "wave_id": 1350676447,
      "first_name": "Nitesh",
      "last_name": "Pillay",
      "birthdate": "1985-02-06",
      "appointment_date": "2010-02-06",
      "legal_status": "FOREIGNER_WP",
      "nationality": "354",
      "fin": "F9864842U",
      "gender": "M",
      "race": "INDIAN",
      "religion": "CHRISTIAN",
      "sdl_exempt": "false",
      "cpf_exempt": "false",
      "payment_method": "cash",
      "number": "EMP003"
    }}
    

    Request body - Foreign address

    { "employee": {
      "wave_id": 1350676447,
      "first_name": "Nitesh",
      "last_name": "Pillay",
      "birthdate": "1985-02-06",
      "appointment_date": "2010-02-06",
      "legal_status": "FOREIGNER_WP",
      "nationality": "354",
      "fin": "F9864842U",
      "gender": "M",
      "race": "INDIAN",
      "religion": "CHRISTIAN",
      "sdl_exempt": false,
      "cpf_exempt": false,
      "payment_method": "cash",
      "physical_address": {
        "type": "F",
        "address_line1": "123",
        "address_line2": "Moreton Drive",
        "address_line3": "Queensland",
        "tx_uf_postal_code": "4008",
        "country_code": "701"
      },
      "number": "EMP005"
    }}
    

    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
    payment_method Method by which employee is paid. The following are valid values:
    • "cash"
    • "cheque"
    • "eft_manual" (for employees paid by GIRO)
    String Required
    birthdate Employee date of birth in the format YYYY-MM-DD Date String Required
    appointment_date The date of appointment in the format YYYY-MM-DD Date String Required
    legal_status Employee legal status in Singapore. The following are valid values:
    • "CITIZEN" - Singapore Citizen
    • "PR" - Singapore Permanent Resident
    • "FOREIGNER" - Foreigner without a Work Permit
    • "FOREIGNER_WP" - Foreigner with a Work Permit
    • "FD_MALAYSIA" - Malaysian foreign director
    • "FD_OTHER" - Any other foreign director
    String Required
    nric Employee NRIC starting with "S" or "T" String Required if legal_status is "CITIZEN" or "PR"
    fin Eemployee FIN String Required if legal_status is "FOREIGNER" or "FOREIGNER_WP"
    malaysian_ic Employee Malaysian IC String Required if legal_status is "FD_MALAYSIA"
    passport_number Employee passport number String Required if legal_status is "FD_OTHER"
    nationality Employee nationality. Please see the Data Lists section for valid values String Required id legal_status is "PR", "FOREIGNER", "FOREIGNER_WP", "FD_MALAYSIA" or "FD_OTHER".
    pr_date Employee date of attaining Singaporean PR status in format YYYY-MM-DD Date String Required if legal_status is "PR"
    gender Employee gender. The following are valid values:
    • "M" - Male
    • "F" - Female
    String Required
    race Employee race. Used to determine applicablity of Self-Help Group Funds. Please see the Data Lists section for valid values String Required
    religion Employee religion. Used to determine applicabiliy of Self-Help Group Funds. Please see the Data Lists section for valid values String Required
    sdl_exempt Employee SDL exempt indicator Boolean Required
    cpf_exempt Employee CPF exempt indicator Boolean Required
    bank_account Employee bank details object. Please see Child Attributes table below Hash Required if payment_method is "eft_manual"
    physical_address Employee address object. Please see Child Attributes table below Hash Optional
    number Employee identiying number for payroll purposes. String Required if client employee_number_mode is "EMPLOYEE_NUMBER_MANUAL" - must be set via UI

    Child Attributes

    Parent Attribute Details Type Applicability
    bank_id bank_account id of employee bank. Please see the Data Lists section for valid values Integer Required for parent
    account_number Employee bank account number of minimum four (4) characters String Required for parent
    branch_code Employee bank branch code of three (3) characters String Required for parent
    physical_address type Employee address type. The following are valid values:
    • "L" - Local residential address
    • "F" - Foreign address
    • "C" - Local C/O address
    • "N" - Not available
    String Required for parent
    block_no Street number of employee local physical address String Optional. Only if type is "L"
    st_name Street name of employee local physical address String Optional. Only if type is "L"
    level_no Building level of employee local physical address String Optional. Only if type is "L"
    unit_no Unit number of employee local physical address String Optional. Only if type is "L"
    postal_code Postal code of employee local physical address String Optional. Only if type is "L"
    address_line1 First line of employee foreign or C/O physical address String Optional. Only if type is "F" or "C"
    address_line2 Second line of employee foreign or C/O physical address String Optional. Only if type is "F" or "C"
    address_line3 Third line of employee foreign or C/O physical address String Optional. Only if type is "F" or "C"
    tx_uf_postal_code Postal code for employee foreign or C/O physical address String Optional. Only if type is "F" or "C"
    country_code Country code for employee foreign physical address. Please see the Data Lists section for valid values String Optional. Only if type is "F"

    Data Lists

    The valid values for the following employee attributes can be found by unhiding the Constants sheet in the SimplePay bulk import / export file:

    This file can be downloaded through the UI by going to Employees > Bulk Actions > Bulk Add Employees.

    Update an Employee

    Request

    Request

    https://www.simplepay.com.sg/api/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 changes for an employee.

    Response

    Response

    {
      "message": "The employee Alice Williams (Number: 1100) has been updated.",
      "id": 1
    }
    

    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://www.simplepay.com.sg/api/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://www.simplepay.com.sg/api/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.

    Response

    Response

    [
      {"wave":{
        "id":1350690664,
        "length_months":1,
        "length_weeks":0,
        "first_end_date":"2008-01-31",
        "first_period_offset":112,
        "notification_days_before":null,
        "finalisation_days_before":null,
        "client_id":36818,
        "interim_first_end_date":null,
        "created_at":"2017-08-08T15:41:40.273+02:00",
        "updated_at":"2017-08-08T15:41:40.273+02:00",
        "payslip_payment_day":null
      }}
      ...
    ]
    

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

    Pay Points

    Get a list of Pay Points

    Request

    Request

    https://www.simplepay.com.sg/api/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://www.simplepay.com.sg/api/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.

    Response

    Response

    [
      {
        "payslip": {
          "id":43,
          "date":"2017-09-27",
          "special":false,
          "finalised":true,
          "nett_pay":3480.02,
          "ss_released": true,
          "payment_run_id": 87908
        }
      },
      {
        "payslip": {
          "id":44,
          "date":"2017-10-04",
          "special":false,
          "finalised":false,
          "nett_pay":3480.02,
          "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 a Specific Payslip for an Employee

    Request

    Request

    https://www.simplepay.com.sg/api/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:

    The contents of the second hash relate to the employee's leave types and balances.

    Requesting a PDF payslip

    Request

    https://www.simplepay.com.sg/api/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

    Reports

    General

    Filtering on Employee IDs and Wave IDs

    Humanizing the Data

    Transaction History Report

    Parameters

    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"]
    humanize Boolean null, true, false

    Request

    https://www.simplepay.com.sg/api/v1/clients/:client_id/reports/transaction_history
    

    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.

    Added Parameters

    ?start_date=2017-12-01&end_date=2017-12-31&wave_ids%5B%5D=1&wave_ids%5B%5D=2
    &employee_ids%5B%5D=6&employee_ids%5B%5D=2&account_names%5B%5D=basic_salary&account_names%5B%5D=tax&humanize=true
    

    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 transaction_history is the id for this report

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

    Additional Parameters

    Other parameters added onto this request ->

    These include: start_date = 2017-12-01 end_date = 2017-12-31 wave_ids = [1,2] employee_ids = [6,2] account_names = ["basic_salary", "tax"]

    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

    Parameters

    Name Type Examples
    wave_id Number 131
    employee_ids Array null or [6, 7, 9]
    period_offset Number 112
    humanize Boolean null, true, false

    Request

    https://www.simplepay.com.sg/api/v1/clients/:client_id/reports/variance
    

    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.

    Request

    Added Parameters

    ?wave_id%5D=1&period_offset%5D=119&employee_ids%5B%5D=6&humanize=true
    

    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 variance is the id for this report

    Additional Parameters

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

    Other parameters added onto this request ->

    These include: employee_ids = [6] wave_id = 1 period_offset = 119

    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

    Parameters

    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

    Request

    https://www.simplepay.com.sg/api/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

    Added Parameters

    ?start_date=2017-12-01&end_date=2017-12-31&wave_ids%5B%5D=1&wave_ids%5B%5D=2
    &employee_ids%5B%5D=6&employee_ids%5B%5D=2&leave_types%5B%5D=5&leave_types%5B%5D=6&humanize=true
    

    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 comparison_leave is the id for this report

    Additional Parameters

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

    Other parameters added onto this request ->

    These include: start_date = 2017-12-01 end_date = 2017-12-31 wave_ids = [1,2] employee_ids = [6,2] leave_types = [5,6]

    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)

    Parameters

    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

    Request

    Request

    https://www.simplepay.com.sg/api/v1/clients/:client_id/reports/leave_liability_v2
    

    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 leave_liability_v2 is the id for this report

    Added Parameters

    ?date=2017-12-31&wave_ids%5B%5D=1&wave_ids%5B%5D=2&employee_ids%5B%5D=6&employee_ids%5B%5D=2&humanize=true
    

    Additional Parameters

    Other parameters added onto this request ->

    These include: wave_ids = [1,2] employee_ids = [6,2] date = 2017-12-31

    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

    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

    Request

    https://www.simplepay.com.sg/api/v1/clients/:client_id/reports/tracked_balances
    

    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 tracked_balances is the id for this report

    Added Parameters

    ?date=2017-12-31&wave_ids%5B%5D=1&wave_ids%5B%5D=2&employee_ids%5B%5D=6&employee_ids%5B%5D=2&humanize=true
    

    Additional Parameters

    Other parameters added onto this request ->

    These include: wave_ids = [1,2] employee_ids = [6,2] date = 2017-12-31

    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.

    Calculations

    Get a list of Calculations

    Request

    Request

    https://www.simplepay.com.sg/api/v1/clients/:client_id/calculations
    https://www.simplepay.com.sg/api/v1/employees/:employee_id/calculations
    https://www.simplepay.com.sg/api/v1/payslips/:payslip_id/calculations
    

    This is an HTTP GET request to this URL ->

    Either of the 3 requests can be used, for either the client, employee or payslip respectively.

    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

    Request

    Request

    https://www.simplepay.com.sg/api/v1/calculations/:id
    

    This is an HTTP GET 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

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

    Request

    Request

    https://www.simplepay.com.sg/api/v1/employees/:employee_id/calculations
    https://www.simplepay.com.sg/api/v1/payslips/:payslip_id/calculations
    

    This is an HTTP POST request to this URL ->

    This action can do either the creation or the update of a calculation, depending on whether a calculation of the same type exists, in which case the calculation will be updated with the details that are given.

    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 this snippet ->

    Delete a Calculation

    Request

    Request

    https://www.simplepay.com.sg/api/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 ->

    Leave

    Get an employees leave balance

    Request

    Request

    https://www.simplepay.com.sg/api/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 and the parameter. The desired date is passed through as a parameter, as you can see in the added parameters, we are requesting the leave balance on 2017-12-01

    Added Parameters

    ?date=2017-12-01
    

    Response

    Response

    {
      "5":4.5968,
      "6":30.0,
      "7":3.0,
      "8":0
    }
    

    If executed correctly the response body is a JSON hash containing the ID key and the leave balance, which should be similar to this snippet ->

    Get a list of available leave types

    Request

    Request

    https://www.simplepay.com.sg/api/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://www.simplepay.com.sg/api/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 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 (its null when it's a full day), the leave type and the leave type id.

    Create a new leave day

    Request

    Request

    https://www.simplepay.com.sg/api/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", 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://www.simplepay.com.sg/api/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", 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://www.simplepay.com.sg/api/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://www.simplepay.com.sg/api/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 ->

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

    200: Success | 400: Validation Error | 404: Requested Resource Not Found