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);
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:
|
includeTechnologyData |
boolean | No | Includes the following data in the readOnlyContactData object:
|
includeRFMData |
boolean | No | Includes the following data in the readOnlyContactData object:
|
includeEngagementData |
boolean | No | Includes the following data in the readOnlyContactData object:
|
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