Skip to main content

End-of-year arrangements Our offices and phone lines will close down over the holiday season, but our website, self-service 0800 number and myIR will remain available. Find out more

We've upgraded our voice system You may notice some changes the next time you call us. Find out more

Our SOAP web services operations contain requests and responses with common structure and fields. These are used across different schemas and tax types for reusable service design architecture.

XSD schema structure

The XSD schema structure for gateway services are:

  • Common.xsd
  • ServiceCommon.xsd
  • SpecificProduct.xsd

All schemas for different services import a common.xsd which has some data types specific to Inland Revenue.

This common.xsd will be used in other gateway services outside of the //namespace and must be kept up to date.

You can view and download the operations, schemas and data definitions for each service in our services catalogue.

Services catalogue

SOAP messages structure

All messages require a header containing the Action: parameter. The body must contain a structured XML payload.

Refer to the WSDL for the correct addresses. Refer to samples or the WSDL element wsdl:binding/soap12:operation/soapAction for the URL to use.

The online WSDLs for gateway services define an 'any' XML request and response structure, which then relies on a group of XSDs to define the data structure of those requests and responses.

Each request and response type will define a lower, 'wrapper' element. To simplify analysis and code generation, a development-oriented version of the WSDL and XSDs is provided with the build pack that has the 'any' elements replaced with relevant types.

Schema (XSD) validations

When you send structured XML through gateway this will be checked against our published XSDs.

This is partially a late binding validation, performed after an authentication review. The message structure of these services is a simple request/response.

The XML request will be checked for well-formed XML before the schema validation. Responses to these requests will be in XML format and defined by the same schemas as requests.

Any XML submissions in the body that do not match the provided schemas will not be accepted. Incorrect namespaces will also fail validation against the published schemas.

Any malformed XML will instantly be rejected before any schema validation.

<soap:Envelope xmlns:soap=""











             <RetrieveClientListRequest xmlns:xsi…

                <…XML payload…>







<s:Envelope xmlns:s=""  xmlns:a=






<a:Action s:mustUnderstand="1">




            <si:RetrieveClientListResponse >














Last updated: 28 Apr 2021
Jump back to the top of the page