Review SOAP Envelopes to Retrieve Information

The SOAP envelope represents all of the elements included in a message. Use this SOAP envelope to review the information present in the message and use your preferred coding language to retrieve information from that envelope.

When reviewing SOAP envelopes, you see two different types of envelopes:

Request - the information passed from you to the API
Response - the information generated by the API after processing your request and returned to you

The SOAP Request Envelope

The example below represents a typical SOAP request envelope:

1<?xml version="1.0" encoding="UTF-8"?>
2<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
3  <soapenv:Header xmlns:wsa="http://www.w3.org/2005/08/addressing">
4    <wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" soapenv:mustUnderstand="1">
5      <wsse:UsernameToken xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" wsu:Id="UsernameToken-1">
6        <wsse:Username>XXXXX</wsse:Username>
7        <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">XXXXX</wsse:Password>
8      </wsse:UsernameToken>
9    </wsse:Security>
10    <wsa:To>https://YOUR_SUBDOMAIN.soap.marketingcloudapis.com/Service.asmx</wsa:To>
11    <wsa:MessageID>urn:uuid:a4362473-88fa-45ef-82af-0acb5efcd505</wsa:MessageID>
12    <wsa:Action>Update</wsa:Action>
13  </soapenv:Header>
14  <soapenv:Body>
15    <par:UpdateRequest xmlns:par="http://exacttarget.com/wsdl/partnerAPI" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
16      <par:Options>
17        <par:SaveOptions>
18          <par:SaveOption>
19            <par:PropertyName>*</par:PropertyName>
20            <par:SaveAction>UpdateAdd</par:SaveAction>
21          </par:SaveOption>
22        </par:SaveOptions>
23      </par:Options>
24      <par:Objects xsi:type="par:DataExtensionObject">
25        <par:Client>
26          <par:ID>12345</par:ID>
27        </par:Client>
28        <par:PartnerKey xsi:nil="true"/>
29        <par:ObjectID xsi:nil="true"/>
30        <par:CustomerKey>SampleCustomerKey</par:CustomerKey>
31        <par:Properties>
32          <par:Property>
33            <par:Name>Subscriber_Key</par:Name>
34            <par:Value>13175555555</par:Value>
35          </par:Property>
36          <par:Property>
37            <par:Name>List_ID</par:Name>
38            <par:Value>1234</par:Value>
39          </par:Property>
40          <par:Property>
41            <par:Name>Email_Address</par:Name>
42            <par:Value>acruz@example.com</par:Value>
43          </par:Property>
44        </par:Properties>
45      </par:Objects>
46    </par:UpdateRequest>
47  </soapenv:Body>
48</soapenv:Envelope>

The SOAP Response Envelope

The example below represents a typical SOAP response envelope.Use this envelope as the model for all calls in this technical article:

1<?xml version="1.0" encoding="utf-8"?>
2<soap:Envelope xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" xmlns:par="http://exacttarget.com/wsdl/partnerAPI">
3  <par:Results xsi:type="DataExtensionUpdateResult">
4    <par:StatusCode>OK</par:StatusCode>
5    <par:StatusMessage>Updated DataExtensionObject</par:StatusMessage>
6    <par:OrdinalID>0</par:OrdinalID>
7    <par:Object xsi:type="DataExtensionObject">
8      <par:Client>
9        <par:ID>12345</par:ID>
10      </par:Client>
11      <par:PartnerKey xsi:nil="true"/>
12      <par:ObjectID xsi:nil="true"/>
13      <par:CustomerKey>SampleCustomerKey</par:CustomerKey>
14      <par:Properties>
15        <par:Property>
16          <par:Name>Subscriber_Key</par:Name>
17          <par:Value>13175555555</par:Value>
18        </par:Property>
19        <par:Property>
20          <par:Name>List_ID</par:Name>
21          <par:Value>1234</par:Value>
22        </par:Property>
23        <par:Property>
24          <par:Name>Email_Address</par:Name>
25          <par:Value>acruz@example.com</par:Value>
26        </par:Property>
27      </par:Properties>
28    </par:Object>
29  </par:Results>
30  <par:RequestID>a5d36471-e636-478c-a29b-fd3571714602</par:RequestID>
31  <par:OverallStatus>OK</par:OverallStatus>
32</soap:Envelope>

The SOAP envelopes include a client ID value used to perform calls in sub-accounts, such as in an Enterprise 2.0 account. If you are performing the action in the same account you are logged into, you don’t need to include this value.

Error Message in SOAP Envelopes

In addition to retrieving information from SOAP envelopes, you can use them to get information about errors. The SOAP request below fails because no client ID is specified and the application couldn’t find the applicable triggered send because it was located in another account:

1<?xml version="1.0" encoding="utf-8"?>
2<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
3  <soapenv:Header xmlns:wsa="http://www.w3.org/2005/08/addressing">
4    <wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" soapenv:mustUnderstand="1">
5      <wsse:UsernameToken xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" wsu:Id="UsernameToken-1">
6        <wsse:Username>XXXXX</wsse:Username>
7        <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">XXXXX</wsse:Password>
8      </wsse:UsernameToken>
9    </wsse:Security>
10    <wsa:To>https://YOUR_SUBDOMAIN.soap.marketingcloudapis.com/Service.asmx</wsa:To>
11    <wsa:MessageID>urn:uuid:0805f203-3a1c-4c4d-907f-e1c290a16c47</wsa:MessageID>
12    <wsa:Action>Create</wsa:Action>
13  </soapenv:Header>
14  <soapenv:Body>
15    <par:CreateRequest xmlns:par="http://exacttarget.com/wsdl/partnerAPI" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
16      <par:Options/>
17      <par:Objects xsi:type="par:TriggeredSend">
18        <par:TriggeredSendDefinition>
19          <par:PartnerKey xsi:nil="true"/>
20          <par:ObjectID xsi:nil="true"/>
21          <par:CustomerKey>SampleCustomerKey</par:CustomerKey>
22        </par:TriggeredSendDefinition>
23        <par:Subscribers>
24          <par:EmailAddress>acruz@example.com</par:EmailAddress>
25          <par:Attributes>
26            <par:Name>FirstName</par:Name>
27            <par:Value>Angela</par:Value>
28          </par:Attributes>
29          <par:SubscriberKey>acruz@example.com</par:SubscriberKey>
30        </par:Subscribers>
31      </par:Objects>
32    </par:CreateRequest>
33  </soapenv:Body>
34</soapenv:Envelope>

The SOAP response envelope contains information about the error. In this case, the create request failed because no client ID was specified and the application couldn’t find the applicable triggered send (as it was located in another account):

1<?xml version="1.0" encoding="utf-8"?>
2<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
3  <soap:Header>
4    <wsa:Action>CreateResponse</wsa:Action>
5    <wsa:MessageID>urn:uuid:418acec2-1bb7-479c-9122-f47fb2c00417</wsa:MessageID>
6    <wsa:RelatesTo>urn:uuid:7019ac69-ba97-47af-8552-4476a8702c6a</wsa:RelatesTo>
7    <wsa:To>http://schemas.xmlsoap.org/ws/2004/08/addressing/role/anonymous</wsa:To>
8  </soap:Header>
9  <soap:Body>
10    <CreateResponse xmlns:par="http://exacttarget.com/wsdl/partnerAPI">
11      <par:Results xsi:type="TriggeredSendCreateResult">
12        <par:StatusCode>Error</par:StatusCode>
13        <par:StatusMessage>Invalid Customer Key</par:StatusMessage>
14        <par:OrdinalID>0</par:OrdinalID>
15        <par:ErrorCode>18002</par:ErrorCode>
16        <par:NewID>0</par:NewID>
17      </par:Results>
18      <par:RequestID>17a0f752-bcf1-4872-9dbc-ee3aa35e9d4e</par:RequestID>
19      <par:OverallStatus>Error</par:OverallStatus>
20    </CreateResponse>
21  </soap:Body>
22</soap:Envelope>

You can review the successful request envelope below:

1<?xml version="1.0" encoding="UTF-8"?>
2<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
3  <soapenv:Header xmlns:wsa="http://www.w3.org/2005/08/addressing">
4    <wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" soapenv:mustUnderstand="1">
5      <wsse:UsernameToken xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" wsu:Id="UsernameToken-1">
6        <wsse:Username>XXXXX</wsse:Username>
7        <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">XXXXX</wsse:Password>
8      </wsse:UsernameToken>
9    </wsse:Security>
10    <wsa:To>https://YOUR_SUBDOMAIN.soap.marketingcloudapis.com/Service.asmx</wsa:To>
11    <wsa:MessageID>urn:uuid:80ed30c1-30d9-45ad-a556-f457fb279ac7</wsa:MessageID>
12    <wsa:Action>Create</wsa:Action>
13  </soapenv:Header>
14  <soapenv:Body>
15    <par:CreateRequest xmlns:par="http://exacttarget.com/wsdl/partnerAPI" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
16      <par:Options/>
17      <par:Objects xsi:type="par:TriggeredSend">
18        <par:Client>
19          <par:ID>1063695</par:ID>
20        </par:Client>
21        <par:TriggeredSendDefinition>
22          <par:PartnerKey xsi:nil="true"/>
23          <par:ObjectID xsi:nil="true"/>
24          <par:CustomerKey>SampleCustomerKey</par:CustomerKey>
25        </par:TriggeredSendDefinition>
26        <par:Subscribers>
27          <par:EmailAddress>acruz@example.com</par:EmailAddress>
28          <par:Attributes>
29            <par:Name>FirstName</par:Name>
30            <par:Value>Angela</par:Value>
31          </par:Attributes>
32          <par:Attributes>
33            <par:Name>LastName</par:Name>
34            <par:Value>Cruz</par:Value>
35          </par:Attributes>
36          <par:SubscriberKey>acruz@example.com</par:SubscriberKey>
37        </par:Subscribers>
38      </par:Objects>
39    </par:CreateRequest>
40  </soapenv:Body>
41</soapenv:Envelope>

Review SOAP Envelopes to Retrieve Information

The SOAP Request Envelope

The SOAP Response Envelope

Error Message in SOAP Envelopes

Related Items