Skip to main content

Trigger Automations via API

Learning Objectives

After completing this unit, you’ll be able to:

  • Review available API requests for Automation Studio.
  • Follow best practices for API requests.

Automation Studio allows you to chain together a bunch of activities in the Marketing Cloud Engagement app, but you can also use API requests. Each activity has an external key for reference, as well as the entire automation itself. Let’s dive into your options.

SOAP API and Automation Studio

Marketing Cloud Engagement’s SOAP API gives you options to perform several functions for Automation Studio.

  • Create an automation, including all related activities.
  • Immediately perform an automation.
  • Retrieve the status of an automation already in progress.
  • Retrieve the status of a single automation.
  • Schedule an existing automation.
  • Update an automation.
  • Pause an automation.
  • Delete an automation.

For example, Alex Driskel from Get Cloudy Consulting could use this SOAP envelope to create an automation that accesses the Sent data view.

If you use the following code, be sure that you replace these two values with your tenant-specific domain and access token values.

  • {{et_subdomain}}: your tenant-specific subdomain
  • {{dne_etAccessToken}}: your access token

Sample Code: Access the Sent Data View

<?xml version="1.0" encoding="UTF-8"?>
     <s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:a="http://schemas.xmlsoap.org/ws/2004/08/addressing" xmlns:u="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
          <s:Header>
               <a:Action s:mustUnderstand="1">Create</a:Action>
               <a:To s:mustUnderstand="1">https://{{et_subdomain}}.soap.marketingcloudapis.com/Service.asmx</a:To>
               <fueloauth xmlns="http://exacttarget.com">{{dne_etAccessToken}}</fueloauth>
          </s:Header>
          <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
               <CreateRequest xmlns="http://exacttarget.com/wsdl/partnerAPI">
                    <Objects xsi:type="Automation">
                         <Name>System Data Views</Name>
                         <CustomerKey>DataViews_Automation</CustomerKey>
                         <AutomationTasks>
                              <AutomationTask>
                                   <Name>Load Data Views</Name>
                                   <Activities>
                                        <Activity>
                                             <ObjectID>64315dd7-95c6-430d-940e-09f72147f8a1</ObjectID>
                                             <ActivityObject xsi:type="QueryDefinition">
                                                  <ObjectID>64315dd7-95c6-430d-940e-09f72147f8a1</ObjectID>
                                                  <CustomerKey>DataView_Sent</CustomerKey>
                                                  <Name>DataView_Sent</Name>
                                             </ActivityObject>
                                        </Activity>
                                   </Activities>
                             </AutomationTask>
                        </AutomationTasks>
                        <AutomationType>scheduled</AutomationType>
                   </Objects>
              </CreateRequest>
          </s:Body>
     </s:Envelope>

After Alex’s automation is set, he can schedule the automation to run at a specified time using an API request containing this information.

Sample Code: Schedule the Automation

<?xml version="1.0" encoding="UTF-8"?>
     <s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:a="http://schemas.xmlsoap.org/ws/2004/08/addressing" xmlns:u="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
          <s:Header>
               <a:Action s:mustUnderstand="1">Schedule</a:Action>
               <a:To s:mustUnderstand="1">https://{{et_subdomain}}.soap.marketingcloudapis.com/Service.asmx</a:To>
               <fueloauth xmlns="http://exacttarget.com">{{dne_etAccessToken}}</fueloauth>
          </s:Header>
          <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
               <ScheduleRequestMsg xmlns="http://exacttarget.com/wsdl/partnerAPI">
                    <Action>start</Action>
                    <Schedule>
                         <Recurrence xsi:type="HourlyRecurrence">
                              <HourlyRecurrencePatternType>Interval</HourlyRecurrencePatternType>
                              <HourInterval>24</HourInterval>
                         </Recurrence>
                         <RecurrenceType>Hourly</RecurrenceType>
                         <RecurrenceRangeType>EndOn</RecurrenceRangeType>
                         <StartDateTime>2021-03-25T20:53:23.2236156-03:00</StartDateTime>
                         <EndDateTime>2038-03-25T20:53:23.2236156-03:00</EndDateTime>
                    </Schedule>
                    <Interactions>
                         <Interaction xsi:type="Automation">
                              <ObjectID>a41c4d53-0487-495d-b374-3427cc278fcd</ObjectID>
                         </Interaction>
                    </Interactions>
               </ScheduleRequestMsg>
          </s:Body>
     </s:Envelope>

And if Alex needs results quickly, he can immediately perform the automation with a SOAP API request based off of this SOAP envelope.

Sample Code: Perform the Automation

<?xml version="1.0" encoding="UTF-8"?>
     <s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:a="http://schemas.xmlsoap.org/ws/2004/08/addressing" xmlns:u="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
          <s:Header>
               <a:Action s:mustUnderstand="1">Perform</a:Action>
               <a:To s:mustUnderstand="1">https://{{et_subdomain}}.soap.marketingcloudapis.com/Service.asmx</a:To>
               <fueloauth xmlns="http://exacttarget.com">{{dne_etAccessToken}}</fueloauth>
          </s:Header>
          <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
               <PerformRequestMsg xmlns="http://exacttarget.com/wsdl/partnerAPI" xmlns:ns2="urn:fault.partner.exacttarget.com">
                    <Action>start</Action>
                    <Definitions>
                         <Definition xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="Automation">
                              <ObjectID>a41c4d53-0487-495d-b374-3427cc278fcd</ObjectID>
                         </Definition>
                    </Definitions>
               </PerformRequestMsg>
          </s:Body>
     </s:Envelope>

So why would Alex want to use SOAP API requests to handle this task when he could just get into Marketing Cloud Engagement and use the app to create the automation? The answer depends on the task. API calls are helpful if you’re building custom integrations or tying certain actions tightly to output from other systems. The vast majority of Automation Studio users can get what they need from the Automation Studio app and tie it to either a schedule or an automated file drop from an FTP location. For more specific cases, the SOAP API helps you work those Automation Studio requests into whatever systems you might need.

Right Request, Right Time

The standard advice for Marketing Cloud Engagement API requests apply to Automation Studio requests as well. If you know an automation is going to take a lot of time and resources to perform, try to schedule it when there is less overall activity in your account. Include only necessary information in your requests—and that applies to any queries or scripts you include in your requests. Join us in the next unit as we troubleshoot in Automation Studio. 

Resources

Keep learning for
free!
Sign up for an account to continue.
What’s in it for you?
  • Get personalized recommendations for your career goals
  • Practice your skills with hands-on challenges and quizzes
  • Track and share your progress with employers
  • Connect to mentorship and career opportunities