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.co.za/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.co.za/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.co.za/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.co.za/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.co.za/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.co.za/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 - RSA Citizen paid by EFT to own bank account

    { "employee": {
      "wave_id": 1350676447,
      "first_name": "Juliet",
      "last_name": "Dean",
      "birthdate": "1985-02-06",
      "appointment_date": "2010-02-06",
      "identification_type": "rsa_id",
      "rsa_id": "8502066392883",
      "payment_method": "eft_manual",
      "bank_account": {
        "bank_id": 1462381520,
        "account_number": "123456778",
        "branch_code": "011006",
        "holder_relationship": "1"
      },
      "number": "00002"
    }}
    

    Request body - Foreign Employee with different postal and residential addresses and paid by cash

    { "employee": {
      "wave_id": 1350676447,
      "first_name": "Jeffery",
      "last_name": "Walsh",
      "birthdate": "1985-02-06",
      "appointment_date": "2010-02-06",
      "identification_type": "passport",
      "other_number": "85879303958",
      "passport_code": "NOR",
      "payment_method": "cash",
      "physical_address":
      {
        "street_number": "5",
        "street_or_farm_name": "Hoft Street",
        "suburb_or_district": "Mowbray",
        "city_or_town": "Cape Town",
        "postal_code": "7705"
      },
      "postal_address":
      {
        "same_as_physical": "false"
        "line1": "22 Thohya Court",
        "line2": "1 Norman Road",
        "line3": "Newlands",
        "line4": "Cape Town",
        "postal_code": "7725"
      }
    }}
    

    The following attributes may be required for the creation of an employee. Certain attributes are always required while others are only conditionally required based on the value of another attribute. There are also certain optional attributes, which can be ignored for creation and added during an update if required.

    Parent Attributes

    Attribute Details Type Applicability
    wave_id The ID of the wave to which the employee belongs Integer Required
    first_name Employee first name String Required
    last_name Employee last name String Required
    birthdate Employee date of birth in the format YYYY-MM-DD Date String Required
    appointment_date The date of appointment in the format YYYY-MM-DD Date String Required
    identification_type The type of identification number used. The following are valid values:
    • "none" - No identification number given
    • "rsa_id" - South African ID number
    • "passport" - Passport number or foreign ID number
    • "asylum_seeker" - Asylum Seeker's Permit number
    • "refugee" - Refugee ID number
    String Required
    id_number Employee ID number String Required if identification_type is "rsa_id" or "refugee"
    other_number Non-RSA identification number String Required if identification_type is "passport" or "asylum_seeker"
    passport_code Passport country code String Required if identification_type is "passport". Country code values can be found Data Lists
    email The employee's email address String Optional. This can be used for self-service.
    number Employee identiying number for payroll purposes. String Required if client employee_number_mode is "EMPLOYEE_NUMBER_MANUAL" - must be set via UI
    job_title Employee's job title String Optional
    income_tax_number The employee's tax number String Optional
    payment_method The method with which the employee will be paid. The following are valid values:
    • "cash"
    • "cheque"
    • "eft_manual"
    String Required
    bank_account Employee bank details object. Please see Child Attributes table below Hash Required if payment_method is "eft_manual"
    physical_address Employee residential address object. Please see Child Attributes table below Hash Optional
    postal_address Employee postal address object. Please see Child Attributes table below Hash Optional

    Child Attributes

    Parent Attribute Details Type Applicability
    bank_account bank_id ID of employee's 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 six (6) characters String Required for parent
    holder_relationship Who owns the given bank account. The following are valid values:
    • "1" - The bank account is held solely by the employee
    • "2" - The account is a joint account
    • "3" - The account is held by a third party
    String
    holder_name The name of the third party account holder String Optional. Only relevant if holder_relationship is "3"
    physical_address unit_number Unit number String Optional
    complex Name of the complex the unit is in String Optional
    street_number Street number of employee's physical address String Optional
    street_or_farm_name Street name (or farm name) of employee's physical address String Optional
    suburb_or_district Name of the suburb or district of employee's physical address String Optional
    city_or_town Name of the city or town of employee's physical address String Optional
    postal_code Postal code of employee's physical address String Optional
    postal_address same_as_physical Indicates whether the postal and residential addresses are different. Boolean
    line1 First line of the postal address String Optional
    line2 Second line of the postal address String Optional
    line3 Third line of the postal address String Optional
    code Postal code String Optional

    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.co.za/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.co.za/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.co.za/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.co.za/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.co.za/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.co.za/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.co.za/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

    Employment Tax Incentive (ETI) 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, 2, 9]
    humanize Boolean null, true, false

    Request

    https://www.simplepay.co.za/api/v1/clients/:client_id/reports/eti
    

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

    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&humanize=true
    

    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]

    Response

    Response

    [
      {"employee":"6","Month":"201712.00","Hours":"160.00","Monthly Remuneration":"R 15,300.00",
      "Monthly Minimum Wage":"R 2,000.00","ETI Calculated":"R 0.00"},
      {"employee":"2","Month":"201712.00","Hours":"160.00","Monthly Remuneration":"R 12,000.00",
      "Monthly Minimum Wage":"R 2,000.00","ETI Calculated":"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.

    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.co.za/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.co.za/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.co.za/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.co.za/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.co.za/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.co.za/api/v1/clients/:client_id/calculations
    https://www.simplepay.co.za/api/v1/employees/:employee_id/calculations
    https://www.simplepay.co.za/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.co.za/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.co.za/api/v1/employees/:employee_id/calculations
    https://www.simplepay.co.za/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.co.za/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.co.za/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.co.za/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.co.za/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.co.za/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.co.za/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.co.za/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.co.za/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