Search for subscribers in a list and retrieve their email addresses and custom field values (optional).
System runs asynchronously in the background to allow retrieving payloads for larger lists. User has option of receiving notification of call completion and a link to download either the JSON or CSV file via email or by webhook.
JSON Request Example:
{
"username": "jogn.doe@xxxxx.com",
"usertoken": "abc123abc123abc123abc123abc123",
"requesttype": "Lists",
"requestmethod": "GetListSubscribersAsync",
"details": {
"list": ["{*list_id*}", "{*list_id*}"], /* required: at least one */
"status": "{*status: any|active|inactive|bounced|unsubscribed*}", /* optional: default any */
"include_membership": "{*include_membership_boolean*}", /* optional: include tag membership */
"customfields": ["{*customfield_name*}"], /* optional, multi, use 'all' for all */
"startdate": "{*start_date*}",
"enddate": "{*end_date*}",
"format": "{*csv|json*}", /* optional: default json */
"notify": { /* required */
"type": "{*notification_type*}", /* required: email or webhook */
"value": "{*notification_target*}" /* required: email-address or webhook-url */
}
}
}"json_request" element
| Field Name | Description |
| username | Username used to login to Pinpointe |
| usertoken | Unique token assigned to Pinpointe account |
| requesttype | Lists |
| requestmethod | GetListSubscribersAsync |
"details"
| Field Name | Description |
| List | ID of list to be searched. Can add multiple <list> tags to search more than one list. |
| status (optional) | Status of contacts to be searched for. Value can be any, active, inactive, bounced or unsubscribed. Default is any. |
"customfields" element
| customfields (optional) | User may retrieve a contact's custom field values by specifying the name(s) of the custom fields to be be returned, or by entering "all" as the parameter value. |
"startdate" and "enddate" elements
| startdate (optional) | A start date for when subscribers were added in the YYYYMMDD format |
| enddate (optional) | An end date for when subscribers were added in the YYYYMMDD format |
NOTE: The actual timestamp used in the YYYYMMDD format is YYYY-MM-DD:00:00:00, or in other words, 12:00 am at 0 minutes and 0 seconds of the date given. Thus, if the user wished, for example, to specify a given date, such as January 1, 2025, they would use a startdate = 20250101 and an enddate of 20250102.
"format" element
| format | User can select whether to receive the payload in either CSV or JSON format. |
"notify" element
| type (required) | Method by which user wishes to be notified that the call has completed processing and what the link to the JSON file is: either "email" or "webhook" |
| value (required) | If user selects notification via email, they must provide a valid email address which will receive the email notification. If user selects notification via webhook, they must provide a valid webhook URL to receive the payload, including the link to the JSON file. |
Successful Response:
"response" element
| Field Name | Description |
| status | Will return SUCCESS if call was successfully completed. |
| data | Includes sub-element count (the number of subscribers being returned); and subscribers, a list of email addresses and the respective data for each subscriber. |
Example of returned data:
(Where user has selected "email-address" as notification method and provided an email address):
(Where user has selected "webhook-url" as notification method and provided a webhook URL):
Unsuccessful Response:
"response" element
| Field Name | Description |
| status | Will return ERROR if unsuccessful |
| errormessage | Text explaining why request failed |