HowToCodePage

What SOAP is and how the envelope works

The XML messaging protocol behind enterprise web services, and the three parts every SOAP message is built from.

A protocol, not an architecture

SOAP (originally Simple Object Access Protocol) is a specification for exchanging structured XML messages over a transport, in practice almost always HTTP. It is deliberately strict: the message shape, the encoding and the error format are all defined, which is why banks, insurers, telecoms and government systems standardised on it.

  • SOAP 1.1 uses the namespace http://schemas.xmlsoap.org/soap/envelope/ and the SOAPAction HTTP header.
  • SOAP 1.2 uses http://www.w3.org/2003/05/soap-envelope and moves the action into the Content-Type parameter.
  • Security is standardised separately as WS-Security: signing, encryption and tokens travel inside the header.
  • The contract is published as a WSDL document, which is what makes code generation possible.
💡
SOAP is transport-independent by design — the same envelope can go over HTTP, SMTP or a message queue. That flexibility is why the format is heavier than a plain JSON request, and why you almost never hand-write the messages in a real integration.

Envelope, header, body

PartRequiredPurpose
EnvelopeYesThe root element; declares the SOAP version and namespaces
HeaderNoOut-of-band data: credentials, correlation ids, routing, WS-Security
BodyYesThe actual call or response payload
FaultNoAppears inside the body on failure, with a code, reason and details
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
               xmlns:q="urn:example:quotes">
  <soap:Header>
    <q:Auth>
      <q:Token>8f2c1a</q:Token>
    </q:Auth>
  </soap:Header>
  <soap:Body>
    <q:GetQuote>
      <q:symbol>AAPL</q:symbol>
    </q:GetQuote>
  </soap:Body>
</soap:Envelope>

Attributes on a header block control who has to understand it: soap:mustUnderstand="1" means the receiver must process it or fail the call, and soap:actor (1.1) or soap:role (1.2) names the node it is addressed to. A fault is never mixed with a normal response body — it replaces it.

FAQ

Is SOAP still used?
Yes, heavily, in regulated and long-lived enterprise integrations where a strict contract and standardised security matter. It is rarely chosen for new public APIs.
Can SOAP return JSON?
The specification is XML, but SOAP 1.2 allows other serialisations in principle. Practically, XML is what every mainstream SOAP stack emits and expects, so treat JSON as out of scope.

WSDL contracts and code generation Calling a SOAP service, and why REST usually wins

Last refreshed 2026-09-18.