Create a Data Extension

Use a data extension to store information about your subscribers.

Data Extension Considerations

Keep these considerations in mind when you use SOAP API to create data extensions:

Limit data extension external keys to 36 characters. You can specify an external key that exceeds this limit, but doing so can negatively impact other processes.
Don’t use Date values as primary keys. When you retrieve a column that contains the Date data type, SOAP API returns a value that’s rounded to the nearest second, followed by AM or PM. This behavior occurs even when the source timestamp contains millisecond data. As a result, if you use a Date column as a primary key, it can prevent you from retrieving unique rows.

Sample SOAP Create Request

This sample SOAP envelope represents a request to create a data extension called DataExtensionFromAPI. The data extension contains 4 fields: EmailAddress, ChannelUser, ChannelUser_EmailAddress, and Demographic_Address.

1<soapenv:Body>
2  <CreateRequest xmlns="http://exacttarget.com/wsdl/partnerAPI">
3    <Options></Options>
4    <Objects
5      xmlns:ns1="http://exacttarget.com/wsdl/partnerAPI"
6      xsi:type="ns1:DataExtension">
7      <CustomerKey>DataExtensionFromAPI</CustomerKey>
8      <Name>DataExtensionFromAPI</Name>
9      <IsSendable>true</IsSendable>
10      <SendableDataExtensionField>
11        <CustomerKey>EmailAddress_Key</CustomerKey>
12        <Name>EmailAddress</Name>
13        <FieldType>EmailAddress</FieldType>
14      </SendableDataExtensionField>
15      <SendableSubscriberField>
16        <Name>Email Address</Name>
17        <Value></Value>
18      </SendableSubscriberField>
19      <Fields>
20        <Field>
21          <CustomerKey>EmailAddress_Key</CustomerKey>
22          <Name>EmailAddress</Name>
23          <FieldType>EmailAddress</FieldType>
24        </Field>
25        <Field>
26          <CustomerKey>ChannelUser_Key</CustomerKey>
27          <Name>ChannelUser</Name>
28          <FieldType>Text</FieldType>
29        </Field>
30        <Field>
31          <CustomerKey>ChannelUser_EmailAddress_Key</CustomerKey>
32          <Name>ChannelUser_EmailAddress</Name>
33          <FieldType>EmailAddress</FieldType>
34        </Field>
35        <Field>
36          <CustomerKey>Demographic_Address_Key</CustomerKey>
37          <Name>Demographic_Address</Name>
38          <FieldType>Text</FieldType>
39        </Field>
40      </Fields>
41    </Objects>
42  </CreateRequest>
43</soapenv:Body>

Sample SOAP Create Response

If the API accepts the request to create a data extension, the response includes the external key, name, and fields for the data extension.

1<soap:Body>
2  <CreateResponse xmlns="http://exacttarget.com/wsdl/partnerAPI">
3    <Results>
4      <StatusCode>OK</StatusCode>
5      <StatusMessage>Data Extension created.</StatusMessage>
6      <OrdinalID>0</OrdinalID>
7      <NewID>0</NewID>
8      <NewObjectID>1a3e2c14-580e-de11-b30f-001cc494ae9e</NewObjectID>
9      <Object xsi:type="DataExtension">
10        <ObjectID>1a3e2c14-580e-de11-b30f-001cc494ae9e</ObjectID>
11        <CustomerKey>DataExtensionFromAPI</CustomerKey>
12        <Name>DataExtensionFromAPI</Name>
13        <IsSendable>true</IsSendable>
14        <SendableDataExtensionField>
15          <ObjectID xsi:nil="true" />
16          <CustomerKey>EmailAddress_Key</CustomerKey>
17          <Name>EmailAddress</Name>
18          <FieldType>EmailAddress</FieldType>
19        </SendableDataExtensionField>
20        <SendableSubscriberField>
21          <Name>Email Address</Name>
22          <Value />
23        </SendableSubscriberField>
24        <Fields>
25          <Field>
26            <ObjectID xsi:nil="true" />
27            <CustomerKey>EmailAddress_Key</CustomerKey>
28            <Name>EmailAddress</Name>
29            <FieldType>EmailAddress</FieldType>
30          </Field>
31          <Field>
32            <ObjectID xsi:nil="true" />
33            <CustomerKey>ChannelUser_Key</CustomerKey>
34            <Name>ChannelUser</Name>
35            <FieldType>Text</FieldType>
36          </Field>
37          <Field>
38            <ObjectID xsi:nil="true" />
39            <CustomerKey>ChannelUser_EmailAddress_Key</CustomerKey>
40            <Name>ChannelUser_EmailAddress</Name>
41            <FieldType>EmailAddress</FieldType>
42          </Field>
43          <Field>
44            <ObjectID xsi:nil="true" />
45            <CustomerKey>Demographic_Address_Key</CustomerKey>
46            <Name>Demographic_Address</Name>
47            <FieldType>Text</FieldType>
48          </Field>
49        </Fields>
50      </Object>
51    </Results>
52    <RequestID>27a2d45f-0eef-4118-b4de-fde288b09657</RequestID>
53    <OverallStatus>OK</OverallStatus>
54  </CreateResponse>
55</soap:Body>

Create a Data Extension with Non-Nullable Fields

This sample SOAP envelope creates a data extension with a non-nullable field by including IsPrimaryKey and IsRequired values.

1<soapenv:Body>
2  <CreateRequest xmlns="http://exacttarget.com/wsdl/partnerAPI">
3    <Options />
4    <Objects xsi:type="ns2:DataExtension"
5      xmlns:ns2="http://exacttarget.com/wsdl/partnerAPI">
6      <CustomerKey>yoni_test_10</CustomerKey>
7      <Name>yoni_test_1</Name>
8      <Description>Created from API on 2024-02-08</Description>
9      <IsSendable>true</IsSendable>
10      <IsTestable>true</IsTestable>
11      <SendableDataExtensionField xsi:type="ns2:DataExtensionField">
12        <Name>userid</Name>
13        <FieldType>EmailAddress</FieldType>
14      </SendableDataExtensionField>
15      <SendableSubscriberField>
16        <Name>Subscriber Key</Name>
17        <Value />
18      </SendableSubscriberField>
19      <Fields>
20        <Field xsi:type="ns2:DataExtensionField">
21          <CustomerKey>userid</CustomerKey>
22          <Name>userid</Name>
23          <Label>userid</Label>
24          <IsRequired>true</IsRequired>
25          <IsPrimaryKey>true</IsPrimaryKey>
26          <FieldType>EmailAddress</FieldType>
27        </Field>
28        <Field xsi:type="ns2:DataExtensionField">
29          <CustomerKey>geoid</CustomerKey>
30          <Name>geoid</Name>
31          <DataType>Number</DataType>
32          <Label>geoid</Label>
33          <FieldType>Number</FieldType>
34        </Field>
35        <Field xsi:type="ns2:DataExtensionField">
36          <CustomerKey>order</CustomerKey>
37          <Name>order</Name>
38          <DataType>Number</DataType>
39          <Label>order</Label>
40          <FieldType>Number</FieldType>
41        </Field>
42        <Field xsi:type="ns2:DataExtensionField">
43          <CustomerKey>url</CustomerKey>
44          <Name>url</Name>
45          <DataType>Text</DataType>
46          <Label>url</Label>
47          <MaxLength>1000</MaxLength>
48          <IsNillable>true</IsNillable>
49          <IsPrimaryKey>false</IsPrimaryKey>
50          <FieldType>Text</FieldType>
51        </Field>
52        <Field xsi:type="ns2:DataExtensionField">
53          <CustomerKey>time</CustomerKey>
54          <Name>time</Name>
55          <DataType>Date</DataType>
56          <Label>time</Label>
57          <IsNillable>true</IsNillable>
58          <IsPrimaryKey>false</IsPrimaryKey>
59          <FieldType>Date</FieldType>
60        </Field>
61      </Fields>
62    </Objects>
63  </CreateRequest>
64</soapenv:Body>

Create a Data Extension that uses Different Field Types

This sample SOAP envelope includes an example of data extension field types.

1<soapenv:Body>
2  <CreateRequest xmlns="http://exacttarget.com/wsdl/partnerAPI">
3    <Options />
4    <Objects xsi:type="DataExtension">
5      <PartnerKey xsi:nil="true" />
6      <ObjectID xsi:nil="true" />
7      <Name>FieldTypeTest</Name>
8      <IsSendable>false</IsSendable>
9      <Fields>
10        <Field>
11          <Name>EmailAddress_type</Name>
12          <FieldType>EmailAddress</FieldType>
13          <IsPrimaryKey>true</IsPrimaryKey>
14          <IsRequired>true</IsRequired>
15        </Field>
16        <Field>
17          <Name>Text_type</Name>
18          <FieldType>Text</FieldType>
19          <IsRequired>false</IsRequired>
20        </Field>
21        <Field>
22          <Name>Date_type</Name>
23          <FieldType>Date</FieldType>
24          <DefaultValue>getdate()</DefaultValue>
25          <IsRequired>true</IsRequired>
26        </Field>
27        <Field>
28          <Name>Decimal_type</Name>
29          <FieldType>Decimal</FieldType>
30          <IsRequired>true</IsRequired>
31          <Precision>10</Precision>
32          <Scale>2</Scale>
33        </Field>
34        <Field>
35          <Name>Boolean_type</Name>
36          <FieldType>Boolean</FieldType>
37          <DefaultValue>true</DefaultValue>
38          <IsRequired>true</IsRequired>
39        </Field>
40        <Field>
41          <Name>Number_type</Name>
42          <FieldType>Number</FieldType>
43          <IsRequired>false</IsRequired>
44        </Field>
45        <Field>
46          <Name>Phone_type</Name>
47          <FieldType>Phone</FieldType>
48          <IsRequired>false</IsRequired>
49        </Field>
50        <Field>
51          <Name>Locale_type</Name>
52          <FieldType>Locale</FieldType>
53          <IsRequired>false</IsRequired>
54        </Field>
55      </Fields>
56      <CustomerKey>FieldTypeTest</CustomerKey>
57    </Objects>
58  </CreateRequest>
59</soapenv:Body>

Create a Data Extension with Row-Based Data Retention

This example shows how to create a data extension that uses row-based data retention. In a data extension that uses row-based retention, individual rows are deleted when their ages exceed the specified period.

1<s:Envelope
2  xmlns:s="http://www.w3.org/2003/05/soap-envelope"
3  xmlns:a="http://schemas.xmlsoap.org/ws/2004/08/addressing"
4  xmlns:u="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
5  <s:Header>
6    <a:Action s:mustUnderstand="1">Create</a:Action>
7    <a:To s:mustUnderstand="1">https://YOUR_SUBDOMAIN.soap.marketingcloudapis.com/Service.asmx</a:To>
8    <fueloauth xmlns="http://exacttarget.com">YOUR_ACCESS_TOKEN</fueloauth>
9  </s:Header>
10  <s:Body
11    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
12    xmlns:xsd="http://www.w3.org/2001/XMLSchema">
13    <CreateRequest xmlns="http://exacttarget.com/wsdl/partnerAPI">
14      <Objects xsi:type="DataExtension">
15        <Client>
16          <ID>987654</ID>
17        </Client>
18        <CustomerKey>c7b0df2e-e34a-11ef-a842-325096b39f69</CustomerKey>
19        <Name>DE with Row-Based Retention</Name>
20        <IsSendable>true</IsSendable>
21        <SendableDataExtensionField>
22          <CustomerKey>SubscriberKey</CustomerKey>
23          <Name>SubscriberKey</Name>
24          <FieldType>Text</FieldType>
25        </SendableDataExtensionField>
26        <SendableSubscriberField>
27          <Name>Subscriber Key</Name>
28          <Value></Value>
29        </SendableSubscriberField>
30        <DataRetentionPeriodLength>48</DataRetentionPeriodLength>
31        <DataRetentionPeriod>Days</DataRetentionPeriod>
32        <RowBasedRetention>true</RowBasedRetention>
33        <Fields>
34          <Field>
35            <CustomerKey>SubscriberKey</CustomerKey>
36            <Name>SubscriberKey</Name>
37            <FieldType>Text</FieldType>
38            <MaxLength>50</MaxLength>
39            <IsRequired>true</IsRequired>
40            <IsPrimaryKey>true</IsPrimaryKey>
41          </Field>
42          <Field>
43            <CustomerKey>First_Name</CustomerKey>
44            <Name>First_Name</Name>
45            <FieldType>Text</FieldType>
46            <MaxLength>50</MaxLength>
47            <IsRequired>false</IsRequired>
48            <IsPrimaryKey>false</IsPrimaryKey>
49          </Field>
50          <Field>
51            <CustomerKey>Last_Name</CustomerKey>
52            <Name>Last_Name</Name>
53            <FieldType>Text</FieldType>
54            <MaxLength>50</MaxLength>
55            <IsRequired>false</IsRequired>
56            <IsPrimaryKey>false</IsPrimaryKey>
57          </Field>
58          <Field>
59            <CustomerKey>Email</CustomerKey>
60            <Name>Email</Name>
61            <FieldType>EmailAddress</FieldType>
62            <IsRequired>false</IsRequired>
63            <IsPrimaryKey>false</IsPrimaryKey>
64          </Field>
65          <Field>
66            <CustomerKey>Rewards_Points</CustomerKey>
67            <Name>Rewards_Points</Name>
68            <FieldType>Number</FieldType>
69            <IsRequired>false</IsRequired>
70            <IsPrimaryKey>false</IsPrimaryKey>
71          </Field>
72        </Fields>
73      </Objects>
74    </CreateRequest>
75  </s:Body>
76</s:Envelope>

Create a Data Extension with Object-Based Data Retention

This example shows how to create a data extension that uses object-based data retention. In a data extension that uses object-based retention, all of the content in the data extension is deleted after the specified period. Optionally, you can delete the data extension itself (rather than just the data within it) at the end of the retention period by setting DeleteAtEndOfRetentionPeriod to false. If you set this to true, only the content is deleted after the specified period, but the data extension persists.

Compared to the row-based retention code example, this example omits the RowBasedRetention property and adds the ResetRetentionPeriodOnImport and DeleteAtEndOfRetentionPeriod properties.

1<s:Envelope
2  xmlns:s="http://www.w3.org/2003/05/soap-envelope"
3  xmlns:a="http://schemas.xmlsoap.org/ws/2004/08/addressing"
4  xmlns:u="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
5  <s:Header>
6    <a:Action s:mustUnderstand="1">Create</a:Action>
7    <a:To s:mustUnderstand="1">https://YOUR_SUBDOMAIN.soap.marketingcloudapis.com/Service.asmx</a:To>
8    <fueloauth xmlns="http://exacttarget.com">YOUR_ACCESS_TOKEN</fueloauth>
9  </s:Header>
10  <s:Body
11    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
12    xmlns:xsd="http://www.w3.org/2001/XMLSchema">
13    <CreateRequest xmlns="http://exacttarget.com/wsdl/partnerAPI">
14      <Objects xsi:type="DataExtension">
15        <Client>
16          <ID>987654</ID>
17        </Client>
18        <CustomerKey>c7b0df2e-e34a-11ef-a842-325096b39f69</CustomerKey>
19        <Name>DE with Object-Based Retention</Name>
20        <IsSendable>true</IsSendable>
21        <SendableDataExtensionField>
22          <CustomerKey>SubscriberKey</CustomerKey>
23          <Name>SubscriberKey</Name>
24          <FieldType>Text</FieldType>
25        </SendableDataExtensionField>
26        <SendableSubscriberField>
27          <Name>Subscriber Key</Name>
28          <Value></Value>
29        </SendableSubscriberField>
30        <DataRetentionPeriodLength>48</DataRetentionPeriodLength>
31        <DataRetentionPeriod>Days</DataRetentionPeriod>
32        <ResetRetentionPeriodOnImport>true</ResetRetentionPeriodOnImport>
33        <DeleteAtEndOfRetentionPeriod>false</DeleteAtEndOfRetentionPeriod>
34        <Fields>
35          <Field>
36            <CustomerKey>SubscriberKey</CustomerKey>
37            <Name>SubscriberKey</Name>
38            <FieldType>Text</FieldType>
39            <MaxLength>50</MaxLength>
40            <IsRequired>true</IsRequired>
41            <IsPrimaryKey>true</IsPrimaryKey>
42          </Field>
43          <Field>
44            <CustomerKey>First_Name</CustomerKey>
45            <Name>First_Name</Name>
46            <FieldType>Text</FieldType>
47            <MaxLength>50</MaxLength>
48            <IsRequired>false</IsRequired>
49            <IsPrimaryKey>false</IsPrimaryKey>
50          </Field>
51          <Field>
52            <CustomerKey>Last_Name</CustomerKey>
53            <Name>Last_Name</Name>
54            <FieldType>Text</FieldType>
55            <MaxLength>50</MaxLength>
56            <IsRequired>false</IsRequired>
57            <IsPrimaryKey>false</IsPrimaryKey>
58          </Field>
59          <Field>
60            <CustomerKey>Email</CustomerKey>
61            <Name>Email</Name>
62            <FieldType>EmailAddress</FieldType>
63            <IsRequired>false</IsRequired>
64            <IsPrimaryKey>false</IsPrimaryKey>
65          </Field>
66          <Field>
67            <CustomerKey>Rewards_Points</CustomerKey>
68            <Name>Rewards_Points</Name>
69            <FieldType>Number</FieldType>
70            <IsRequired>false</IsRequired>
71            <IsPrimaryKey>false</IsPrimaryKey>
72          </Field>
73        </Fields>
74      </Objects>
75    </CreateRequest>
76  </s:Body>
77</s:Envelope>

Create a Data Extension that Includes a Date Value in a Date-type Field

When you create a data extension field that contains a date value, pass the time in 24-hour format.

1<CreateRequest xmlns="http://exacttarget.com/wsdl/partnerAPI">
2  <Options/>
3  <Objects xsi:type="DataExtensionObject">
4    <ObjectID xsi:nil="true"/>
5    <CustomerKey>DateFormatTest</CustomerKey>
6    <Properties>
7      <Property>
8        <Name>DateField</Name>
9        <Value><![CDATA[01/02/2024 16:00:00]]></Value>
10      </Property>
11    </Properties>
12  </Objects>
13</CreateRequest>