legacy.retrieve_dynamic

‹ BACK TO API PAGE


Description

This method allows you to retrieve a list of subscribers from a specific dynamic segment. Because subscriber lists can be very long, this method is asynchronous and will need to be used in conjunction with the utilities.getTasks and utilities.getFile methods.

Performing an Asynchronous Request
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:

  1. Initiate the request to retrieve subscriber profile data. A task ID will be included in the response.
  2. Use the task ID to query the job engine via utilities.getTasks to know when the subscriber profile data is available for download. When the returned status is COMPLETE, the method's <task_response> parameter will include the file path to the subscriber profile data file.
  3. Use the file path to retrieve the subscriber list via utilities.getFile in XML format.

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
group_id The value of this element is a single ID for the dynamic segment you want the list of subscribers for. integer Yes 92439
basic Specifies that only basic contact information will be included in the response which includes first name, last name, email, subscriber status, 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 subscriber status where:
  • 0 – do not specify extended contact info (default)
  • 1 – include extended contact info
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
group_id The Group ID of the dynamic segment that was requested. 92439
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
contact_id The subscriber's identifier defined in the Empower system. ABC123DEF456
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
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
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.
405 Invalid usage case Group ID is required.
406 Invalid usage case Group ID is not an integer.
407 Invalid usage case Invalid Group ID.

Example Post

<methodCall>

<methodName>legacy.retrieve_dynamic</methodName>

<group_id>92439</group_id>

<basic>1</basic>

<extended>1</extended>

<custom_fields>1</custom_fields>

</methodCall>

Example Response

<methodResponse>

<item>

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

<responseCode>![CDATA[201]]</responseCode>

<responseText>![CDATA[Successfully retrieved dynamic subscribers data.]]</responseText>

<responseData>

<task_id>![CDATA[4231738.1020]]</task_id>

<responseNum>![CDATA[1]]</responseNum>

</item>

</methodResponse>


Back to API Reference Guide