Building a request in SOAP

SOAP Envelope

If you are using the WSDL to generate your client you won’t need to worry about this per-se, but it is handy to know what is happening underneath the hood.

The SOAP envelope provides a wrapper around each API request, defining the XML document as a SOAP message. The namespace definitions in this XML element are required. If they are missing, the server will generate a fault and discard the request.

The envelope consists of two sections; a header and a body. The header contains authentication information and is explained in the next document section. The body contains the fax request information when making each function call and is described in the function definitions throughout this document.

An example of a SOAP envelope for the UTBox Fax API is shown below with the header and body information omitted.


<soapenv:Envelope xmlns:soapenv="" xmlns:wsse="" xmlns:v2="">









Authorisation Headers

The UTBox Fax API uses WS-Security to authorise users on the platform. The WS-Security specification allows users to authenticate against SOAP services using a variety of different models.

When connecting to the UTBox Fax API you must use the UsernameToken security token format, which authenticates based on your UTBox username and password.

Applying these security headers will differ based on your API integration/connection method.

When using the WSDL to generate your SOAP client you may use a WS-Security library from your programming language to apply the headers to this SOAP service. Below is an example of applying these headers in Java using WSS4J interceptors:


Map<String,Object> outProps = new HashMap<String,Object>(); 

outProps.put(WSHandlerConstants.ACTION, WSHandlerConstants.USERNAME_TOKEN); 

outProps.put(WSHandlerConstants.USER, ”username”);

outProps.put(WSHandlerConstants.PW_CALLBACK_REF, new CallbackHandler() { 

       public void handle(Callback[] callbacks) throws IOException, UnsupportedCallbackException { 

              WSPasswordCallback pc = (WSPasswordCallback) callbacks[0]; 




outProps.put(WSHandlerConstants.PASSWORD_TYPE, WSConstants.PW_TEXT); 

factory.getOutInterceptors().add(new WSS4JOutInterceptor(outProps));


Alternatively if you are sending raw XML to the API you will need to apply the security headers to the request yourself following the example below:




        <wsse:Security soapenv:mustUnderstand="1">









[link to 

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request


Article is closed for comments.
Powered by Zendesk