Revenue interface
Lookup and inbox
Reading back what Revenue holds. Two different calls with two different purposes, and one undocumented constraint that will cost you an afternoon.
On this page
LookupRctRequest
Retrieves contracts or payment notifications Revenue holds for you. Operation header FormRct/File, SOAPAction …/LookupOperation.
How to read these
- required
- The schema demands it. Omitting it fails validation.
- required in practice
- The schema says it is optional and Revenue rejects the request without it. Learned the hard way, against PIT3.
- optional
- Genuinely optional. Send it when you have it.
- never send
- The schema permits sending it and you must not. These are response-only fields, and populating one asserts something you have no authority to assert.
Fields
rct:RctTypeCONTRACT | PAYMENT_NOTIFICATION | RETURNrequiredWhat you are looking for. Upper case with underscores — Contract is not a member of the enumeration and is rejected.
rct:PrincipalRegistrationNumberstringrequiredYour RCT registration. Leading zero dropped, as everywhere else.
rct:BeginDateros:dateoptionalDD/MM/YYYY. Narrows the search by date.
rct:EndDateros:dateoptionalrct:ContractIdintegeroptionalFetch one specific contract.
rct:ExternalIdstringoptionalFind a record by the reference you supplied when you filed it.
The inbox — DocumentSearch
Lists the documents in your ROS inbox. Operation header Inbox/List, SOAPAction …/LookupOperation. A different namespace from everything else: http://www.ros.ie/schemas/inbox/.
Attributes, not child elements
DocumentSearch is an empty element whose search terms are attributes. Sending children produces a schema rejection naming the element and not the reason.
<DocumentSearch xmlns="…/inbox/" taxtype="RCT"/>
Attributes
taxtypestringoptionalTax head, e.g. RCT.
doctypestringoptionalDocument type.
fromros:dateoptionalDD/MM/YYYY. Documents issued on or after this date.
fromtimestringoptionalTime component, alongside a date.
The one-attribute rule
All four attributes are use="optional" in the XSD, with nothing indicating they are mutually exclusive. They are. Exactly one is accepted — zero is refused and two are refused.
| Sent | Result |
|---|---|
| no attributes | 500 — The input data was invalid |
taxtype="RCT" | 200 — 23 documents |
from="06/07/2026" | 200 — 23 documents |
| taxtype + from, either order | 500 |
| taxtype + doctype | 500 |
Measured against PIT3. Because nothing in the schema hints at it, Brickie models the search term as a single tagged value rather than an object with optional fields — the constraint is made unrepresentable rather than validated at runtime.
Do not build on Inbox/Document/Retrieve
It refuses RCT doctypes outright. The inbox is a receipt, not a document source: it tells you a filing exists and gives you its prn. That is all it is good for here.
What the inbox returns
| Field | Meaning |
|---|---|
prn | The document reference. Matches the AcknowledgementNumber from the submission that created it — this is the join. |
doctype | What kind of document it is. |
taxType | The tax head. |
registration | The registration it belongs to. |
issued | DD/MM/YYYY, as Revenue sends it. |
Reconciling against your own records
The reason this call matters: filings are signed in the browser, so an application takes the client’s word for what Revenue returned. The inbox is the independent check.
Matching stored acknowledgement numbers against inbox prn values produces four outcomes:
| Outcome | Meaning |
|---|---|
| Confirmed | You have a filing and Revenue holds the matching document. |
| Missing | You believe you filed something Revenue has no document for. Treat the filing as not made. |
| Unexpected | Revenue holds a document you have no record of. Usually a filing made directly in ROS. |
| Unverifiable | A filing with no acknowledgement number to match on — normally a submission that failed before Revenue responded. |
A missing result on a payment notification means the deduction was never actually authorised. If the payment has already gone out, that is precisely the situation the 35% liability applies to.
The user-facing version of this is Checking against Revenue.