Managing the Pay Instruction

Pay instructions are used to store the payment and deduction information for a single employee. Employees hold a collection of Pay Instructions that describe the DNA of their payroll history.

For more information, please see the Understanding Pay Instructions page.

There many different types of pay instruction to cover the different types of payroll calculations. See the Pay Instruction reference page for a complete list.

This example demonstrates management of a primitive pay instruction, but the principles are the same for all instruction types.

Supported HTTP methods are:

[GET] a Pay Instruction

This example demonstrates how to [GET] an existing pay instruction instance.

The Pay instructions reside under the employee instance.
Prefix the pay instruction unique key with the employee resource location:
/Employer/[EmployerKey]/Employee/[EmployeeKey]/PayInstruction/[PayInstructionKey]

curl -X GET
   https://api.test.payrun.io/Employer/ER001/Employee/EE001/PayInstruction/BASIC001
   -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/Employer/ER001/Employee/EE001/PayInstruction/BASIC001
   -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"?>
<PrimitivePayInstruction xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <StartDate>2017-04-06</StartDate>
    <EndDate>2017-05-05</EndDate>
    <Description>Pay slip description</Description>
    <Code>BASIC</Code>
    <Value>150.0000</Value>
</PrimitivePayInstruction>
{
    "PrimitivePayInstruction": {
        "StartDate": "2017-04-06",
        "EndDate": "2017-05-05",
        "Description": "Pay slip description",
        "Code": "BASIC",
        "Value": "150.0000"
    }
}

This example demonstrates how to [GET] links to all pay instructions under a single employee.

curl -X GET
   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'
curl -X GET
   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'

Response Example

<?xml version="1.0"?>
<LinkCollection xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <Links>
        <Link 
            title="Primitive: [2017-04-06-&gt;2017-05-05]" 
            href="/Employer/ER001/Employee/EE001/PayInstruction/BASIC001" 
            rel="PrimitivePayInstruction" 
            />
        <Link 
            title="Primitive: [2017-04-06-&gt;2017-05-05]" 
            href="/Employer/ER001/Employee/EE001/PayInstruction/BASIC002" 
            rel="PrimitivePayInstruction" 
            />
    </Links>
</LinkCollection>
{
    "LinkCollection": {
        "Links": {
            "Link": [
                {
                    "@title": "Primitive: [2017-04-06->2017-05-05]",
                    "@href": "/Employer/ER001/Employee/EE001/PayInstruction/BASIC001",
                    "@rel": "PrimitivePayInstruction"
                },
                {
                    "@title": "Primitive: [2017-04-06->2017-05-05]",
                    "@href": "/Employer/ER001/Employee/EE001/PayInstruction/BASIC002",
                    "@rel": "PrimitivePayInstruction"
                }
            ]
        }
    }
}

[POST] a new Pay Instruction

This example demonstrates creating a new pay instruction using a [POST].

When performing a [POST] the API will generate default resource location unique keys.
Default primitive pay instruction unique key pattern is the payment code name suffixed with an incrementing number.

For example, a primitive pay instruction with the BASIC payment code has the pattern:

  • BASIC001
  • BASIC002
  • etc...
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"?>
<PrimitivePayInstruction xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <StartDate>2017-04-06</StartDate>
    <EndDate>2017-05-05</EndDate>
    <Description>Pay slip description</Description>
    <Code>BASIC</Code>
    <Value>150.0000</Value>
</PrimitivePayInstruction>'
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 '{
    "PrimitivePayInstruction": {
        "StartDate": "2017-04-06",
        "EndDate": "2017-05-05",
        "Description": "Pay slip description",
        "Code": "BASIC",
        "Value": "150.0000"
    }
}'

Response Example

The [POST] response is a link to the newly generated resource.

<?xml version="1.0"?>
<Link 
    xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    title="Primitive: [2017-04-06-&gt;2017-05-05]" 
    href="/Employer/ER001/Employee/EE001/PayInstruction/BASIC004" 
    rel="PrimitivePayInstruction" 
/>
{
    "Link": {
        "@title": "Primitive: [2017-04-06->2017-05-05]",
        "@href": "/Employer/ER001/Employee/EE001/PayInstruction/BASIC003",
        "@rel": "PrimitivePayInstruction"
    }
}

[PUT] a Pay Instruction

This example demonstrates creating a new pay instruction using [PUT]. You can use [PUT] to create new and updated existing objects.

When performing a [PUT] you specify the resource location unique key. This allows you to use your own resource managment naming conventions.
Example:

  • /Employer/ER001/Employee/EE001/PayInstruction/MyKey
  • /Employer/ER001/Employee/EE001/PayInstruction/AnotherKey
curl -X PUT
   https://api.test.payrun.io/Employer/ER001/Employee/EE001/PayInstruction/BASIC001
   -H 'Content-type: application/xml'
   -H 'Accept: application/xml'
   -H 'Api-Version: default'
   -H 'Authorization: {OAuthHeader}'
   -H 'Cache-Control: no-cache'
curl -X PUT
   https://api.test.payrun.io/Employer/ER001/Employee/EE001/PayInstruction/BASIC001
   -H 'Content-type: application/json'
   -H 'Accept: application/json'
   -H 'Api-Version: default'
   -H 'Authorization: {OAuthHeader}'
   -H 'Cache-Control: no-cache'

Response Example

The [PUT] response is the entire updated resource.

<?xml version="1.0"?>
<PrimitivePayInstruction xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <StartDate>2017-04-06</StartDate>
    <EndDate>2017-05-05</EndDate>
    <Description>Pay slip description</Description>
    <Code>BASIC</Code>
    <Value>150.0000</Value>
</PrimitivePayInstruction>
{
    "PrimitivePayInstruction": {
        "StartDate": "2017-04-06",
        "EndDate": "2017-05-05",
        "Description": "Pay slip description",
        "Code": "BASIC",
        "Value": "150.0000"
    }
}

[PATCH] a pay instruction

This example demonstrates updating an existing pay instruction using [PATCH].

[PATCH] allows updates by supplying only the changes.

curl -X PATCH
   https://api.test.payrun.io/Employer/ER001/Employee/ER001/PayInstruction/BASIC001
   -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"?>
<PrimitivePayInstruction xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <EndDate>2017-06-05</EndDate>
    <Description>Pay slip description NEW</Description>
</PrimitivePayInstruction>'
curl -X PATCH
   https://api.test.payrun.io/Employer/ER001/Employee/ER001/PayInstruction/BASIC001
   -H 'Content-type: application/json'
   -H 'Accept: application/json'
   -H 'Api-Version: default'
   -H 'Authorization: {OAuthHeader}'
   -H 'Cache-Control: no-cache'
-d '{
    "PrimitivePayInstruction": {
        "EndDate": "2017-06-05",
        "Description": "Pay slip description NEW"
    }
}'

Response Example

The [PATCH] response is the entire updated resource.

<?xml version="1.0"?>
<PrimitivePayInstruction xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <StartDate>2017-04-06</StartDate>
    <EndDate>2017-06-05</EndDate>
    <Description>Pay slip description NEW</Description>
    <Code>BASIC</Code>
    <Value>150.0000</Value>
</PrimitivePayInstruction>
{
    "PrimitivePayInstruction": {
        "StartDate": "2017-04-06",
        "EndDate": "2017-06-05",
        "Description": "Pay slip description NEW",
        "Code": "BASIC",
        "Value": "150.0000"
    }
}

[DELETE] an Pay Instruction

This example demonstrates deleting a pay instruction using the [DELETE] verb.

Note: You cannot delete pay instructions with dependent calculations.

curl -X DELETE
   https://api.test.payrun.io/Employer/ER001/Empployee/EE001/PayInstruction/BASIC001
   -H 'Content-type: application/xml'
   -H 'Accept: application/xml'
   -H 'Api-Version: default'
   -H 'Authorization: {OAuthHeader}'
   -H 'Cache-Control: no-cache'
curl -X DELETE
   https://api.test.payrun.io/Employer/ER001/Empployee/EE001/PayInstruction/BASIC001
   -H 'Content-type: application/json'
   -H 'Accept: application/json'
   -H 'Api-Version: default'
   -H 'Authorization: {OAuthHeader}'
   -H 'Cache-Control: no-cache'