Interact with Automation Studio

Use SOAP API to interact with Automation Studio. You can use SOAP API to perform these actions in Automation Studio using your own application or development environment:

Create an automation, including all steps and tasks included in the automation
Perform an automation immediately
Retrieve the status of an automation already in progress
Retrieve the status of a single automation instance
Update an automation
Pause an automation

Prerequisites

Automation Studio must be enabled for your account.

Code Examples

Use these code examples with automations that were created using SOAP API. To interact with these automations, use the NewObjectID value returned when you created the automation using SOAP API. If you don’t have this value or if you want to interact with an automation created in the web interface, contact Salesforce Customer Support to retrieve the ID. We recommend that you use SOAP API to create the automations if you plan to use subsequent API calls to interact with them.

Create an Automation

This sample SOAP envelope shows how to create an automation.

1POST /Service.asmx HTTP/1.1
2Host: YOUR_DOMAIN.soap.marketingcloudapis.com
3Content-Type: text/xml;charset=UTF-8
4SOAPaction: Create

1<soapenv:Envelope
2  xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
3  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
4  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
5  xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing"
6  xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
7  xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
8>
9  <soapenv:Header>
10    <wsse:Security soapenv:mustUnderstand="1">
11      <wsse:UsernameToken>
12        <wsse:Username>username</wsse:Username>
13        <wsse:Password>password</wsse:Password>
14      </wsse:UsernameToken>
15    </wsse:Security>
16  </soapenv:Header>
17  <soapenv:Body>
18    <CreateRequest xmlns="http://exacttarget.com/wsdl/partnerAPI">
19      <Options />
20      <Objects xsi:type="Automation">
21        <Client>
22          <ID>1234567</ID>
23        </Client>
24        <Name>AUT_ONEOFF</Name>
25        <CustomerKey>AUT_ONEOFF</CustomerKey>
26        <Description>AUT_ONEOFF</Description>
27        <AutomationTasks>
28          <AutomationTask>
29            <PartnerKey xsi:nil="true" />
30            <ObjectID xsi:nil="true" />
31            <Name>Task 1</Name>
32            <Activities>
33              <Activity>
34                <PartnerKey xsi:nil="true" />
35                <ObjectID>c7ccca24-4567-4317-b8d0-3874d69c130c</ObjectID>
36                <Name>Query 1</Name>
37                <ActivityObject xsi:type="QueryDefinition">
38                  <PartnerKey xsi:nil="true" />
39                  <ObjectID>c7ccca24-4567-4317-b8d0-3874d69c130c</ObjectID>
40                  <CustomerKey>546012e7-4438-4526-9e6c-5ec73939848b</CustomerKey>
41                  <Name>BrowseAbandon_US_Unica_Sendable_Audience_Approved</Name>
42                </ActivityObject>
43              </Activity>
44            </Activities>
45          </AutomationTask>
46        </AutomationTasks>
47        <AutomationType>scheduled</AutomationType>
48      </Objects>
49    </CreateRequest>
50  </soapenv:Body>
51</soapenv:Envelope>

The response indicates the status of the request.

1<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing" 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">
2  <soap:Header>
3    <wsa:Action>CreateResponse</wsa:Action>
4    <wsa:MessageID>urn:uuid:663bdbf6-b24d-45cf-bb4f-0f849228906d</wsa:MessageID>
5    <wsa:RelatesTo>urn:uuid:28100dbe-b01f-4bbc-aac5-88bb9e2d9ee5</wsa:RelatesTo>
6    <wsa:To>http://schemas.xmlsoap.org/ws/2004/08/addressing/role/anonymous</wsa:To>
7    <wsse:Security>
8      <wsu:Timestamp wsu:Id="Timestamp-95b6f164-6835-4d46-9d9d-e9f67cf8a9dc">
9        <wsu:Created>2013-10-04T17:32:11Z</wsu:Created>
10        <wsu:Expires>2013-10-04T17:37:11Z</wsu:Expires>
11      </wsu:Timestamp>
12    </wsse:Security>
13  </soap:Header>
14  <soap:Body>
15    <CreateResponse xmlns="http://exacttarget.com/wsdl/partnerAPI">
16      <Results>
17        <StatusCode>OK</StatusCode>
18        <OrdinalID>0</OrdinalID>
19        <NewID>0</NewID>
20        <NewObjectID>1856a6fb-12dd-4472-a822-8b6ef77b7fd7</NewObjectID>
21        <Object xsi:type="Automation">
22          <PartnerKey xsi:nil="true"/>
23          <ObjectID xsi:nil="true"/>
24        </Object>
25      </Results>
26      <RequestID>522fc2a8-cbbd-4868-8b4b-d14facaa9a03</RequestID>
27      <OverallStatus>OK</OverallStatus>
28    </CreateResponse>
29  </soap:Body>
30</soap:Envelope>

Perform an Automation Immediately

This sample SOAP envelope shows how to perform an automation immediately.

1POST /Service.asmx HTTP/1.1
2Host: YOUR_DOMAIN.soap.marketingcloudapis.com
3Content-Type: text/xml;charset=UTF-8
4SOAPaction: Perform

1<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing" 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">
2   <soapenv:Header>
3      <wsse:Security soapenv:mustUnderstand="1">
4         <wsse:UsernameToken>
5            <wsse:Username>Username</wsse:Username>
6            <wsse:Password>Password</wsse:Password>
7         </wsse:UsernameToken>
8      </wsse:Security>
9   </soapenv:Header>
10   <soapenv:Body>
11      <PerformRequestMsg xmlns="http://exacttarget.com/wsdl/partnerAPI">
12         <Action>start</Action>
13         <Definitions>
14            <Definition xsi:type="Automation">
15               <Client>
16                  <ID>1234567</ID>
17               </Client>
18               <ObjectID>d3f5e492-f1a9-47be-a510-15b0d8de65d3</ObjectID>
19            </Definition>
20         </Definitions>
21      </PerformRequestMsg>
22   </soapenv:Body>
23</soapenv:Envelope>

Retrieve an Automation

This sample SOAP envelope shows how to retrieve information about an automation.

1POST /Service.asmx HTTP/1.1
2Host: YOUR_DOMAIN.soap.marketingcloudapis.com
3Content-Type: text/xml;charset=UTF-8
4SOAPaction: Retrieve

1<s:Envelope
2	xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"
3	xmlns:u="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
4	<s:Header>
5		<o:Security
6			xmlns:o="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" s:mustUnderstand="1">
7			<o:UsernameToken u:Id="uuid-4e7d733b-f16d-44e1-b947-b27ce4cda3fe-1">
8				<o:Username>ccc</o:Username>
9				<o:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">ccc</o:Password>
10			</o:UsernameToken>
11		</o:Security>
12	</s:Header>
13	<s:Body
14		xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
15		xmlns:xsd="http://www.w3.org/2001/XMLSchema">
16		<RetrieveRequestMsg
17			xmlns="http://exacttarget.com/wsdl/partnerAPI">
18			<RetrieveRequest>
19				<ClientIDs>
20					<ClientID>1234567</ClientID>
21				</ClientIDs>
22				<ObjectType>Automation</ObjectType>
23				<Properties>ProgramID</Properties>
24				<Properties>Name</Properties>
25				<Properties>Description</Properties>
26				<Properties>RecurrenceID</Properties>
27				<Properties>CustomerKey</Properties>
28				<Properties>IsActive</Properties>
29				<Properties>CreatedDate</Properties>
30				<Properties>ModifiedDate</Properties>
31				<Properties>Status</Properties>
32				<Filter xsi:type="SimpleFilterPart">
33					<Property>ProgramID</Property>
34					<SimpleOperator>equals</SimpleOperator>
35					<Value>aa697ba2-3531-4c26-8669-20594a949145</Value>
36				</Filter>
37			</RetrieveRequest>
38		</RetrieveRequestMsg>
39	</s:Body>
40</s:Envelope>

The response includes data for the fields specified in the request.

1<?xml version="1.0" encoding="utf-8"?>
2<soap:Envelope
3	xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
4	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
5	xmlns:xsd="http://www.w3.org/2001/XMLSchema"
6	xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing"
7	xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
8	xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
9	<soap:Body>
10		<RetrieveResponseMsg
11			xmlns="http://exacttarget.com/wsdl/partnerAPI">
12			<OverallStatus>MoreDataAvailable</OverallStatus>
13			<RequestID>147c8363-3cbb-40fa-96b0-b242d51cacc5</RequestID>
14			<Results xsi:type="Automation">
15				<PartnerKey/>
16				<PartnerProperties>
17					<Name>AutomationType</Name>
18					<Value>scheduled</Value>
19				</PartnerProperties>
20				<CreatedDate>2014-04-24T07:02:53.857</CreatedDate>
21				<ModifiedDate>2014-04-24T07:33:53.27</ModifiedDate>
22				<ObjectID>8b6aea33-6f91-4556-bae3-794650b328eb</ObjectID>
23				<CustomerKey>aa697ba2-3531-4c26-8669-20594a949145</CustomerKey>
24				<ObjectState/>
25				<Name>Example Automation</Name>
26				<Description>SOAP API Created Example</Description>
27				<Keyword/>
28				<AutomationTasks>
29					<AutomationTask>
30						<PartnerKey xsi:nil="true"/>
31						<ObjectID xsi:nil="true"/>
32						<AutomationTaskType>42</AutomationTaskType>
33						<Activities>
34							<Activity>
35								<PartnerKey xsi:nil="true"/>
36								<ObjectID>5a0d3995-0cf2-4fcf-bb6b-c2cfc50e0c8b</ObjectID>
37								<Name>MyEmailSendDefinition</Name>
38								<IsActive>true</IsActive>
39								<Definition>
40									<PartnerKey xsi:nil="true"/>
41									<ObjectID xsi:nil="true"/>
42									<CustomerKey>aa697ba2-3531-4c26-8669-20594a949145</CustomerKey>
43								</Definition>
44								<Sequence>0</Sequence>
45							</Activity>
46						</Activities>
47					</AutomationTask>
48				</AutomationTasks>
49				<IsActive>true</IsActive>
50				<Status>2</Status>
51				<AutomationType>scheduled</AutomationType>
52			</Results>
53		</RetrieveResponseMsg>
54	</soap:Body>
55</soap:Envelope>

Retrieve a Single Instance of an Existing Automation

Use the Automation ID and AutomationInstanceID fields to retrieve existing automations.

1POST /Service.asmx HTTP/1.1
2Host: YOUR_DOMAIN.soap.marketingcloudapis.com
3Content-Type: text/xml;charset=UTF-8
4SOAPaction: Retrieve

1<Envelope
2  xmlns="http://schemas.xmlsoap.org/soap/envelope/"
3  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
4  <Header>
5    <fueloauth>YOUR_ACCESS_TOKEN</fueloauth>
6  </Header>
7  <Body>
8    <RetrieveRequestMsg xmlns="http://exacttarget.com/wsdl/partnerAPI ">
9      <RetrieveRequest>
10        <ObjectType>AutomationInstance</ObjectType>
11        <Properties>ProgramID</Properties>
12        <Properties>Status</Properties>
13        <Properties>Name</Properties>
14        <Properties>CreatedDate</Properties>
15        <Properties>ModifiedDate</Properties>
16        <Properties>CustomerKey</Properties>
17        <Properties>RecurrenceID</Properties>
18        <Properties>ClientID</Properties>
19        <Filter xsi:type="SimpleFilterPart">
20          <Property>ProgramInstanceID</Property>
21          <SimpleOperator>equals</SimpleOperator>
22          <Value>4948b9f5-5f88-4b3f-bf84-5faf8014b5a2</Value>
23          <!-- GUID Value for ProgramInstanceID is returned from Automation Perform as the ObjectID -->
24        </Filter>
25      </RetrieveRequest>
26    </RetrieveRequestMsg>
27  </Body>
28</Envelope>

Update an Automation

This sample SOAP envelope shows how to update an automation.

1POST /Service.asmx HTTP/1.1
2Host: YOUR_DOMAIN.soap.marketingcloudapis.com
3Content-Type: text/xml;charset=UTF-8
4SOAPaction: Update

1<s:Envelope
2  xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"
3  xmlns:u="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
4  <s:Header>
5    <o:Security s:mustUnderstand="1" xmlns:o="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
6      <o:UsernameToken u:Id="uuid-4058d7c8-2104-490a-a67f-88de530a4506-1">
7        <o:Username>XXXXX</o:Username>
8        <o:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">XXXXX</o:Password>
9      </o:UsernameToken>
10    </o:Security>
11  </s:Header>
12  <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
13    <UpdateRequest xmlns="http://exacttarget.com/wsdl/partnerAPI">
14      <Options/>
15      <Objects xsi:type="Automation">
16        <PartnerKey xsi:nil="true"/>
17        <ObjectID>8b6aea33-6f91-4556-bae3-794650b328eb</ObjectID>
18        <Name>This automation received a new name</Name>
19      </Objects>
20    </UpdateRequest>
21  </s:Body>
22</s:Envelope>

Pause an Automation

This sample SOAP envelope shows how to pause an automation.

1POST /Service.asmx HTTP/1.1
2Host: YOUR_DOMAIN.soap.marketingcloudapis.com
3Content-Type: text/xml;charset=UTF-8
4SOAPaction: Perform

1<soap:Envelope
2	xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
3	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
4	xmlns:xsd="http://www.w3.org/2001/XMLSchema"
5	xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing"
6	xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
7	xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
8	<soap:Header>
9		<wsse:Security soap:mustUnderstand="1">
10			<wsse:UsernameToken wsu:Id="SecurityToken-4c1eed3b-75ee-4d19-8712-731028aaad77">
11				<wsse:Username>XXXXX</wsse:Username>
12				<wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">XXXXX</wsse:Password>
13			</wsse:UsernameToken>
14		</wsse:Security>
15	</soap:Header>
16	<soap:Body>
17		<ScheduleRequestMsg
18			xmlns="http://exacttarget.com/wsdl/partnerAPI">
19			<Action>pause</Action>
20			<Schedule></Schedule>
21			<Interactions>
22				<Interaction xsi:type="Automation">
23					<ObjectID>78d55eb5-0811-4638-a574-374a242426f7</ObjectID>
24				</Interaction>
25			</Interactions>
26		</ScheduleRequestMsg>
27	</soap:Body>
28</soap:Envelope>