Skip to main content

Budget 2024 | The Government has announced proposed changes to personal income tax, the independent earner tax credit, in-work tax credit, the minimum family tax credit and the interest rate charged for overseas based student loans. They have also provided more information on FamilyBoost. 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