Soap
A SOAP client for Elixir. It reads a WSDL, checks your params against its schema, and gives you back plain Elixir data shaped by that schema.
{:ok, client} = Soap.load("http://www.dneonline.com/calculator.asmx?WSDL")
Soap.operations(client)
#=> ["Add", "Subtract", "Multiply", "Divide"]
Soap.call(client, "Add", %{intA: 2, intB: 3})
#=> {:ok, %{"AddResponse" => %{"AddResult" => 5}}}
Coming from 1.x? See the migration guide.
Installation
def deps do
[
{:soap, "~> 2.0"}
]
end
There's nothing to configure. Options go on the client or the call, so one application can talk to any number of services, in either SOAP version.
Loading a service
{:ok, client} = Soap.load("priv/service.wsdl")
{:ok, client} = Soap.load("https://example.com/service?wsdl", timeout: 10_000)
{:ok, client} = Soap.from_string(wsdl_xml)
Options you pass here become defaults for every call. A call's own options win.
Imports
A WSDL is often loaded from somewhere you don't control, so imports are limited by default.
| Reference in a document | From a local file | From a URL |
|---|---|---|
| Relative path | Read | Fetched from the same host |
http or https URL |
Skipped | Fetched from the same host only |
Absolute path, file:, others |
Skipped | Skipped |
allow_imports_from: ["schemas.example.com"]orallow_imports_from: :allallows more hosts.import_root: "priv/wsdl"keeps local imports inside a directory. Without it, a local WSDL can import from parent directories.- With
import_root, imports through symlinks below that directory are skipped. - HTTP redirects follow the same host restrictions as imports. Relative imports resolve against the final URL.
client.service.unresolved_importslists what was skipped, and why.- An import that's allowed but can't be read is an error.
ignore_failed_imports: trueaccepts a partial model instead.
Calling
Soap.call(client, "CreateOrder", %{
"Customer" => %{"Name" => "Ann", "Phones" => ["555-1", "555-2"]},
"Total" => %{"@currency" => "EUR", "#text" => Decimal.new("10.50")},
"Date" => ~D[2026-11-04],
"Note" => nil
})
- Params can be a map, a keyword list, or a list of
{name, value}or{name, attributes, value}tuples. Names can be atoms or strings. - Elements go out in the order and namespaces the schema requires.
- A list repeats the element.
"@name"is an attribute, and"#text"is an element's text next to its attributes.- Missing,
nil, empty and[]values follow the table below. - Values go out in the form their type needs, including
Date,DateTimeandDecimal. Base64 and hex fields take raw bytes.
Missing and empty values
| Param | Element sent |
|---|---|
| Key left out | None |
nil |
xsi:nil="true" if the schema says nillable, otherwise none |
"" |
An empty element |
[] |
None if the element can repeat, otherwise an empty element |
In results, an element that's absent has no key, even one that can repeat. xsi:nil is nil, an empty simple element is "", and an empty complex one is %{}.
Validation
A value that can't fit its type, or an element the schema doesn't allow, returns an error and nothing gets sent:
Soap.call(client, "Add", %{intA: "two"})
#=> {:error, %Soap.Error{reason: {:invalid_param, "Add/intA", "\"two\" isn't a valid int"}}}
Missing required elements are allowed, because servers often accept less than their WSDL says. validate: false turns validation off.
Options
| Option | Meaning |
|---|---|
:endpoint |
Send here instead of the address in the WSDL |
:port |
The wsdl:port to use, by name, when several offer the operation. It picks the binding and the address. By default it's the first one in the WSDL |
:version |
"1.1" or "1.2", when the WSDL offers both |
:input |
The input's name, to choose between overloaded operations |
:soap_headers |
SOAP headers, in the same forms as params |
:http_headers |
Extra HTTP headers. One with a standard header's name replaces it |
:wsse |
WS-Security credentials |
:mtom |
Send every base64 field as an attachment |
:attachments |
Extra %Soap.Attachment{} parts |
:validate |
Check params against the schema. Defaults to true |
:timeout, :connect_timeout |
In milliseconds |
:follow_redirects |
Follow redirects on calls. Defaults to false |
:max_reply_size |
The largest reply to accept, in bytes, also once decompressed. Defaults to 100 MB. :infinity turns it off |
:http, :http_opts |
The HTTP adapter and its options |
A call's options replace the client's, except :http_headers, :soap_headers, :http_opts and :telemetry_metadata, which are merged by name or key, with the call winning. A header set to nil is removed, so a call can drop one the client sets:
{:ok, client} = Soap.load(url, http_headers: [{"Authorization", "Bearer t"}])
Soap.call(client, "Ping", %{}, http_headers: [{"X-Request-Id", "42"}]) # sends both headers
Soap.call(client, "Ping", %{}, http_headers: [{"authorization", nil}]) # sends no Authorization
Results
{:ok, %{"GetOrderResponse" => order}} = Soap.call(client, "GetOrder", %{id: 7})
order
#=> %{
#=> "Id" => 7,
#=> "Paid" => true,
#=> "Created" => ~U[2026-11-04 10:00:00Z],
#=> "Lines" => [%{"Sku" => "A-1", "Quantity" => 2}],
#=> "Total" => %{"@currency" => "EUR", "#text" => "10.50"}
#=> }
- Keys are strings, so a reply can't create atoms. Prefixes are dropped, so a server changing its prefix changes nothing.
- An element that can repeat is always a list, even with one item.
- Values take their schema type. A value that doesn't parse stays a string.
xsd:decimalstays a string, so no precision is lost. CallDecimal.new/1if you want aDecimal.xsi:nilisnil.rpc/encodedlinks (multiRef,href) are followed, andsoapenc:Arraybecomes a list.
With no schema, as in Soap.decode_response(nil, nil, status, headers, body), a repeated element is a list, a single one isn't, and values are strings.
For the HTTP status, raw body, SOAP headers and attachments, use Soap.request/4. To see what would be sent, use Soap.build_request/4.
Errors
case Soap.call(client, "Pay", params) do
{:ok, result} -> result
{:error, %Soap.Fault{code: code, message: message}} -> {:rejected, code, message}
{:error, %Soap.Error{reason: {:transport, reason}}} -> {:unreachable, reason}
{:error, %Soap.Error{reason: reason}} -> {:failed, reason}
end
A Fault or error that came from a reply keeps its HTTP status, headers and body, for example to read Retry-After.
Invalid params, wrongly shaped options, broken replies and network failures return errors instead of raising or exiting. :http_opts are the exception: they go to the HTTP adapter unchecked, and Req raises on one it doesn't know. A SOAP Fault is reported the same way at any HTTP status, in either SOAP version. Soap.call!/4 raises these as exceptions instead.
WS-Security
token = Soap.WSSE.username_token("ann", "secret")
Soap.call(client, "GetOrders", %{}, wsse: token)
token = Soap.WSSE.username_token("ann", "secret", digest: true, timestamp: 300)
This supports UsernameToken with a plain password or a digest. Message signing and encryption aren't supported. Send plain passwords over HTTPS only.
Attachments
# MTOM: every base64 field goes as a binary part.
Soap.call(client, "Upload", %{"File" => bytes}, mtom: true)
# MTOM for one field, with a content type.
Soap.call(client, "Upload", %{"File" => %Soap.Attachment{data: bytes, content_type: "image/png"}})
# SOAP with Attachments: extra parts with no reference in the XML.
Soap.call(client, "Upload", %{}, attachments: [%Soap.Attachment{data: bytes}])
MTOM replies resolve into the result automatically. Other parts are in Soap.request/4's attachments.
Raw XML
Soap.call(client, "Send", %{"Document" => %Soap.Raw{xml: prebuilt_fragment}})
Soap.call(client, "Send", params, soap_headers: [%Soap.Raw{xml: custom_header}])
Raw XML goes out unchecked and unescaped, so never build it from untrusted input.
HTTP clients
Req is the default, and you can pass it options:
Soap.load(url, http_opts: [req: [connect_options: [proxy: {:http, "proxy", 3128, []}]]])
To use another client, implement Soap.HTTP and pass it as :http. For HTTPoison:
defmodule MyApp.SoapHTTP do
@behaviour Soap.HTTP
@impl true
def request(method, url, headers, body, opts) do
options = [
recv_timeout: opts[:timeout] || 5_000,
follow_redirect: opts[:follow_redirects] || false
]
case HTTPoison.request(method, url, IO.iodata_to_binary(body), headers, options) do
{:ok, %HTTPoison.Response{status_code: status, headers: headers, body: body}} ->
{:ok, %{status: status, headers: headers, body: body}}
{:error, %HTTPoison.Error{reason: reason}} ->
{:error, reason}
end
end
end
Soap.load(url, http: MyApp.SoapHTTP)
Generating a client
mix soap.gen priv/calculator.wsdl --module MyApp.Calculator
This writes a module with one documented, typed function per operation:
{:ok, client} = MyApp.Calculator.client()
MyApp.Calculator.add(client, %{"intA" => 2, "intB" => 3})
Testing your code
Soap.Test answers calls with no network:
{:ok, client} =
Soap.Test.client("priv/calculator.wsdl", fn request ->
assert request.operation == "Add"
assert request.params == %{"intA" => "2", "intB" => "3"}
Soap.Test.reply("AddResponse", %{"AddResult" => 5}, namespace: "http://tempuri.org/")
end)
assert {:ok, %{"AddResponse" => %{"AddResult" => 5}}} = Soap.call(client, "Add", %{intA: 2, intB: 3})
Handlers can also return Soap.Test.fault("soap:Server", "boom"), {status, body} or {:error, :timeout}.
Telemetry
Each call emits [:soap, :request, :start | :stop | :exception]. Metadata holds the operation, version, URL, status and outcome, with credentials removed. To log calls:
Soap.Telemetry.attach_default_logger(level: :info)
See Soap.Telemetry.
Compatibility
- SOAP 1.1 and 1.2.
- WSDL 1.1, in document/literal, rpc/literal and rpc/encoded. WSDL 2.0 returns a clear error.
- WSDLs split across files with
wsdl:import,xsd:importandxsd:include. - XML in UTF-8, UTF-16 and ISO-8859-1.
Replies containing a DOCTYPE are refused, so external entities and entity bombs can't apply.
A reply over :max_reply_size returns {:error, %Soap.Error{reason: :reply_too_large}}. The limit also covers what a compressed reply expands to.
Testing this library
The suite in test/conformance/ runs against 1,400 real-world WSDLs, recorded replies, PHP's and node-soap's test suites, a raw socket server that sends broken replies, public services, and real servers in Docker: Apache CXF, PHP SoapServer and node-soap. See test/corpus/README.md.
mix test
docker compose -f test/interop/docker-compose.yml up -d --build --wait
mix test --only interop
Copyright and License
Copyright (c) 2017 Petr Stepchenko
This work is free. You can redistribute it and/or modify it under the terms of the MIT License. See the LICENSE.md file for more details.