# Working with SOAP APIs
### Introduction
Some systems still use SOAP APIs (**S**imple **O**bject **A**ccess **P**rotocol) instead of REST APIs. \
SOAP is a messaging protocol that uses XML in order to exchange information between computers.
At Locoia, you can integrate SOAP APIs by configuring Connector Actions with SOAP-specific settings.
***
### Creating the SOAP Request Body
Define a valid SOAP XML payload manually in the Request Body Template using Jinja for dynamic fields.
{% code title="Example Request Body Template" %}
```xml
{{ id }}
```
{% endcode %}
✅ Ensure correct use of namespaces (xmlns) as per the API specification.
***
## Endpoint Details
### Reading Details from the WSDL
The WSDL (Web Services Description Language) file defines:
* Available operations (methods)
* Expected input and output formats
* Required namespaces and endpoints
Use the WSDL to:
* Identify operation names
* Understand the expected structure of requests
* Verify service URLs
📚 In SoapUI, importing the WSDL auto-generates method templates.
***
### Reading Documentation from the XSD
The XSD (XML Schema Definition) describes:
* Data types (string, int, boolean)
* Field validations (e.g., minLength, maxLength)
* Mandatory and optional fields
XSDs are often referenced inside WSDLs and explain how the body structure should be composed.
***
## Testing Requests
### Testing with SoapUI
To read out all the endpoint details of a SOAP API, you can use a tool such as [SoapUI](https://www.soapui.org/downloads/soapui/) (download **SoapUI Open Source**).
1. Create a new SOAP project
1. Make sure that **Create Requests** is turned on. This way the tool will create sample requests for you with the correct structure, where you simply have to fill in the parameters.
New SOAP Project dialog
2. **Import the WSDL**
Load the WSDL file provided by the API. SoapUI will parse the available methods and message formats.
3. **SoapUI generates available operations**
All available operations (endpoints) will appear automatically after importing the WSDL
4. **Customize and send requests**
* Edit the generated XML request templates.
* Insert the correct field values.
* Set the SOAPAction manually if needed.
5. **Review the full XML responses and faults**
* Inspect the returned XML.
* Handle successful responses or SOAP faults properly.
Why use SoapUI?
✅ WSDL parsing
✅ Visual method explorer
✅ Automated request templates
***
### Testing with Postman
To test the request in Postman, you can follow this article from Postman itself: [Send SOAP requests](https://learning.postman.com/docs/sending-requests/soap/making-soap-requests/)
* Set method to POST
* Set Headers:
* Content-Type: `text/xml`
* SOAPAction (if needed)
Request with Headers in Postman
* Paste the XML manually into the raw body
* Send a request and view the response
{% hint style="warning" %}
The `SOAPAction` value always needs to have quotation marks (`""`) around it.
{% endhint %}
{% hint style="info" %}
Postman does not support WSDL parsing.
{% endhint %}
***
### Testing directly inside Locoia
In case the SOAP web service requires the `text/xml` Content-Type, add it as a header to the Connector itself:
```json
{
"content_type": "text/xml"
}
```
In the actions, you always need to select `post` as the method and add the `SOAPAction` method name in the header.
The XML can be written directly into the request body template.
Create Connector Action dialog
***
## Parsing SOAP Responses
SOAP responses are XML. Extract values using:
* Jinja templating (e.g., regex\_replace)
* Additional Flow steps for XML parsing if needed
Example Jinja Extraction:
```django
{{ body | regex_replace('(.*?)', '\\1') }}
```
***
## Special Notes
* Strict namespace usage is mandatory.
* Handle SOAP faults properly (\ elements).
* Authentication varies depending on API (Basic Auth, API Key, OAuth).
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.locoia.com/connectors/building-connectors/working-with-soap-apis.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
