Revenue interface
How the Revenue interface works
Brickie files to the same ROS service you would use by hand. This section documents every call and every field, because Revenue publishes schemas but no readable field reference.
On this page
Who this is for
Developers, and accountants who want to know exactly what is being sent in their client’s name. If you are a builder using Brickie, you do not need any of this — the rest of the documentation covers what you actually do.
It is written down because the information is genuinely hard to come by. Revenue publishes XSDs, and the XSDs are not a reliable guide to what a request must contain. Much of what follows was established by submitting to Revenue’s test environment and reading the rejections.
The endpoint
| Environment | Host | Use |
|---|---|---|
| PIT3 | softwaretest.ros.ie/service | Testing. Filings here are not real. |
| Production | ros.ie/service | Real filings against real taxpayer accounts. |
Two things that look like details and are not
The path is /service, not /webservice/service. And softwaretestnextversion is PIT4, not PIT3 — never derive one environment from another by string manipulation.
Revenue’s current Customs & Excise integration guide describes a different, modern SOAP profile. RCT does not use it. Following that guide will send you a long way in the wrong direction.
How requests are authenticated
Every request is a SOAP envelope signed with your ROS digital certificate, using a WS-Security profile that dates from about 2002.
| Canonicalisation | Exclusive C14N |
| Signature algorithm | RSA-SHA1 only. SHA-256 and SHA-512 are rejected. |
| Digest | SHA-1 |
| Signed elements | The Operation header and the Body. Nothing else. |
| Timestamp | None. This profile has no wsu:Timestamp. |
| SOAPAction header | Required, and must be quoted. An empty one is refused. |
RSA-SHA1 is not an oversight to correct
Upgrading the algorithm breaks filing. The endpoint refuses SHA-256 during authentication and reports “An error occured during authentication” — Revenue’s spelling — which sounds like a certificate problem and is not.
In Brickie the signing happens in the browser, so the private key never reaches the server. See Your ROS certificate.
The operations
The endpoint dispatches on an Operation SOAP header inside the signed envelope, with a SOAPAction HTTP header alongside it.
| Request | Operation header | SOAPAction |
|---|---|---|
SubmitRctRequest — contracts | FormRct/File | …/SubmitOperation |
SubmitRctRequest — payment notifications | FormRct/File | …/SubmitOperation |
LookupRctRequest | FormRct/File | …/LookupOperation |
DocumentSearch — inbox | Inbox/List | …/LookupOperation |
Contracts and payment notifications share one request element. What distinguishes them is which child you put inside it — rct:Contract or rct:PaymentNotification.
Batching, and why it is all or nothing
One SubmitRctRequest carries up to 100 records.
A rejected batch processes none of it
If one record in a batch is rejected, nothing in that batch is processed. There is no partial success in which the valid records go through and the bad one comes back.
This was verified against PIT3 and contradicts the assumption most integrations start with. The practical consequence: validate locally before submitting, because a round trip that rejects fifteen notifications for one apostrophe tells you very little about which one.
Nothing in a rejected batch has any effect at Revenue, so there is nothing to unwind. The records simply were not filed.
Send an ExternalId — your own reference — and Revenue echoes it back. It is how a record in a hundred-record submission is tied to the row it came from.
What you can put in a text field
Revenue enforces a restricted character set on free-text fields, after schema validation. It is not in the XSD. Verbatim from the rejection:
a-z A-Z 0-9 Á É Í Ó Ú á é í ó ú - / & . ( ) ' * and space
Note what is absent, in rough order of how easily it is typed:
- The em-dash and en-dash. Word and most editors insert these automatically. An em-dash in a description is what produced this rejection for us.
- The comma, colon and plus sign. All of which look entirely ordinary in a description of work.
- Every accented character except the five Irish vowels. A Polish or Lithuanian subcontractor’s name will be rejected as spelled. That is Revenue’s constraint, not a choice Brickie makes, and there is no good answer to it.
Dates and numbers
| Type | Format | Trap |
|---|---|---|
ros:date | DD/MM/YYYY | Not xsd:date. An ISO value like 2026-09-01 fails validation, and the rejection names the field without saying the format is wrong. |
| County | Integer | A numeric county code, not a county name. |
| Contract value | Integer | Whole euro. Not cent, and not a decimal. |
| Payment amounts | Decimal, 2 places | The only place money is not an integer. Sent as e.g. 4250.00. |
| Yes/no indicators | 1 | One for yes, zero for no. Not true/false, and not 1/2. A value of 2 is refused. |
| Principal registration | Text | Drops its leading zero. 02831260F must be sent as 2831260F, even though Revenue echoes it back with the zero. |