Over the past few weeks, we have looked at how to login to the new API and how to filter result sets. Now we are going to take a closer look at how to work with the updated readContacts function, and see what new information is provided to us in the result. As was mentioned in Filtering Result Sets, all of the read functions in version 4 of the Bronto API, including readContacts, have the option to include a filter based on selected criteria. You can find out what criteria are available by looking at the contactFilter
Using the contactFilter
Lets say you were interested in all active contacts created after June 1, 2009 at 6am ET. You would create a SOAP message like:
<soapenv:Envelope xmlns:soapenv=”http://schemas.xmlsoap.org/soap/envelope/” xmlns:v4=”http://api.bronto.com/v4″>
<soapenv:Header>
<v4:sessionHeader>
<sessionId></sessionId>
</v4:sessionHeader>
</soapenv:Header>
<soapenv:Body>
<v4:readContacts>
<filter>
<type>AND</type>
<status>active</status>
<created>
<operator>After</operator>
<value>2009-06-01T06:00:00-05:00</value>
</created>
</filter>
<includeLists>false</includeLists>
<fields></fields>
<pageNumber>1</pageNumber>
</v4:readContacts>
</soapenv:Body>
</soapenv:Envelope>
Using the readContacts function, you can also filter on criteria such as email address, modified date, which lists or segments the contacts are on, message format preference, source and customSource. You can also specify if the contacts should match all or any of the filter criteria by defining the filter type as an AND or an OR.
Aggregate Information Returned by the readContact Function
The updated readContact function also returns aggregate information for each contact. The results now include numSends, numBounces, numOpens, numClicks, numConversions and conversionAmount. These metrics tell you the total number of deliveries sent to a contact, the number of times deliveries sent to a contact that have bounced, the number of opens recorded for the contact, the number of clicks recorded for the contact, the total number of times a contact has converted, and the total amount of any conversions. This is in addition to all the other information about a contact that is returned.
Let us know if you have any suggestions or questions in the comments section below!
Andrew Kanes
Support Engineer at Bronto
Related posts:
- Filtering Result Sets Did you know that all of the read functions available...
- Token, Token, Who Wants a Token? Another new feature of version 4 of the Bronto API...
- May I Have Another User As part of version 4 of the Bronto API, we...
Follow Bronto on Twitter
{ 2 comments… read them below or add one }
How do we filter a delivery’s results (clicks and opens) by contact, so we can determine how a message has performed with a particular contact (or how a particular contact has responded to a message?)
Hi Bilal -
That feature is not currently available in version 4 of the API, but should be coming in the next few months.
Regards -
Andrew