Add Subscribers to a List

You can use SOAP API to add subscribers to a subscriber, publication, or suppression list. You can add a subscriber to a list when you create their subscriber record, or you can update an existing subscriber to add them to a list.

If your use case requires you to add a batch of subscribers to a list, start by performing an Update operation. After that, perform a Create operation to create the contacts that weren’t found during the Update operation.

Sample SOAP Envelopes

Use these sample SOAP envelopes as guidelines for creating requests that suit your use case.

Create a Subscriber and Add to List

This example shows how to create a subscriber and add that subscriber to a list.

1<?xml version="1.0" encoding="UTF-8"?>
2<s:Envelope
3    xmlns:s="http://www.w3.org/2003/05/soap-envelope"
4    xmlns:a="http://schemas.xmlsoap.org/ws/2004/08/addressing"
5    xmlns:u="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
6    <s:Header>
7        <a:Action s:mustUnderstand="1">Create</a:Action>
8        <a:To s:mustUnderstand="1">
9            https://YOUR_SUBDOMAIN.soap.marketingcloudapis.com/Service.asmx
10        </a:To>
11        <fueloauth xmlns="http://exacttarget.com">YOUR_ACCESS_TOKEN</fueloauth>
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        <CreateRequest xmlns="http://exacttarget.com/wsdl/partnerAPI">
17            <Objects xsi:type="Subscriber">
18                <CustomerKey>dangelo.cunningham@example.com</CustomerKey>
19                <EmailAddress>dangelo.cunningham@example.com</EmailAddress>
20                <Lists>
21                    <ID>99887766</ID>
22                </Lists>
23                <Attributes>
24                    <Name>First Name</Name>
25                    <Value>D'Angelo</Value>
26                </Attributes>
27                <Attributes>
28                    <Name>Last Name</Name>
29                    <Value>Cunningham</Value>
30                </Attributes>
31                <Attributes>
32                    <Name>Company</Name>
33                    <Value>DreamHouse Realty</Value>
34                </Attributes>
35            </Objects>
36        </CreateRequest>
37    </s:Body>
38</s:Envelope>

The body of the SOAP response contains information about the subscriber that you created and the list that they were added to.

1<soap:Body>
2    <CreateResponse xmlns="http://exacttarget.com/wsdl/partnerAPI">
3      <Results>
4        <StatusCode>OK</StatusCode>
5        <StatusMessage>Created Subscriber.</StatusMessage>
6        <OrdinalID>0</OrdinalID>
7        <NewID>1106974556</NewID>
8        <Object xsi:type="Subscriber">
9          <PartnerKey xsi:nil="true" />
10          <ID>1106974556</ID>
11          <ObjectID xsi:nil="true" />
12          <CustomerKey>dangelo.cunningham@example.com</CustomerKey>
13          <EmailAddress>dangelo.cunningham@example.com</EmailAddress>
14          <Attributes>
15            <Name>First Name</Name>
16            <Value>D'Angelo</Value>
17          </Attributes>
18          <Attributes>
19            <Name>Last Name</Name>
20            <Value>Cunningham</Value>
21          </Attributes>
22          <Attributes>
23            <Name>Company</Name>
24            <Value>DreamHouse Realty</Value>
25          </Attributes>
26          <Lists>
27            <PartnerKey xsi:nil="true" />
28            <ID>99887766</ID>
29            <ObjectID xsi:nil="true" />
30          </Lists>
31        </Object>
32      </Results>
33      <RequestID>2206d1db-0629-4a9d-8529-8036c06943a9</RequestID>
34      <OverallStatus>OK</OverallStatus>
35    </CreateResponse>
36  </soap:Body>

Add Existing Subscriber to a List

Add an existing subscriber to a list by updating the subscriber record. This sample request updates the List.ID property for a specified contact.

1<?xml version="1.0" encoding="UTF-8"?>
2<s:Envelope
3    xmlns:s="http://www.w3.org/2003/05/soap-envelope"
4    xmlns:a="http://schemas.xmlsoap.org/ws/2004/08/addressing"
5    xmlns:u="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
6    <s:Header>
7        <a:Action s:mustUnderstand="1">Update</a:Action>
8        <a:To s:mustUnderstand="1">
9            https://YOUR_SUBDOMAIN.soap.marketingcloudapis.com/Service.asmx
10        </a:To>
11        <fueloauth xmlns="http://exacttarget.com">YOUR_ACCESS_TOKEN</fueloauth>
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        <UpdateRequest xmlns="http://exacttarget.com/wsdl/partnerAPI">
17            <Objects xsi:type="Subscriber">
18                <CustomerKey>dangelo.cunningham@example.com</CustomerKey>
19                <Lists>
20                    <ID>33445566</ID>
21                </Lists>
22            </Objects>
23        </UpdateRequest>
24    </s:Body>
25</s:Envelope>

The response body includes information about the updated subscriber.

1<soap:Body>
2    <UpdateResponse xmlns="http://exacttarget.com/wsdl/partnerAPI">
3      <Results>
4        <StatusCode>OK</StatusCode>
5        <StatusMessage>Updated Subscriber.</StatusMessage>
6        <OrdinalID>0</OrdinalID>
7        <Object xsi:type="Subscriber">
8          <PartnerKey xsi:nil="true" />
9          <ID>1234567890</ID>
10          <ObjectID xsi:nil="true" />
11          <CustomerKey>dangelo.cunningham@example.com</CustomerKey>
12          <Lists>
13            <PartnerKey xsi:nil="true" />
14            <ID>33445566</ID>
15            <ObjectID xsi:nil="true" />
16          </Lists>
17        </Object>
18      </Results>
19      <RequestID>94e3b699-0501-443a-82e0-c717154f5c1d</RequestID>
20      <OverallStatus>OK</OverallStatus>
21    </UpdateResponse>
22  </soap:Body>