readContacts

The readContacts function attempts to return contacts that match all of the given filters. The specified attributes of the contacts are returned for each matching contact.

Results

The readContacts function may return 1 or many contact objects. See the documentation on the contactObject for a list of the data fields that could potentially be returned. For more information on result limits and paging, see How To Read Objects.

Note: The data fields returned depend on the type of data you ask for in your request.

Syntax

contactObject[] contacts = bApi.readContacts( filter contactFilter, 
	      includeLists, fields, pageNumber, includeSMSKeywords, includeGeoIPData, 
	      includeTechnologyData, includeRFMData);

readContacts Parameters

Name Type Required Description
filter contactFilter Yes The filter used to return a specific contact.
includeLists boolean No The lists, referenced by id, that the contact belongs to.
fields string, array No The contact field(s) that you want returned. Fields are referenced by their unique id. You can pass in a single id as a string, or multiple ids in an array.
pageNumber int Yes Retrieves the next “batch” of objects as the value specified increases from 1. In order to obtain an entire set of objects for a given call, you should increase the number value assigned to pageNumber until no more objects are returned.
includeSMSKeywords boolean No The SMS keywords the contact is subscribed to.
includeGeoIPData boolean No Includes the following data in the readOnlyContactData object:
  • geoIPCity
  • geoIPStateRegion
  • geoIPZip
  • geoIPCountry
  • geoIPCountryCode
includeTechnologyData boolean No Includes the following data in the readOnlyContactData object:
  • primaryBrowser
  • mobileBrowser
  • primaryEmailClient
  • mobileEmailClient
  • operatingSystem
includeRFMData boolean No Includes the following data in the readOnlyContactData object:
  • firstOrderDate
  • lastOrderDate
  • lastOrderTotal
  • totalOrders
  • totalRevenue
  • averageOrderValue
includeEngagementData boolean No Includes the following data in the readOnlyContactData object:
  • lastDeliveryDate
  • lastOpenDate
  • lastClickDate
customSource string No A user-defined source used to indicate where the contact came from.

PHP Code Example

<?php 
/** This example will log into your account and try to read the * contacts 'john.doe@example.com' and 
 * 'jane.doe@example.com' in two ways: first, by specifically matching on those email addresses, 
 * and then second by matching on any contact whose email address contains 'doe@example.com'. 
 * It also prints the matched contacts' status. */ 

 $client = new SoapClient('https://api.bronto.com/v4?wsdl', array('trace' => 1, 
                                 'features' => SOAP_SINGLE_ELEMENT_ARRAYS));
 
try {
  $token = "YOUR_TOKEN_HERE";
 
  print "logging in\n";
  $sessionId = $client->login(array('apiToken' => $token))->return;
 
  $session_header = new SoapHeader("http://api.bronto.com/v4",
                   'sessionHeader',
                   array('sessionId' => $sessionId));
  $client->__setSoapHeaders(array($session_header));
 
  // set up a filter to read contacts and match on either of two email addresses
  $filter = array('type' => 'OR',
          'email' => array(array('operator' => 'EqualTo',
                       'value' => 'john.doe@example.com'
                       ),
                   array('operator' => 'EqualTo',
                       'value' => 'jane.doe@example.com'
                       )
                   ),
          ); 
 
  print "reading contacts with equalto filter\n";
  $contacts = $client->readContacts(array('pageNumber' => 1,
                      'includeLists' => false,
                      'filter' => $filter,
                      )
                    )->return;
 
  // print matching contact email addresses
  foreach ($contacts as $contact) {
    print $contact->email . ': ' . $contact->status . "\n";
  }
 
 
  // set up a filter to read contacts and match on either of two email addresses
  $filter = array('email' => array(array('operator' => 'Contains',
                       'value' => 'doe@example.com'
                       ),
                   ),
          ); 
 
  print "reading contacts with contains filter\n";
  $contacts = $client->readContacts(array('pageNumber' => 1,
                      'includeLists' => false,
                      'filter' => $filter,
                      )
                    )->return;
 
  // print matching contact email addresses
  foreach ($contacts as $contact) {
    print $contact->email . ': ' . $contact->status . "\n";
  }
 
} catch (Exception $e) {
  print "uncaught exception\n";
  print_r($e);
}

cURL Example

Before you can call readContacts using curl, you will need to first call login to retrieve a session ID.

Create a file named Login.xml with the following XML:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:v4="http://api.bronto.com/v4">
   <soapenv:Header/>
   <soapenv:Body>
      <v4:login>
         <apiToken>YOUR-API-TOKEN</apiToken>
      </v4:login>
   </soapenv:Body>
</soapenv:Envelope>
Make the following request from the command line:
curl https://api.bronto.com/v4?wsdl -H 'Content-Type: text/xml; charset=UTF-8' -d @Login.xml

Copy the returned session ID.

Create a new file named readContacts.xml with the following XML:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:v4="http://api.bronto.com/v4">
   <soapenv:Header>
      <v4:sessionHeader>
      <sessionId>RETURNED SESSION ID</sessionId>
      </v4:sessionHeader>
   </soapenv:Header>
   <soapenv:Body>
      <v4:readContacts>
         <!--Optional:-->
         <filter>
            <!--Optional:-->
            <type>OR</type>
            <email>
               <!--Optional:-->
               <operator>EqualTo</operator>
               <!--Optional:-->
               <value>EMAIL ADDRESS</value>
            </email>
            <!--Zero or more repetitions:-->
         </filter>
         <!--Optional:-->
         <includeLists>false</includeLists>
         <!--Zero or more repetitions:-->
         <pageNumber>1</pageNumber>
      </v4:readContacts>
   </soapenv:Body>
</soapenv:Envelope>
Make the following request from the command line:
curl https://api.bronto.com/v4?wsdl -H 'Content-Type: text/xml; charset=UTF-8' -d @readContacts.xml