Soap

Module Version Hex Docs License

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

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
})

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"}
#=> }

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

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 (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.