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 Mapp while it generates the subscriber data.
Retrieving subscriber data asynchronously is a three-step process:
- Initiate the request to retrieve subscriber profile data and set the <asynchronous> input parameter to '1'.
- Query the job engine via utilities.getTasks to know when the subscriber profile data is available for download
- 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
- This method cannot be combined with any other method call within the same POST command.
- 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 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:
|
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 (Mapp'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:
|
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:
|
string | No | all |
| asynchronous | Specifies to enable returning of the resource to operate in asynchronous mode where:
|
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:
|
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:
|
boolean | No | 1 |
| return_groups | Specifies whether to include a comma-delimited list of static segment IDs to which each subscriber belongs where:
|
boolean | No | 1 |
| custom_fields | Specifies whether to include all custom field data to be included in the response message where:
|
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 | |
| 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:
|
|
| 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 Empower 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>