Manage Payroll Relationships

Payroll relationships group a person's employment assignment records based on the payroll statutory calculation and reporting requirements. When you hire an employee, the application automatically creates the payroll relationship details. You can use the Payroll REST API to manage information at the payroll relationship, payroll assignment records, and assigned payroll levels for an employee.

Using the payrollRelationships resource, you can manage the payroll information of an employee at the payroll relationship level. You can update the overtime period for employees either at their payroll relationship or assignment level. A time period at a lower level, such as assignment, overrides a time period at a higher level, such as payroll relationship.

This graphic shows the various REST resources available at the payroll relationship, payroll assignment, and assigned payroll levels.

Note:

You can use this resource to add Tax Reporting Unit to UK new hires. The TRU triggers the automatic creation of UK tax records for the employees. You can use the update TRU custom action to update the tax reporting unit for a payroll assignment.

Let's discuss these scenarios:

• Retrieve Payroll Relationship Details
• Retrieve Element Duration Dates

Retrieve Payroll Relationship Details

Let's say that John was terminated on 1-Mar-19 and the payroll manager wants to check if the application has processed the termination correctly. The payroll manager wants to view the worker's payroll relationship details as on 1-Mar-19.

To retrieve the payroll relationship details:

1. Perform a GET operation on the payrollRelationship resource and query the payroll record by using a finder parameter and the effective date of 2019-03-01.
2. Verify the payroll relationship details of the employee returned in the response.

Example URL

Use this resource URL format.

GET

Using assignment number in the finder:

/hcmRestApi/resources/11.13.18.05/payrollRelationships?finder=findByAssignmentNumberPersonNumber;AssignmentNumber=<Assignment Number>&effectiveDate=2019-03-01

Using person number in the finder:

hcmRestApi/resources/11.13.18.05/payrollRelationships?finder=findByAssignmentNumberPersonNumber;PersonNumber=<PersonNumber>&effectiveDate=2019-03-01

Example Response

Here's an example of the response body in JSON format.

{
         "PayrollRelationshipId": 300100026848715,
         "PayrollRelationshipNumber": "955160008176301",
         "StartDate": "2011-01-01",
         "EndDate": "4712-12-31",
         "PersonNumber": "955160008176301",
         "Country": "US",
         "PartyId": 300100026811994,
         "PartyNumber": "CDRM_69113",
         "EffectiveEndDate": "4712-12-31",
         "EffectiveStartDate": "2016-05-15",
         "OverridingPeriodId": 300100050037581
}

Retrieve Element Duration Dates

Element duration dates at the payroll relationship level control the start and end date of earnings and deductions assigned to the employee's payroll relationship. Examples of payroll relationship elements include tax and social insurance entries.

You can use the payrollRelationshipDates resource to retrieve these date values.

• First Standard Earnings Date
• Last Standard Earnings Date
• Last Standard Process Date
• Final Close Date

Here's a graphic that helps you understand the scenarios.

Let's say that the application has set the last standard earnings date on John's assignment record as 1-Mar-19, which is his termination date. The same date cascades up to the last standard earnings date at the payroll relationship level.

To retrieve the last standard earnings date:

1. Perform a GET operation on the payrollRelationshipDates resource by using the PayDateId.
2. Verify the standard earning date returned in the response.

Example URL

Use this resource URL format.

GET

/hcmRestApi/resources/11.13.18.05/payrollRelationships/{Id}/child/payrollRelationshipDates/{Id}

Example Response

Here's an example of the response body in JSON format.

{
    "PayDateId": 300100178285540,
    "DateValue": "2019-02-19",
    "ShortName": "LSED"
}