legacy.retrieve_dynamic

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

Example Response

---