Retrieve a Subscriber

This page contains information about retrieving a subscriber via the SOAP API.

Why Retrieve a Subscriber 

By retrieving a subscriber, you can view the applicable information for that subscriber. You can include this information in a profile center or in your own application as part of a screen that displays subscriber information.

How To Retrieve a Subscriber 

Use the sample code below as a model to create your own API calls.

Sample .NET Code 

1using System;
2using System.Configuration;
3using System.Data;
4using System.Linq;
5using System.Web;
6using System.Web.Security;
7using System.Web.UI;
8using System.Web.UI.HtmlControls;
9using System.Web.UI.WebControls;
10using System.Web.UI.WebControls.WebParts;
11using System.Xml.Linq;
12using etAPI;
13public partial class RetrieveSubscriber : System.Web.UI.Page
14{
15    //Global Variables
16    private SoapClient client = new SoapClient();
17    protected void Page_Load(object sender, EventArgs e)
18    {
19        //Authenticate
20        client.ClientCredentials.UserName.UserName = System.Configuration.ConfigurationSettings.AppSettings["wsUserName"];
21        client.ClientCredentials.UserName.Password = System.Configuration.ConfigurationSettings.AppSettings["wsPassword"];
22        if (!IsPostBack)
23        {
24        }
25    }
26    protected void btnSubmit_Click(object sender, EventArgs e)
27    {
28        try
29        {
30            //Retrieve Subscriber
31            //Local variables
32            APIObject[] Results;
33            String requestID;
34            String status;
35            // Instantiate the retrieve request
36            RetrieveRequest rr = new RetrieveRequest();
37            rr.ObjectType = "Subscriber";//required
38            // Setting up a simple filter
39            SimpleFilterPart sf = new SimpleFilterPart();
40            sf.SimpleOperator = SimpleOperators.equals;
41            sf.Property = "SubscriberKey";
42            sf.Value = new String[] { "0613d278-888e-4825-b796-74a21a071391" };
43            //Add Filter
44            rr.Filter = sf;
45            rr.Properties = new string[] { "ID", "CreatedDate", "Client.ID", "EmailAddress", "SubscriberKey", "UnsubscribedDate", "Status", "EmailTypePreference" };//required //Adding "ID" triggers all of the Subscriber Attributes to be returned
46            status = client.Retrieve(rr, out requestID, out Results);
47            lblMessage.Text += "<br/>Total Records: " + Results.Length;
48        }
49        catch (Exception ex)
50        {
51            lblMessage.Text += ex.Message;
52            lblMessage.Text += "<br/>";
53        }
54    }
55}

Sample Java Code (Axis 1.4) 

1public void testRetrieveSubcriberByKey() throws RemoteException {
2    Soap stub = init();
3    RetrieveRequest request = new RetrieveRequest();
4    request.setObjectType("Subscriber");
5    String[] props = { "ID", "SubscriberKey };
6    request.setProperties(props);
7    request.setQueryAllAccounts(true); //scans all sub-Accounts of parent-Account
8    //Query filter using Simplefilter.
9    SimpleFilterPart filterPart = new SimpleFilterPart();
10    filterPart.setProperty("SubscriberKey");
11    String[] values = {"acruz@example.com"};
12    filterPart.setValue(values);
13    filterPart.setSimpleOperator(SimpleOperators.equals);
14    request.setFilter(filterPart);
15    RetrieveRequestMsg requestMsg = new RetrieveRequestMsg();
16    requestMsg.setRetrieveRequest(request);
17    RetrieveResponseMsg responseMsg = stub.retrieve(requestMsg);  //Soap call to request Account object
18    assertNotNull(responseMsg);
19    assertNotNull(responseMsg.getResults(0));
20    Subscriber sub = (Subscriber) responseMsg.getResults(0);
21    if(sub!=null && sub.getAttributes()!=null && sub.getAttributes().length >0){
22        Attribute[] a = sub.getAttributes();
23        for(int i=0; i< sub.getAttributes().length-1; i ++) {
24        Attribute a1 = sub.getAttributes(i);
25        System.out.println("Name :: " + a1.getName() + "  Value :: " + a1.getValue());
26        }
27    }

Sample SOAP Envelope - Retrieve Subscribers 

In this example, the request includes a filter to retrieve subscribers by the CreatedDate.

1<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
2   <soapenv:Header>
3      <wsse:Security soapenv:mustUnderstand="1" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
4         <wsse:UsernameToken wsu:Id="UsernameToken-32259181" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
5            <wsse:Username>XXXXX</wsse:Username>
6            <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">XXXXX</wsse:Password>
7         </wsse:UsernameToken>
8      </wsse:Security>
9   </soapenv:Header>
10   <soapenv:Body>
11      <RetrieveRequestMsg xmlns="http://exacttarget.com/wsdl/partnerAPI">
12         <RetrieveRequest>
13            <ObjectType>Subscriber</ObjectType>
14            <Properties>CreatedDate</Properties>
15            <Properties>Client.ID</Properties>
16            <Properties>EmailAddress</Properties>
17            <Properties>SubscriberKey</Properties>
18            <Properties>Status</Properties>
19            <Properties>UnsubscribedDate</Properties>
20            <Properties>EmailTypePreference</Properties>
21            <Filter xsi:type="SimpleFilterPart">
22               <Property>CreatedDate</Property>
23               <SimpleOperator>greaterThan</SimpleOperator>
24               <DateValue>2012-01-04T10:19:00</DateValue>
25            </Filter>
26         </RetrieveRequest>
27      </RetrieveRequestMsg>
28   </soapenv:Body>
29</soapenv:Envelope>