Viewing The Contacts On A Segment Using The API

If you are using the API and want a quick way to find out which contacts are on a particular segment, this post is for you.

Getting The Segment ID: Manually

There are actually two ways you can obtain an ID for a segment. The first way is a manual process. You can login in to the application, go to Contacts->Segments, and click on the name of the segment you want to obtain the ID for. You will be brought to the overview page for that segment. In the bottom right corner of the page, you can obtain the segment ID.

Getting The Segment ID: Programmatically

The quickest way to obtain an ID for a segment is to do so using the API. All you need to do is call readSegments. The example code below will show you how to do this using the name of the segment.

Viewing The Contacts On The Segment

The script below makes two calls to the API. First, it calls readSegments to obtain a segment ID. Second, it uses the segment ID as a filter when calling readContacts.

<?php
/**
 * This example will read a segment from your account whose name
 * matches a given string. Using the segment ID that is returned,
 * the script will call readContacts using the segmentID as
 * a filter.
 */

$client = new SoapClient('https://api.bronto.com/v4?wsdl',
                                         array('trace' => 1,
                                                 'features' => SOAP_SINGLE_ELEMENT_ARRAYS));
setlocale(LC_ALL, 'en_US');

try {
	// Be sure to replace the placeholder text with a real API token!
	$token = "SOME EXAMPLE TOKEN";

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

	// Read data for a segment matching the following name.
	// Be sure to replace the value with the name of the segment
	// you want to obtain an ID for!
	$filter = array('name' => array('operator' => 'EqualTo',
							  'value' => 'SOME SEGMENT NAME'
							)
					);

	print "reading segments\n";
	$segments = $client->readSegments(array('pageNumber' => 1,
									      'filter' => $filter,
									)
								 )->return;

	// print matching results
	foreach ($segments as $segment) {
		print "Segment name: " . $segment->name . "; id: " . $segment->id . "\n";

		// set up a filter to read contacts based on the segment ID
		$filter = array('type' => 'AND',
				       'segmentId' => $segment->id);

	print "reading contacts with that match the given segment ID\n";
		$contacts = $client->readContacts(array('pageNumber' => 1,
										  'includeLists' => false,
										  'filter' => $filter,
										)
									)->return;

		// print matching contact objects
                    print_r($contacts);

	} // End foreach

} catch (Exception $e) {
	print "uncaught exception\n";
	print_r($e);
}
?>

What Data Am I Getting Back?

The script above will return the name and ID of each segment object that matches the given filter in the readSegments call. For each segment object, a readContacts call will be will made and you will get back an array of contact objects corresponding to contacts who are on the segment. Of course, you don't have to return the entire contact object. You can choose to filter the contact object and return only the data you need. Along similar lines, you don't have to return all the contact objects associated with segment. Optionally, you can further filter the contacts returned in the readContacts call. For example:

// set up a filter to read contacts. Here we want contacts
// on a specific segment who also have the text 'gmail'
// in there email address
$filter = array('type' => 'AND',
					'segmentId' => $segment->id,
					'email' => array('operator' => 'Contains',
								  'value' => 'gmail'));

I hope this post has given you a better idea of how you can obtain data for contacts that belong to a specific segment. If you have any questions, please leave them in the comments section below. John Gunther Technical Writer/eLearning Specialist Editor of Brontoversity