legacy.retrieve_dynamic
- 3 Minutes to read
- Print
- DarkLight
legacy.retrieve_dynamic
- 3 Minutes to read
- Print
- DarkLight
Article summary
Did you find this summary helpful?
Thank you for your feedback
General Information
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:
Initiate the request to retrieve subscriber profile data. A task ID will be included in the response.
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.
Use the file path to retrieve the subscriber list via utilities.getFile in XML format.
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 |
|---|---|---|---|---|
group_id | The value of this element is a single ID for the dynamic segment for which you want the list of subscribers. | 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:
| 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:
| 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 | |
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 | |
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:
| |
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 | The group ID is required. |
406 | Invalid usage case | The 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>Was this article helpful?