Search for subscribers in a list and retrieve their email addresses and custom field values (optional).


JSON Request Example:  


{
  "username": "johndoe",
  "usertoken": "abc123abc123abc123abc123abc123",
  "requesttype": "Lists",
  "requestmethod": "GetListSubscribers",
  "details": {
    "list": ["{*list_id*}", "{*list_id*}"], /* required: at least one */
    "status": "{*status: any|active|inactive|bounced|unsubscribed*}", /* optional: default any */
     "emailonly": "{*boolean: emailonly*}", /* optional: default is "false" */ 
    "include_membership": "{*include_membership_boolean*}", /* optional: include tag membership */
    "customfields": ["{*customfield_name*}"], /* optional: multi, use  "all" for all */ 
    "startdate": "{*start_date*}",
    "enddate": "{*end_date*}",
    "pagination": { /* optional: default return all at once */
      "limit": "{*max_records*}", /* required */
      "next": "{*start_at_record_number*}" /* optional: default 0 */
    }
  }
}


"json_request"  element


Field NameDescription
usernameUsername used to login to Pinpointe
usertokenUnique token assigned to Pinpointe account
requesttypeLists
requestmethodGetListSubscribers


"details" 


Field NameDescription
ListID 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.


"include_membership" element


include_membership
(optional) 
PieSync requirement: Setting this element's value to true, 1 or yes results in the API call adding a list of all tags that a subscriber is in as part of the returned information for that subscriber. Default is false 


"customfields" and "emailonly" elements


customfields (optional)User may retrieve a contact's custom field values by specifying the name(s) OR ID(s) of the custom fields be be returned, or by entering "all" as the parameter value.
emailonly (optional)
User may elect to only have contact email addresses returned. This element takes a Boolean value: "yes", "1", "true", - OR -  "no", "0", "false". The default value is "false".


"startdate" and "enddate" elements


startdate
(optional)
Use Zulu Time format (2025-08-13T16:32:00Z). Other time formats are not recommended because they may be deprecated in the future. 
enddate
(optional)
Use Zulu Time format (2025-08-13T16:32:00Z). Other time formats are not recommended because they may be deprecated in the future.


"pagination" element


Please note: If "pagination" parameters omitted, call will return as many records as allowable based on current application memory constraints.  


Field Name
Description
limit
(optional but required if "next" parameter used)
max_records: Integer indicating maximum number of datasets (records) to be returned for the respective call.
next
(optional)
start_at_record_number: If parameter used, the call response will be limited to the “limit” value and the response will include a pagination section with the appropriate “next” value to return the next sequential chunk of records, or “0” if all records have been returned.



Successful Response:


"response" element


Field NameDescription
statusWill return SUCCESS if subscriber(s) successfully found and retrieved. 
dataIncludes 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:

 


Unsuccessful Response:


"response" element


Field NameDescription
statusWill return ERROR if unsuccessful
errormessageText explaining why request failed