legacy.retrieve_active

‹ BACK TO API PAGE


Description

This method allows you to retrieve information stored in your subscriber database on any active subscriber. This method is normally used to retrieve profile data for an individual subscriber in realtime.

Asynchronous Option
When using this method to retrieve profile data for a large list of subscribers, it is recommended that you use the asynchronous option. This option will enable your system to continue working and not time out waiting for a response from BlueHornet while it generates the subscriber data.

Retrieving subscriber data asynchronously is a three-step process:

  1. Initiate the request to retrieve subscriber profile data and set the <asynchronous> input parameter to '1'.
  2. Query the job engine via utilities.getTasks to know when the subscriber profile data is available for download
  3. Retrieve the subscriber profile data via utilities.getFile.

When this method's input parameters includes the <asynchronous> input parameter set to '1', it will return a task ID corresponding to the asynchronous job assigned to collect the subscriber profile data.

Query the job queue using the utilities.getTasks method call, passing in the task ID in the <task_id> input element. This method will then return the most current status of the specified job. When the returned status is COMPLETE, the method's <task_response> parameter will include the file path to the subscriber profile data file.

The file path becomes the input parameter to the utilities.getFile method which will then return the full subscriber profile data in XML format.

Searching for Fields with Null Values
This method will also let you search for records with null values in the standard fields in the following list:

  • <email>
  • <external_id>
  • <firstname>
  • <lastname>
  • <city>
  • <state>
  • <postal_code>
  • <country>
  • <phone_hm>
  • <phone_wk>
  • <fax>

If the string ::null:: is provided in any of the above input elements, then this method will return all records with null values for their corresponding fields.

Usage Notes

  1. This method cannot be combined with any other method call within the same POST command.
  2. This method only supports the XML response type. The PHP response type is not available for this method.

Arguments

Field Description Field Type Required Example
email Email address to retrieve data on a single subscriber. Omit this element, the <external_id> element, and the <contact_id> element to retrieve data on all subscribers matching other criteria. The percentage symbol (%) may be used as a wildcard. string Conditional; required only if no other selection criteria are provided in the POST message. jsmith@​example.com or %@example.com
return_count Specifies whether the the response will only include a count of active subscribers where:
  • 0 – include subscriber data specified (default)
  • 1 – return just a count of active subscribers matching the selection criteria
boolean No 1
external_id An identifier defined within an external system used to retrieve data on a single subscriber. Omit this element, the <email> element, and the <contact_id> element to retrieve data on all subscribers matching other criteria. The percentage symbol (%) may be used as a wildcard.If this element is included with the <email> element, then the search for the subscriber record will be based on both the external_id and the email address. string
64 characters max
No ABC123DEF456
contact_id The contact ID (BlueHornet's internal ID for a subscriber record) to retrieve data on a single subscriber. Searching a subscriber record by contact_id cannot be paired with any other input parameter (e.g. email). If the <contact_id> element is included in the input, then search will be done by contact ID and any other input parameter will be ignored.Omit this element, the <email> element, and the <external_id> element to retrieve data on all subscribers matching other criteria. Number No 12345678
firstname First name on which to base result search string No John
lastname Last name on which to base result search string No Smith
date_search_type No longer used; is replaced by <date_joined_on>, <date_joined_start> and <date_joined_end>. string N/A N/A
city City name string No Miami
state State or province string No FL
postal_code Postal code string No 92110
country Country name or ISO code string No US
phone_hm Home phone number string No 619-295-1856
phone_wk Work phone number string No 619-295-1856
fax Fax number string No 619-295-1856
date_modified_on (Formerly known as <date_modified>) Date when the subscribers' profiles were last modified. The date must be in YYYY-MM-DD format. If <date_modified_on> is provided along with <date_modified_start> and <date_modified_end> then subscribers are selected solely upon <date_modified_on>. date No 2010-06-05
date_modified_start Starting date range for selecting records by subscriber record last modified date.
Date must be in YYYY-MM-DD format.
date No 2013-01-01
date_modified_end Ending date range for selecting records by subscriber record last modified date.
Date must be in YYYY-MM-DD format.
date No 2013-05-17
date_joined_on (Formerly known as <optin_date>) The date when the subscribers were added to the database. The date must be in YYYY-MM-DD format. If <date_joined_on> is provided along with <date_joined_start> and <date_joined_end> then subscribers are selected solely upon <date_joined_on>. string No 2010-01-31
date_joined_start Date range for selecting records by subscriber opt-in date starting on the date provided.
Date must be in YYYY-MM-DD format.
date No 2013-01-05
date_joined_end Date range for selecting records by subscriber opt-in date ending on the date provided.
Date must be in YYYY-MM-DD format.
date No 2013-05-17
bounced No longer used; is replaced by <bounce_status>. A boolean value that when set to '1' indicates finding subscribers that have not received an email because it "bounced" number No 1
bounce_status When provided, will return only records with either valid or invalid bounce status. The valid bounce status types are:
  • valid
  • invalid
string No valid
invalid No longer used; is replaced by <bounce_status>. A boolean value that when set to '1' indicates finding subscribers classified as "invalid" number No 1
valid No longer used; is replaced by <bounce_status>. A boolean value that when set to '1' indicates finding subscribers in which emails sent to them have bounced less than three times over the lifetime of their subscriber records. number No 1
max (Formerly known as <limit_rows>) An integer value that limits the number of subscribers returned in the response message number Conditional; required if <offset> is included in the POSTed message. 100000
offset (Formerly known as <limit_offset>) An integer value that starts the return of subscribers after X number of records. Include <max> to specify a limited set of results. number No 2500
order Set to either "desc" or "asc" to order the subscribers by a certain field as defined in the <orderby> element string No asc
orderby Set to "email" for email (the default), "firstname" for first name, "lastname" for last name, or "edate" for the date the record was added to the subscriber database string No edate
custval{integer}={value} Requests subscribers whose specified custom field equals the specified value where {integer} is the custom field ID to be referenced and {value} is either the string or date value that is stored in this custom field. To view a list of custom fields and their corresponding ID numbers, log in to the application and navigate to Administration > Configure Settings > Account and Segment IDs. Scroll down on the screen to the Custom Fields section to find the custom field name and its corresponding custom field ID. string or date. If date, it must be in the format YYYY-MM-DD No custval8439=fido
groups Requests subscribers that belong to the specified static segments. The value of this element is a comma delimited list of the ID numbers of the static segments to which the subscribers belong. To view a list of static segments and their corresponding ID numbers, log in to the application and navigate to Administration > Configure Settings > Account and Segment IDs. Scroll down on the screen to the Segments section to find the static segment name and its corresponding segment ID. string No 194832,92439
grp_search_type Parameter options include:
  • any – Match subscribers who are in any of the static segments specified within the <groups> field (default)
  • all – Match subscribers who are in all of the specified segments
  • notany- Match subscribers who are not in any of the specified segments
  • notall – Match subscribers who are not in all of the specified segments
string No all
asynchronous Specifies to enable returning of the resource to operate in asynchronous mode where:
  • 0 – operate in synchronous mode, returning the resource in real-time (default)
  • 1 – operate in asynchronous mode
boolean' No 1
mess_id_sent Returns all subscribers sent the specified message. This single parameter replaces the <m_id> and <m_sent> combination.Cannot be combined in the same request with the <mess_id_opened>, <mess_id_delivered>, and <mess_id_bounced> input fields. number No 95009
mess_id_delivered Returns all subscribers that the specified message was successfully delivered. This single parameter replaces the <m_id> and <m_delivered> combination.Cannot be combined in the same request with the <mess_id_bounced> input field. number No 95009
mess_id_opened Returns all subscribers that opened the specified message.Cannot be combined in the same request as the <mess_id_delivered> and <mess_id_bounced> input fields. number No 95009
mess_id_bounced Returns all subscribers that the specified message bounced when sent. This single parameter replaces the <m_id> and <m_bounced> combination.Cannot be combined in the same request as the <mess_id_delivered> input field. number No 95009
m_id No longer used. Is replaced by stand alone parameters for <mess_id_opened>, <mess_id_sent>, < mess_id_delivered>, and <mess_id_bounced>. This value is a message ID. This is identified as the 'id' attribute in the message element (<message id="162224″>) that can be found in the legacy.message_stats method response. When used by itself it will return subscribers who opened the message. number No 12309
m_sent No longer used. Is replaced by stand alone parameters for <mess_id_opened>, <mess_id_sent>, < mess_id_delivered>, and <mess_id_bounced>. A boolean value that when set to 1 and paired with an m_id value, requests all subscribers sent the message identified by <m_id>. number No 1
m_delivered No longer used. Is replaced by stand alone parameters for <mess_id_opened>, <mess_id_sent>, < mess_id_delivered>, and <mess_id_bounced>. A boolean value that when set to 1 and paired with an m_id value, requests all subscribers sent the message identified by m_id that were delivered (did not bounce) number No 1
m_bounced No longer used. Is replaced by stand alone parameters for <mess_id_opened>, <mess_id_sent>, < mess_id_delivered>, and <mess_id_bounced>. A boolean value that when set to 1 and paired with an m_id value, requests all subscribers sent the message identified by m_id that bounced. number No 1
link_id_clicked (Formerly known as <t_id>) Requests all subscribers who have clicked on the given link. This value is a message link ID. It is identified as the 'id'
attribute in the link element (<link id="133710″>) that can be found
in the legacy.message_stats method response.
number No 133710
roi_id Requests all subscribers who have purchase data associated with the given link. This value is a message link ID (the same value as the above t_id). This is identified as the 'id' attribute in the link element (<link id="133710″>) that can be found in the legacy.message_stats method response. number No 133710
basic Specifies that only basic contact information in the response which includes first name, last name, email, number of times emails sent to the subscriber have bounced, and opt-in date in YYYY-MM-DD format where:
  • 0 – do not specify basic contact info (default)
  • 1 – include only basic contact information
boolean No 1
extended Specifies that extended contact information in the response which includes address, city, state, zip code, home phone, work phone, fax, country, and last modified date in YYYY-MM-DD where:
  • 0 – do not specify extended contact info (default)
  • 1 – include extended contact info
boolean No 1
return_groups Specifies whether to include a comma-delimited list of static segment IDs to which each subscriber belongs where:
  • 0 – do not include (default)
  • 1 – include
boolean No 1
custom_fields Specifies whether to include all custom field data to be included in the response message where:
  • 0 – do not include (default)
  • 1 – include
boolean No 1

Response

Field Description Example
manifest This element is the "wrapper" for all subscriber response data elements
count The total number of active subscribers matching the search criteria POSTed in the input parameters. This element will only be returned if the <return_count> element is set to '1' in the input. 230239
contact_data This element is the "wrapper" for individual subscriber response data elements
email The subscriber's email address jsmith@example.com
external_id The subscriber's identifier defined within an external system.
This element will be included in the response only if the External ID feature is enabled for your account.
ABC123DEF456
firstname First name John
lastname Last name Smith
email_preference A one-letter code defining the subscriber's email preference as:
  • P – plain text
  • H – HTML
  • N – No preference
times_bounced An integer indicating the number of times emails sent to the subscriber bounced 1
timezone The subscriber's preferred time zone
contact_id The unique ID assigned to the subscriber in the eMS Enterprise database 13350980
optin_date A date in YYYY-MM-DD format indicating the date that the subscriber first opted in
address Address
city City
state State or Province
postal_code Postal code
country Country
phone_wk Work phone
phone_hm Home phone
fax Fax number
date_modified A date in YYYY-MM-DD HH:Min:SS format indicating the date that the subscriber's record was last modified
groups_subscribed This element is the "wrapper" for all <group_id> elements. This element will be included in the response when the <return_groups> element is set to '1' in the POSTed XML message.
group_id The ID number of the static segment to which the subscriber belongs. To view a list of static segments and their corresponding ID numbers, log in to the application and navigate to Administration > Configure Settings > Account and Segment IDs. Scroll down on the screen to the Segments section to find the static segment name and its corresponding segment ID.
custom_field_data This element is the "wrapper" for all individual <custom_field_{name/id/value}> data. This element will be included in the response when the <custom_fields> element is set to '1' in the POSTed XML message.
custom_field_name The name of a custom field Pet Name
custom_field_id The custom field ID. To view a list of custom fields and their corresponding ID numbers, log in to the application and navigate to Administration > Configure Settings > Account and Segment IDs. Scroll down on the screen to the Custom Fields section to find the custom field name and its corresponding custom field ID. 4816
custom_field_value The value of the custom field Mr. Snuggles
task_id This element will be included in the response when the input element <asynchronous> is set to '1'. 123456

Response Codes

Response Code Response Text Description
201 Successfully retrieved active subscribers data Successfully retrieved active subscribers data.
420 email filter specified is empty The wildcard search provided in the <email> element did not return any results.
424 The external_id field must be less than 64 characters The value provided in the <external_id> element exceeds the 64-character limit
428 The contact_id field does not support wildcard search The value provided in the <contact_id> must be a numerical value without any wildcard characters
429 mess_id_opened, mess_id_delivered, and mess_id_bounced can not be combined with mess_id_sent Invalid combination of elements provided in the input.
430 mess_id_delivered, and mess_id_bounced can not be combined with mess_id_opened Invalid combination of elements provided in the input.
431 mess_id_bounced can not be combined with mess_id_delivered Invalid combination of elements provided in the input.
451 date_modified_on must be in YYYY-MM-DD format. Invalid data format provided in the input.
452 date_modified_start must be in YYYY-MM-DD format. Invalid data format provided in the input.
453 date_modified_end must be in YYYY-MM-DD format. Invalid data format provided in the input.
454 date_modified_start must be earlier than date_modified_end. Invalid combination of elements provided in the input.
455 date_joined_on must be in YYYY-MM-DD format. Invalid data format provided in the input.
456 date_joined_start must be in YYYY-MM-DD format. Invalid data format provided in the input.
457 date_joined_end must be in YYYY-MM-DD format. Invalid data format provided in the input.
458 date_joined_start must be earlier than date_modified_end. Invalid combination of elements provided in the input.
459 mess_id_sent must be a whole number. Invalid data format provided in the input.
460 mess_id_opened must be a whole number. Invalid data format provided in the input.
461 mess_id_delivered must be a whole number. Invalid data format provided in the input.
462 mess_id_bounced must be a whole number. Invalid data format provided in the input.

Example Post

<methodCall> <methodName>legacy.retrieve_active</methodName> <firstname>john</firstname> <basic>1</basic> <extended>1</extended> <custom_fields>1</custom_fields> <return_groups>1</return_groups> </methodCall>

Example Response

<methodResponse>

<item>

<methodName>legacy.retrieve_active</methodName>

<responseData>

<manifest>

<contact_data>

<firstname>John</firstname>

<lastname/>

<email>jdoe@example.com</email>

<optin_date>2006-05-19</optin_date>

<email_preference>N</email_preference>

<times_bounced>3</times_bounced>

<timezone/>

<contact_id>345208</contact_id>

<address/>

<city/>

<state/>

<postal_code>92128</postal_code>

<country/>

<phone_hm/>

<phone_wk/>

<fax/>

<date_modified>2008-02-27</date_modified>

<groups_subscribed>

<group_id>86</group_id>

<group_id>206</group_id>

<group_id>207</group_id>

</groups_subscribed>

<custom_field_data>

<custom_field_id>156</custom_field_id>

<custom_field_name>custom1</custom_field_name>

<custom_field_hidden>false</custom_field_hidden>

<custom_field_value>radcustom1</custom_field_value>

</custom_field_data>

<custom_field_data>

<custom_field_id>157</custom_field_id>

<custom_field_name>custom2</custom_field_name>

<custom_field_hidden>false</custom_field_hidden>

<custom_field_value/>

</custom_field_data>

<custom_field_data>

<custom_field_id>17</custom_field_id>

<custom_field_name>Last Switchfoot Purchase</custom_field_name>

<custom_field_hidden>false</custom_field_hidden>

<custom_field_value/>

</custom_field_data>

<custom_field_data>

<custom_field_id>18</custom_field_id>

<custom_field_name>Last Dizmas Purchase</custom_field_name>

<custom_field_hidden>false</custom_field_hidden>

<custom_field_value/>

</custom_field_data>

</contact_data>

<contact_data>

<firstname>John</firstname>

<lastname>Smith</lastname>

<email>john_smith@exammple.com</email>

<optin_date>2007-11-04</optin_date>

<email_preference>H</email_preference>

<times_bounced>0</times_bounced>

<timezone/>

<contact_id>1433850</contact_id>

<address/>

<city/>

<state/>

<postal_code>92127</postal_code>

<country/>

<phone_hm/>

<phone_wk/>

<fax/>

<date_modified>2007-11-04</date_modified>

<groups_subscribed></groups_subscribed>

<custom_field_data>

<custom_field_id>157</custom_field_id>

<custom_field_name>custom2</custom_field_name>

<custom_field_hidden>false</custom_field_hidden>

<custom_field_value/>

</custom_field_data>

<custom_field_data>

<custom_field_id>17</custom_field_id>

<custom_field_name>Last Switchfoot Purchase</custom_field_name>

<custom_field_hidden>false</custom_field_hidden>

<custom_field_value/>

</custom_field_data>

<custom_field_data>

<custom_field_id>18</custom_field_id>

<custom_field_name>Last Dizmas Purchase</custom_field_name>

<custom_field_hidden>false</custom_field_hidden>

<custom_field_value/>

</custom_field_data>

<custom_field_data>

<custom_field_id>156</custom_field_id>

<custom_field_name>custom1</custom_field_name>

<custom_field_hidden>false</custom_field_hidden>

<custom_field_value/>

</custom_field_data>

</contact_data>

</manifest>

</responseData>

<responseNum>1</responseNum>

</item> </methodResponse>

If <return_count> was set to '1' in the input parameters, then the output will be as follows:

<methodResponse>

<item>

<methodName><![CDATA[legacy.retrieve_active]]></methodName>

<responseData>

<manifest>

<count>230239</count>

</manifest>

</responseData>

</item>

</methodResponse>


Back to API Reference Guide