RPN Web Service
MethodLookupRPNOperation
RPN Web Service > All Operations Resource Group : LookupRPNOperation (Method)
Request (LookupRPNRequest)

The request body is of type LookupRPNRequest.

PPSN Element To Element From Element Sequence RangeParameters Element EmploymentID Element EmployeePPSN Element Sequence EmployeeID Element DateLastUpdated Element TaxYear Element Version Element Name Element Sequence SoftwareUsed Element AgentTain Element EmployerRegistrationNumber Element Sequence LookupRPNRequest Element

Overview

LookupRPNRequest
Employer's Lookup RPN Request.
Sequence
EmployerRegistrationNumber employerReg Simple Type
Employer's PAYE Registration Number.
AgentTain optional agentTAIN Simple Type
Tax Advisor Identification Number. Required if RPN is queried by agent on behalf of employer.
SoftwareUsed SoftwareUsed Complex Type
References to third party software used to lookup RPN.
Sequence
Name NonEmptyString Simple Type
Name of the software used.
Version NonEmptyString Simple Type
Version of the software used.
TaxYear dateYear Simple Type
The tax year to which the RPN lookup relates (YYYY).
DateLastUpdated optional xs:date
Parameter to lookup for RPN updated on or since a given date.
EmployeeID 0..∞ EmployeeID Complex Type
Elements required to lookup RPN for an employee.
Sequence
EmployeePPSN EmployeePPSN Simple Type
Data Item Ref: 108. Employee's PPS Number. Used to identify the employee to which the RPN relates.
EmploymentID optional employmentID Simple Type
Data Item Ref: 110. Employee's Employment ID. Unique identifier for each distinct employment for an employee. If the RPN is being triggered as a result of the employee setting up the employment via Jobs and Pension or contacting Revenue, this field will not be populated.
RangeParameters optional RangeParameters Complex Type
The range of RPN to be retrieved.
Sequence
From xs:unsignedInt
Start index of range lookup.
To xs:unsignedInt
End index of range lookup.
PPSN 0..∞ defaultString Simple Type
List of PPSNs for search
200 Response (LookupRPNResponse)

The response body is of type LookupRPNResponse.

Description Element Path Element Code Element Sequence ValidationError Element EmploymentID Element EmployeePPSN Element Sequence NoRPN Element PRSIClass Element PRSIExempt Element LPTToDeduct Element USCDeductedToDate Element PayForUSCToDate Element YearlyUSCRateCutOff Element USCRatePercent Element Index Element Sequence USCRate Element USCStatus Element IncomeTaxDeductedToDate Element PayForIncomeTaxToDate Element YearlyRateCutOff Element TaxRatePercent Element Index Element Sequence TaxRate Element YearlyTaxCredits Element StatePensionCont Element ExclusionOrder Element IncomeTaxCalculationBasis Element EmploymentCessationDate Element EndDate Element EffectiveDate Element PreviousEmployeePPSN Element FamilyName Element FirstName Element Sequence Name Element EmployerReference Element RPNIssueDate Element EmploymentID Element EmployeePPSN Element Sequence EmployeeID Element RPNNumber Element Sequence RPN Element DateTimeEffective Element TotalRPNCount Element TaxYear Element AgentTain Element EmployerRegistrationNumber Element EmployerName Element Sequence LookupRPNResponse Element

Overview

LookupRPNResponse
Employer's Lookup RPN Response. Will either return RPN detail or details of validation errors.
Sequence
EmployerName defaultString Simple Type
Data Item Ref: N/A. The Official Name of the employer.
EmployerRegistrationNumber employerReg Simple Type
Data Item Ref: N/A. Employer's PAYE Registration Number.
AgentTain optional agentTAIN Simple Type
Data Item Ref: N/A. Tax Advisor Identification Number. Required if RPN queried by agent on behalf of employer.
TaxYear dateYear Simple Type
Data Item Ref: N/A. The tax year to which the RPN lookup relates (YYYY).
TotalRPNCount xs:unsignedInt
Data Item Ref: N/A. The total number of RPN that are associated with the RPN request submitted.
DateTimeEffective xs:dateTime
Data Item Ref: 105. The date and time at which the RPN returned is correct/was issued (YYYY-MM-DDThh:mm:ss.sss±hh:mm).
RPN 0..∞ RPN Complex Type
Data Item Ref: N/A. List of RPN that make up a valid lookup RPN response.
Sequence
RPNNumber rpnNumber Simple Type
Data Item Ref: 104. Reference number of the RPN for this employment for the employee.
EmployeeID EmployeeID Complex Type
Employee's PPS Number and Employment ID (if available).
Sequence
EmployeePPSN EmployeePPSN Simple Type
Data Item Ref: 108. Employee's PPS Number. Used to identify the employee to which the RPN relates.
EmploymentID optional employmentID Simple Type
Data Item Ref: 110. Employee's Employment ID. Unique identifier for each distinct employment for an employee. If the RPN is being triggered as a result of the employee setting up the employment via Jobs and Pension or contacting Revenue, this field will not be populated.
RPNIssueDate xs:date
Data Item Ref: 105. The date the RPN was issued (YYYY-MM-DD).
EmployerReference optional employerReference Simple Type
Data Item Ref: 111. Employee's internal staff identifier/reference.
Name Name Complex Type
The employee name.
Sequence
FirstName defaultString Simple Type
Data Item Ref: 106.The first name of the employee.
FamilyName defaultString Simple Type
Data Item Ref: 107 The surname/family name of the employee.
PreviousEmployeePPSN optional EmployeePPSN Simple Type
Data Item Ref: 109. Conditionally Returned. Used to identify employee's previous PPS number if available e.g. PPS number with 'W' suffix.
EffectiveDate xs:date
Data Item Ref: 114. January 1st if cumulative basis applies. Date the RPN issued if Week 1 basis applies. The date can be in the future (YYYY-MM-DD).
EndDate xs:date
Data Item Ref: 115. Last date on which the RPN specified will apply. After this date a new RPN should be requested.
EmploymentCessationDate optional xs:date
Data Item Ref: 136. Conditionally returned if present for the employment. Employment Cessation Date
IncomeTaxCalculationBasis IncomeTaxCalculationBasis Simple Type
Data Item Ref: 112. PAYE calculation basis used in the submission. Options allowed are "CUMULATIVE", "WEEK_1" and "EMERGENCY".
ExclusionOrder optional xs:boolean
Data Item Ref: 113. Indicates if there is an exclusion order on file for the employee. Set to “true” if an exclusion order is on file for the employee.
StatePensionCont optional xs:boolean
Data Item Ref: 137. True for an employee drawing down their state pension contributory. Default from 2025 onwards is false.
YearlyTaxCredits defaultDecimal Simple Type
Data Item Ref: 118. Net Tax Credits. Amount of tax credits available to the employee for the year the RPN relates to. Amount of tax credits available for use in the PAYE calculation.
TaxRate 1..∞ TaxRate Complex Type
Details of Tax Rates and Rate Cut Offs
Sequence
Index xs:unsignedShort
Data Item Ref: N/A. Index of the tax rate. For example, Index of 1 would refer to tax rate 1.
TaxRatePercent defaultDecimal Simple Type
Data Item Ref: 119, 121. Tax rate percentage to be applied.
YearlyRateCutOff optional defaultDecimal Simple Type
Data Item Ref: 120. Total allocated to the specified Rate Cut Off. No cut off for highest band.
PayForIncomeTaxToDate defaultDecimal Simple Type
Data Item Ref: 116. Total Pay for Income Tax to Date. This will include total income liable to Income Tax to date – including previous employment income. In the case of recommencements, this includes previous pay from that employer in the same tax year.
IncomeTaxDeductedToDate defaultDecimal Simple Type
Data Item Ref: 117. Total Income Tax Deducted to Date. Total amount of employee’s Income Tax deducted to date. In the case of recommencements, this includes previous tax from that employer in the same tax year.
USCStatus uscStatus Simple Type
Data Item Ref: 124. USC Status. Allowed values are Ordinary and Exempt.
USCRate 0..∞ USCRate Complex Type
Details of USC Rates.
Sequence
Index xs:unsignedShort
Data Item Ref: N/A. Index of the rate. For example, Index of 1 would refer to USC Tax Rate 1.
USCRatePercent defaultDecimal Simple Type
Data Item Ref: 125, 127, 129, 131. USC Rate percentage to be applied.
YearlyUSCRateCutOff optional defaultDecimal Simple Type
Data Item Ref: 126, 128, 130, 132. Total allocated to the specified USC Cut Off.
PayForUSCToDate defaultDecimal Simple Type
Data Item Ref: 133. Total Previous Pay subject to USC to Date. This will include total income liable to USC to date – including previous employment income and any additional declared income liable to USC e.g. Rental Income.
USCDeductedToDate defaultDecimal Simple Type
Data Item Ref: 134. Total Previous USC Paid to Date. Taking into account any USC refunded through any unemployment repayment claim(s).
LPTToDeduct optional defaultDecimal Simple Type
Data Item Ref: 135. LPT to be Deducted. Amount of LPT to be deducted through payroll.
PRSIExempt optional xs:boolean
Data Item Ref: 122. True if employee is exempt from paying PRSI in Ireland. This field is only included if the employee is exempt from paying PRSI.
PRSIClass optional prsiClass Simple Type
Data Item Ref: 123. PRSI Class and Subclass that the employee should be updated to. This will appear only where DSP updates the class or where DSP knows the individual is on the wrong class. i.e. where a review has been carried out by DSP.
NoRPN 0..∞ EmployeeID Complex Type
Data Item Ref: N/A. EmployeePPSNs and EmploymentIDs of employees who do not currently have an RPN associated with the employer. New RPN need to be requested for these employees using the NewRPNRequest service.
Sequence
EmployeePPSN EmployeePPSN Simple Type
Data Item Ref: 108. Employee's PPS Number. Used to identify the employee to which the RPN relates.
EmploymentID optional employmentID Simple Type
Data Item Ref: 110. Employee's Employment ID. Unique identifier for each distinct employment for an employee. If the RPN is being triggered as a result of the employee setting up the employment via Jobs and Pension or contacting Revenue, this field will not be populated.
ValidationError 0..∞ Error Complex Type
Data Item Ref: N/A. List of Validation errors (if any) on the LookupRPNRequest.
Sequence
Code errorCode Simple Type
Technical Error Code - to be used for mapping to error messages.
Path optional errorPath Simple Type
Path to error in schema, if available.
Description errorDescription Simple Type
Description of error - to be used for support.
Example
<?xml version="1.0" encoding="UTF-8"?>
<!--Document History:
======== Version 0.9 ====================================
i. Document Created 30/06/2017
======== Version 0.10 ====================================
ii. Document updated on 07/09/2017: 
        Revenue Payroll Instruction changed to Revenue Payroll Notification and RPI changed to RPN
======== Version 1.0 Milestone 1 ====================================
iii. Document updated on 17/11/2017: 
        Renamed the element: "employeePPSN" to "EmployeePPSN"
======== Version 1.0 Milestone 2 ====================================
iv. Document updated on 09/02/2018:
        Dates re-formatted
======== Version 1.0 Release Candidate 2 ===========
v. Document updated on 24/05/2018
     Updated ENUM Values to reflect schematic changes
-->
<rat:LookupRPNRequest xmlns:rat="http://www.ros.ie/schemas/paye-employers/v1/rpn/" xmlns="http://www.ros.ie/schemas/paye-employers/v1/rpn/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.ros.ie/schemas/paye-employers/v1/rpn/rpn-schema-pit3.xsd">
    <rat:EmployerRegistrationNumber>3980609P</rat:EmployerRegistrationNumber>
    <rat:SoftwareUsed>
        <rat:Name>The Software</rat:Name>
        <rat:Version>Version 10.0</rat:Version>
    </rat:SoftwareUsed>
    <rat:TaxYear>2019</rat:TaxYear>
    <rat:DateLastUpdated>2019-01-10</rat:DateLastUpdated>
    <rat:EmployeeID>
        <rat:EmployeePPSN>00000008P</rat:EmployeePPSN>
        <rat:EmploymentID>1</rat:EmploymentID>
    </rat:EmployeeID>
</rat:LookupRPNRequest>

<?xml version="1.0" encoding="UTF-8"?>
<!--Document History:
======== Version 0.9 ====================================
i. Document Created 30/06/2017
======== Version 0.10 ====================================
ii. Document updated on 07/09/2017: 
        Revenue Payroll Instruction changed to Revenue Payroll Notification and RPI changed to RPN
======== Version 1.0 Milestone 1 ====================================
iii. Document updated on 17/11/2017: 
        Renamed the element: "employeePPSN" to "EmployeePPSN"
        Renamed the element: "calculationBasis" to "IncomeTaxCalculationBasis"
        Renamed the element: "DateLastUpdated" to "RPNIssueDate"    
        Renamed the element: "YearlyUSCCutOff" to "YearlyUSCRateCutOff"    
        Renamed the element: "PayToDate" to "PayForIncomeTaxToDate"    
        Renamed the element: "TaxToDate" to "IncomeTaxDeductedToDate"
        Renamed the element: "USCPaidToDate" to "USCDeductedToDate"    
======== Version 1.0 Milestone 2 ====================================
iv. Document updated on 09/02/2018:
        Date/Time re-formatted

======== Version 1.0 Release Candidate 2 ===========
v. Document updated on 24/05/2018
     Updated ENUM Values to reflect schematic changes
-->
<rat:LookupRPNResponse xmlns:rat="http://www.ros.ie/schemas/paye-employers/v1/rpn/" xmlns="http://www.ros.ie/schemas/paye-employers/v1/rpn/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.ros.ie/schemas/paye-employers/v1/rpn/rpn-schema-pit3.xsd">
    <rat:EmployerName>Employer1</rat:EmployerName>
    <rat:EmployerRegistrationNumber>3980609P</rat:EmployerRegistrationNumber>
    <rat:TaxYear>2019</rat:TaxYear>
    <rat:TotalRPNCount>1</rat:TotalRPNCount>
    <rat:DateTimeEffective>2019-01-29T11:58:02.000+00:00</rat:DateTimeEffective>
    <rat:RPN>
        <rat:RPNNumber>5</rat:RPNNumber>
        <rat:EmployeeID>
            <rat:EmployeePPSN>00000008P</rat:EmployeePPSN>
            <rat:EmploymentID>1</rat:EmploymentID>
        </rat:EmployeeID>
        <rat:RPNIssueDate>2019-01-10</rat:RPNIssueDate>
        <rat:Name>
            <rat:FirstName>Ann</rat:FirstName>
            <rat:FamilyName>Doe</rat:FamilyName>
        </rat:Name>
        <rat:EffectiveDate>2019-01-01</rat:EffectiveDate>
        <rat:EndDate>2019-12-31</rat:EndDate>
        <rat:IncomeTaxCalculationBasis>CUMULATIVE</rat:IncomeTaxCalculationBasis>
        <rat:YearlyTaxCredits>3300.00</rat:YearlyTaxCredits>
        <rat:TaxRate>
            <rat:Index>1</rat:Index>
            <rat:TaxRatePercent>20</rat:TaxRatePercent>
            <rat:YearlyRateCutOff>33800.00</rat:YearlyRateCutOff>
        </rat:TaxRate>
        <rat:TaxRate>
            <rat:Index>2</rat:Index>
            <rat:TaxRatePercent>40</rat:TaxRatePercent>
        </rat:TaxRate>
        <rat:PayForIncomeTaxToDate>1230.00</rat:PayForIncomeTaxToDate>
        <rat:IncomeTaxDeductedToDate>0.00</rat:IncomeTaxDeductedToDate>
        <rat:USCStatus>ORDINARY</rat:USCStatus>
        <rat:USCRate>
            <rat:Index>1</rat:Index>
            <rat:USCRatePercent>.5</rat:USCRatePercent>
            <rat:YearlyUSCRateCutOff>12012.00</rat:YearlyUSCRateCutOff>
        </rat:USCRate>
        <rat:USCRate>
            <rat:Index>2</rat:Index>
            <rat:USCRatePercent>2.5</rat:USCRatePercent>
            <rat:YearlyUSCRateCutOff>18772.00</rat:YearlyUSCRateCutOff>
        </rat:USCRate>
        <rat:USCRate>
            <rat:Index>3</rat:Index>
            <rat:USCRatePercent>5</rat:USCRatePercent>
            <rat:YearlyUSCRateCutOff>70044.00</rat:YearlyUSCRateCutOff>
        </rat:USCRate>
        <rat:USCRate>
            <rat:Index>4</rat:Index>
            <rat:USCRatePercent>8</rat:USCRatePercent>
        </rat:USCRate>
        <rat:PayForUSCToDate>1230.00</rat:PayForUSCToDate>
        <rat:USCDeductedToDate>12.28</rat:USCDeductedToDate>
        <rat:LPTToDeduct>191.00</rat:LPTToDeduct>
    </rat:RPN>
</rat:LookupRPNResponse>
See Also
All Operations Resource Group | RPN Web Service

Please register for our PIT Support Help Desk for the following: