Perform a Data Extract

This page contains information about performing a data extract using the SOAP API.

Why Perform a Data Extract 

You can use a data extract to pull information from your Marketing Cloud Engagement account and place it in a file on an FTP site for use in a different system (such as a web analytics tool).

How to Perform a Tracking Data Extract Activity 

Use the code below as a model to construct your own API call. Note that the ExtractRequest ID can be obtained by performing a Retrieve call on the ExtractDescription object. This call returns all possible IDs for the extracts available to your account.

Sample .NET Code 

1public void RequestDataExtract()
2        {
3            SoapClient framework = new SoapClient();
4            framework.ClientCredentials.UserName.UserName = "XXXX";
5            framework.ClientCredentials.UserName.Password = "XXXX";
6            ExtractRequest request = new ExtractRequest();
7            ExtractRequest[] requests = new ExtractRequest[1];
8            List<ExtractParameter> extractParameters = new List<ExtractParameter>();
9            ExtractParameter extractParam = null;
10            ExtractResult[] responses;
11            request = new ExtractRequest();
12            requests = new ExtractRequest[1];
13            extractParameters = new List<ExtractParameter>();
14            // This is a constant value used to identify the desired extract.  This is required.  This values is for "Tracking Extract"
15            request.ID = "c7219016-a7f0-4c72-8657-1ec12c28a0db";
16            extractParam = new ExtractParameter();
17            extractParam.Name = "StartDate";
18            extractParam.Value = Convert.ToDateTime("2009-09-12").ToString();
19            extractParameters.Add(extractParam);
20            DateTime endDateTime = Convert.ToDateTime("2009-09-18");
21            extractParam = new ExtractParameter();
22            extractParam.Name = "EndDate";
23            extractParam.Value = endDateTime.ToString();
24            extractParameters.Add(extractParam);
25            extractParam = new ExtractParameter();
26            extractParam.Name = "ExtractOpens";
27            extractParam.Value = "true";   // Get opens, set to false to not return opens
28            extractParameters.Add(extractParam);
29            extractParam = new ExtractParameter();
30            extractParam.Name = "ExtractClicks";
31            extractParam.Value = "true"; // Get clicks, set to false to not return clicks\
32            extractParameters.Add(extractParam);
33            extractParam = new ExtractParameter();
34            extractParam.Name = "ExtractSent";
35            extractParam.Value = "true"; // Get sent events, set to false to not return sent envents
36            extractParameters.Add(extractParam);
37            extractParam = new ExtractParameter();
38            extractParam.Name = "ExtractUnsubs";
39            extractParam.Value = "true";  // Get unsubscribes, set to false to not return unsubscribes.
40            extractParameters.Add(extractParam);
41            extractParam = new ExtractParameter();
42            extractParam.Name = "ExtractConversions";
43            extractParam.Value = "false";  // Get conversion events, set to false to not return conversions.
44            extractParameters.Add(extractParam);
45            extractParam = new ExtractParameter();
46            extractParam.Name = "ExtractSurveyResponses";
47            extractParam.Value = "false";  // Get survey respones, set to false to not return survey respones.
48            extractParameters.Add(extractParam);
49            extractParam = new ExtractParameter();
50            extractParam.Name = "ExtractBounces";
51            extractParam.Value = "true";  // Get bounces, set to false to not reutrn bounces.
52            extractParameters.Add(extractParam);
53            extractParam = new ExtractParameter();
54            extractParam.Name = "ExtractSubscribers";
55            extractParam.Value = "true";  // Get subscribers, set to false to not return subscribers.
56            extractParameters.Add(extractParam);
57            extractParam = new ExtractParameter();
58            extractParam.Name = "ExtractSendJobs";
59            extractParam.Value = "true";  // Get sends, set to false to not return sends
60            extractParameters.Add(extractParam);
61            extractParam = new ExtractParameter();
62            extractParam.Name = "QuoteText";
63            extractParam.Value = "true";  // Quote the text
64            extractParameters.Add(extractParam);
65            extractParam = new ExtractParameter();
66            extractParam.Name = "OutputFileName";
67            extractParam.Value = String.Format("tracking_test.zip");
68            extractParameters.Add(extractParam);
69            request.Parameters = extractParameters.ToArray();
70            requests[0] = request;
71            string requestID = String.Empty;
72            string overallResult = String.Empty;
73            overallResult = framework.Extract(requests, out requestID, out responses);
74            Console.WriteLine(String.Format("{0} - [{1}] {2}", overallResult, responses[0].ErrorCode, responses[0].ErrorCode));
75    }

Sample Java Code (Axis 1.4) 

1public void testExtractDataFromETSystem() throws RemoteException {
2        Soap_PortType soap_portType = init();
3        ExtractRequest request = new ExtractRequest();
4        ArrayList<ExtractParameter> extractParameters = new ArrayList();
5        ExtractParameter extractParam = null;
6        extractParam = new ExtractParameter();
7        extractParam.setName("ExtractClicks");
8        extractParam.setValue("true");
9        extractParameters.add(extractParam);
10        extractParam = new ExtractParameter();
11        extractParam.setName("ExtractBounces");
12        extractParam.setValue("true");
13        extractParameters.add(extractParam);
14        extractParam = new ExtractParameter();
15        extractParam.setName("ExtractOpens");
16        extractParam.setValue("true");
17        extractParameters.add(extractParam);
18        extractParam = new ExtractParameter();
19        extractParam.setName("ExtractSubscribers");
20        extractParam.setValue("true");
21        extractParameters.add(extractParam);
22        String datePattern = "MM/dd/yyyy KK:mm a";
23        extractParam = new ExtractParameter();
24        extractParam.setName("StartDate");
25        Calendar start = Calendar.getInstance();
26        start.set(2008, 05, 01, 0, 0);
27        SimpleDateFormat dateFormat = new SimpleDateFormat(datePattern);
28        String cd1 = dateFormat.format(start.getTime());
29        extractParam.setValue(cd1);
30        extractParameters.add(extractParam);
31        extractParam = new ExtractParameter();
32        extractParam.setName("EndDate");
33        Calendar end = Calendar.getInstance();
34        end.set(2009, 05, 01, 0, 0);
35        String cd2 = dateFormat.format(end.getTime());
36        extractParam.setValue(cd2);
37        extractParameters.add(extractParam);
38        extractParam = new ExtractParameter();
39        extractParam.setName("OutputFileName");
40        extractParam.setValue("tracking_october08.zip");
41        extractParameters.add(extractParam);
42        ExtractParameter[] parameters = extractParameters.toArray(new ExtractParameter[extractParameters.size()]);
43        request.setParameters(parameters);
44        request.setOptions(new ExtractOptions());
45        request.setID("c7219016-a7f0-4c72-8657-1ec12c28a0db");
46        ExtractRequest[] requests = new ExtractRequest[]{request};
47        ExtractResponseMsg extractResult = soap_portType.extract(requests);
48        System.out.println("Resposne ::: " + extractResult.getOverallStatus());
49}

Sample SOAP Envelope 

1<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
2   <Header>
3       <fueloauth>YOUR_ACCESS_TOKEN</fueloauth>
4   </Header>
5   <Body>
6      <ExtractRequestMsg xmlns="http://exacttarget.com/wsdl/partnerAPI">
7         <Requests>
8            <ID>c7219016-a7f0-4c72-8657-1ec12c28a0db</ID>
9            <Parameters>
10               <Parameter>
11                  <Name>StartDate</Name>
12                  <Value>10/26/2012 12:00:00 AM</Value>
13               </Parameter>
14               <Parameter>
15                  <Name>EndDate</Name>
16                  <Value>10/29/2015 12:00:00 AM</Value>
17               </Parameter>
18               <Parameter>
19                  <Name>OutputFileName</Name>
20                  <Value>ExampleTracking.zip</Value>
21               </Parameter>
22               <Parameter>
23                  <Name>AccountIDs</Name>
24                  <Value/>
25               </Parameter>
26               <Parameter>
27                  <Name>Attributes</Name>
28                  <Value/>
29               </Parameter>
30               <Parameter>
31                  <Name>CharacterEncoding</Name>
32                  <Value>Default</Value>
33               </Parameter>
34               <Parameter>
35                  <Name>ColumnDelimiter</Name>
36                  <Value>Default</Value>
37               </Parameter>
38               <Parameter>
39                  <Name>ExtractAttributes</Name>
40                  <Value>false</Value>
41               </Parameter>
42               <Parameter>
43                  <Name>ExtractBounces</Name>
44                  <Value>true</Value>
45               </Parameter>
46               <Parameter>
47                  <Name>ExtractClickImpressions</Name>
48                  <Value>false</Value>
49               </Parameter>
50               <Parameter>
51                  <Name>ExtractClicks</Name>
52                  <Value>true</Value>
53               </Parameter>
54               <Parameter>
55                  <Name>ExtractConversions</Name>
56                  <Value>false</Value>
57               </Parameter>
58               <Parameter>
59                  <Name>extractListMembershipChanges</Name>
60                  <Value>false</Value>
61               </Parameter>
62               <Parameter>
63                  <Name>extractLists</Name>
64                  <Value>false</Value>
65               </Parameter>
66               <Parameter>
67                  <Name>ExtractNotSent</Name>
68                  <Value>false</Value>
69               </Parameter>
70               <Parameter>
71                  <Name>ExtractOpens</Name>
72                  <Value>true</Value>
73               </Parameter>
74               <Parameter>
75                  <Name>ExtractSendImpressions</Name>
76                  <Value>false</Value>
77               </Parameter>
78               <Parameter>
79                  <Name>ExtractSendJobImpressions</Name>
80                  <Value>false</Value>
81               </Parameter>
82               <Parameter>
83                  <Name>ExtractSendJobs</Name>
84                  <Value>true</Value>
85               </Parameter>
86               <Parameter>
87                  <Name>ExtractSent</Name>
88                  <Value>true</Value>
89               </Parameter>
90               <Parameter>
91                  <Name>extractStatusChanges</Name>
92                  <Value>false</Value>
93               </Parameter>
94               <Parameter>
95                  <Name>ExtractSubscribers</Name>
96                  <Value>false</Value>
97               </Parameter>
98               <Parameter>
99                  <Name>ExtractSurveyResponses</Name>
100                  <Value>true</Value>
101               </Parameter>
102               <Parameter>
103                  <Name>ExtractUnsubs</Name>
104                  <Value>true</Value>
105               </Parameter>
106               <Parameter>
107                  <Name>Format</Name>
108                  <Value>csv</Value>
109               </Parameter>
110               <Parameter>
111                  <Name>IncludeAllListMembers</Name>
112                  <Value>false</Value>
113               </Parameter>
114               <Parameter>
115                  <Name>IncludeAllSubscribers</Name>
116                  <Value>false</Value>
117               </Parameter>
118               <Parameter>
119                  <Name>IncludeInferredOpens</Name>
120                  <Value>false</Value>
121               </Parameter>
122               <Parameter>
123                  <Name>IncludeMilliseconds</Name>
124                  <Value>false</Value>
125               </Parameter>
126               <Parameter>
127                  <Name>IncludeTestSends</Name>
128                  <Value>true</Value>
129               </Parameter>
130               <Parameter>
131                  <Name>IncludeUnsubReason</Name>
132                  <Value>false</Value>
133               </Parameter>
134               <Parameter>
135                  <Name>QuoteText</Name>
136                  <Value>false</Value>
137               </Parameter>
138               <Parameter>
139                  <Name>SendIDs</Name>
140                  <Value>12283113,12283120</Value>
141               </Parameter>
142               <Parameter>
143                  <Name>TextQualifier</Name>
144                  <Value/>
145               </Parameter>
146               <Parameter>
147                  <Name>Timezone</Name>
148                  <Value>1</Value>
149               </Parameter>
150               <Parameter>
151                  <Name>UnicodeOutput</Name>
152                  <Value>false</Value>
153               </Parameter>
154               <Parameter>
155                  <Name>UseIDs</Name>
156                  <Value>false</Value>
157               </Parameter>
158               <Parameter>
159                  <Name>UseLocalTZinQuery</Name>
160                  <Value>false</Value>
161               </Parameter>
162            </Parameters>
163         </Requests>
164      </ExtractRequestMsg>
165   </Body>
166</Envelope>

How to Create a Data Extension Data Extract 

Use the sample code below to construct a data extract to extract data from a data extension.

Sample .NET Code 

1public static void ExtractDataExtension(SoapClient soapClient, string DataExtensionCustomerKey, string FileName) {
2                ExtractRequest er = new ExtractRequest();
3                er.ID = "bb94a04d-9632-4623-be47-daabc3f588a6";
4
5                // Always set an StartDate to the value specified
6                ExtractParameter epOne = new ExtractParameter();
7                epOne.Name = "StartDate";
8                epOne.Value = "1/1/1900 1:00:00 AM";
9
10                // Always set an StartDate to the value specified
11                ExtractParameter epTwo = new ExtractParameter();
12                epTwo.Name = "EndDate";
13                epTwo.Value = "1/1/1900 1:00:00 AM";
14
15                // Always set an _Async to 0
16                ExtractParameter epThree = new ExtractParameter();
17                epThree.Name = "_AsyncID";
18                epThree.Value = "0";
19
20                ExtractParameter epFour = new ExtractParameter();
21                epFour.Name = "OutputFileName";
22                epFour.Value = FileName;
23
24                ExtractParameter epFive = new ExtractParameter();
25                epFive.Name = "DECustomerKey";
26                epFive.Value = DataExtensionCustomerKey;
27
28                ExtractParameter epSix = new ExtractParameter();
29                epSix.Name = "HasColumnHeaders";
30                epSix.Value = "true";
31
32                er.Parameters = new ExtractParameter[] {epOne, epTwo, epThree, epFour, epFive, epSix };
33
34                string sRequestId;
35                string sStatus;
36                ExtractResult[] results;
37                sStatus = soapClient.Extract(new ExtractRequest[] { er }, out sRequestId, out results);
38
39                Console.WriteLine("Status: " + sStatus);
40                Console.WriteLine("Request ID: " + sRequestId);
41
42                foreach (ExtractResult eresult in results)
43                {
44                                Console.WriteLine("StatusCode: " + eresult.StatusCode);
45                                Console.WriteLine("ErrorCode: " + eresult.ErrorCode);
46                                Console.WriteLine("StatusMessage: " + eresult.StatusMessage);
47                }
48}

Sample SOAP Envelope 

1<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">
2   <s:Header>
3      <o:Security s:mustUnderstand="1" xmlns:o="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
4         <o:UsernameToken u:Id="uuid-2517ad18-a6e9-4f38-98a9-184b30a59fb9-1">
5            <o:Username>XXXXX</o:Username>
6            <o:Password>XXXXX</o:Password>
7         </o:UsernameToken>
8      </o:Security>
9   </s:Header>
10   <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
11      <ExtractRequestMsg xmlns="http://exacttarget.com/wsdl/partnerAPI">
12         <Requests>
13            <ID>bb94a04d-9632-4623-be47-daabc3f588a6</ID>
14            <Parameters>
15               <Parameter>
16                  <Name>DECustomerKey</Name>
17                  <Value>OrderHistory</Value>
18               </Parameter>
19               <Parameter>
20                  <Name>HasColumnHeaders</Name>
21                  <Value>true</Value>
22               </Parameter>
23               <Parameter>
24                  <!--This parameter is required, always pass a value of 0-->
25                  <Name>_AsyncID</Name>
26                  <Value>0</Value>
27               </Parameter>
28               <Parameter>
29                  <Name>OutputFileName</Name>
30                  <Value>MyExtractFile.csv</Value>
31               </Parameter>
32               <Parameter>
33                  <!--This parameter is required, always pass value shown below-->
34                  <Name>StartDate</Name>
35                  <Value>1/1/1900 1:00:00 AM</Value>
36               </Parameter>
37               <Parameter>
38                  <!--This parameter is required, always pass value shown below-->
39                  <Name>EndDate</Name>
40                  <Value>1/1/1900 1:00:00 AM</Value>
41               </Parameter>
42            </Parameters>
43         </Requests>
44      </ExtractRequestMsg>
45   </s:Body>
46</s:Envelope>

Related Items