readContacts

Overview

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 fields you want returned that the contact belongs to. 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.

Examples

To easily copy the code below, move your mouse over the top right corner of the code example. Four buttons will appear. Click View Source or Copy To Clipboard to copy the code below in plain text format without line numbers.

Code Samples

<?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);
}


Was this article helpful?

Not HelpfulHelpful (-9 rating, 13 votes)
Loading...

We welcome your feedback!

Please let us know how this article could be improved.
*Name and Email are optional fields.