Setting the Employee Salary

To set or change an employee's annual salary you will need to issue a new SalaryPayInstruction, if you are unfamilar with the concept of PayInstructions then please read the Understanding Pay Instructions page which will give you an overview of how pay instructions work within PayRun.io.

Getting the employee's current salary

Before deciding if you need to create a new salary pay instruction it's probably best to check what salary SalaryPayInstructions, if any exist, for your employee.

To help find the salary pay instruction, the PayRun.io API includes a pre-defined query. See Active Pay Instructions Report for more info.

Unlike most other payment instructions, Salary Pay Instructions are single instance items. This means that you can only have a single salary active at any one time. The employee's salary pay instructions (start and end dates) cannot overlap.

If the employee has an active salary instruction and needs a different annual salary amount, you must end the existing instruction before the new one starts. Once the old instruction is ended, a new salary pay instruction can be added with the new annual amount.

If no salary exists, simply add the new instruction.

Ending an existing salary

Given the exising salary has a resource location of: /Employer/ER001/Employee/EE001/PayInstruction/SAL001, you use the following API call to set the instruction end date.

If the new salary takes effective on 2017-05-01, the existing instruction should end the day before, 2017-04-30.

curl -X PATCH
   https://api.test.payrun.io/Employer/ER001/Employee/EE001/PayInstruction/SAL001
   -H 'Content-type: application/xml'
   -H 'Accept: application/xml'
   -H 'Api-Version: default'
   -H 'Authorization: {OAuthHeader}'
   -H 'Cache-Control: no-cache'
-d '<?xml version="1.0"?>
<SalaryPayInstruction xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <EndDate>2017-04-30</EndDate>
</SalaryPayInstruction>'
curl -X PATCH
   https://api.test.payrun.io/Employer/ER001/Employee/EE001/PayInstruction/SAL001
   -H 'Content-type: application/json'
   -H 'Accept: application/json'
   -H 'Api-Version: default'
   -H 'Authorization: {OAuthHeader}'
   -H 'Cache-Control: no-cache'
-d '{
  "SalaryPayInstruction": {
    "EndDate": "2017-04-30"
  }
}'

Response Example

<?xml version="1.0"?>
<SalaryPayInstruction xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <StartDate>2017-04-06</StartDate>
    <EndDate>2017-04-30</EndDate>
    <AnnualSalary>25000.00</AnnualSalary>
    <ProRataMethod>NotSet</ProRataMethod>
</SalaryPayInstruction>
{
  "SalaryPayInstruction": {
    "StartDate": "2017-04-06",
    "EndDate": "2017-04-30",
    "AnnualSalary": "25000.00",
    "ProRataMethod": "NotSet"
  }
}

Creating a new salary

The following example demonstrates using [POST] to add a new salary instruction. Using post will create a new instruction with an auto generated unique key (e.g. SAL002). Alternatively, you can use a [PUT] and explicitly specify your own unique key.

curl -X POST
   https://api.test.payrun.io/Employer/ER001/Employee/EE001/PayInstructions
   -H 'Content-type: application/xml'
   -H 'Accept: application/xml'
   -H 'Api-Version: default'
   -H 'Authorization: {OAuthHeader}'
   -H 'Cache-Control: no-cache'
-d '<?xml version="1.0"?>
<SalaryPayInstruction xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <StartDate>2017-05-01</StartDate>
    <AnnualSalary>30000.00</AnnualSalary>
    <ProRataMethod>NotSet</ProRataMethod>
</SalaryPayInstruction>
'
curl -X POST
   https://api.test.payrun.io/Employer/ER001/Employee/EE001/PayInstructions
   -H 'Content-type: application/json'
   -H 'Accept: application/json'
   -H 'Api-Version: default'
   -H 'Authorization: {OAuthHeader}'
   -H 'Cache-Control: no-cache'
-d '{
  "SalaryPayInstruction": {
    "StartDate": "2017-05-01",
    "AnnualSalary": "30000.00",
    "ProRataMethod": "NotSet"
  }
}'

Response Example

<?xml version="1.0"?>
<Link 
    xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    title="Salary: [2017-05-01->]" 
    href="/Employer/ER001/Employee/EE001/PayInstruction/SAL002" 
    rel="SalaryPayInstruction" 
/>
{
  "Link": {
    "@title": "Salary: [2017-05-01->]",
    "@href": "/Employer/ER001/Employee/EE001/PayInstruction/SAL002",
    "@rel": "SalaryPayInstruction"
  }
}

Active Pay Instruction Report

You can find the current employee's salary instruction (if one exists) using the active pay instruction report.

Report Parameters

  • EmployerKey (Required)
    The unique key of the employer. E.g. ER001
  • EmployeeKey (Required)
    The unique key of the employee. E.g. EE001
  • ActiveOn (Required)
    The date to test on. E.g. 2017-04-30
  • Type (Optional)
    The pay instruction type to filter by. E.g. SalaryPayInstruction. If omitted, then all active pay instructions are returned.

You can run the Active Pay Instructions Report from the online API explorer: Active Pay Instructions Report

This example demonstrates how to [GET] the report output.

curl -X GET
   https://api.test.payrun.io/Report/ACTPAYINS/run?EmployerKey=ER001&EmployeeKey=EE001&ActiveOn=2017-04-30&Type=SalaryPayInstruction
   -H 'Content-type: application/xml'
   -H 'Accept: application/xml'
   -H 'Api-Version: default'
   -H 'Authorization: {OAuthHeader}'
   -H 'Cache-Control: no-cache'
curl -X GET
   https://api.test.payrun.io/Report/ACTPAYINS/run?EmployerKey=ER001&EmployeeKey=EE001&ActiveOn=2017-04-30&Type=SalaryPayInstruction
   -H 'Content-type: application/json'
   -H 'Accept: application/json'
   -H 'Api-Version: default'
   -H 'Authorization: {OAuthHeader}'
   -H 'Cache-Control: no-cache'

Response Example

<?xml version="1.0"?>
<ActivePayInstructionsReport xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" Generated="2017-10-10T14:48:12">
  <PayInstructions ActiveOn="2017-04-30">
    <PayInstruction Type="SalaryPayInstruction">
      <Link href="/Employer/ER001/Employee/EE001/PayInstruction/SAL001" />
      <StartDate>2017-04-06</StartDate>
      <EndDate>2018-04-05</EndDate>
      <AnnualSalary>25000.0000</AnnualSalary>
      <ProRataMethod>NotSet</ProRataMethod>
    </PayInstruction>
  </PayInstructions>
</ActivePayInstructionsReport>
{
  "ActivePayInstructionsReport": {
    "@Generated": "2017-10-10T14:54:53",
    "PayInstructions": {
      "@ActiveOn": "2017-04-30",
      "PayInstruction": {
        "@Type": "SalaryPayInstruction",
        "Link": {
          "@href": "/Employer/ER001/Employee/EE001/PayInstruction/SAL001"
        },
        "StartDate": "2017-04-06",
        "EndDate": "2018-04-05",
        "AnnualSalary": "25000.0000",
        "ProRataMethod": "NotSet"
      }
    }
  }
}