Retrieve contacts (including within one or more tags with option to exclude contacts belonging to a subset of to-be-excluded tags (Called "lists" within the GUI application).

JSON Request Example:

  "username": "JohnDoe",
  "usertoken": "abc123abc123abc123abc123abc123",
  "requesttype": "Tags",
  "requestmethod": "GetTagSubscribers",
  "details": {
    "tag": ["{*include_tag_id*}", "{*include_tag_id*}"], /* required: at least one */
    "extag": ["{*exclude_tag_id*}", "{*exclude_tag_id*}"], /* optional */
    "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 */
    "pagination": { /* optional */
      "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

Please note: ALL OPTIONAL tags that are not used should be deleted from submitted call. For example, If no tag is to be excluded, remove the <extag>{*exclude_tag_id*}</extag> elements. In addition, if only one tag is being searched, remove all unused <tag></tag> elements.

"details" element


Field NameDescription
ID of tag(s) to be searched. At least one required.  
ID of optional tag(s) who contacts should be excluded from the search.
Select from the options provided to search for contacts with that status.

"include_membership" element

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.

"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.

"pagination" element

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

Field Name
(optional but required if "next" parameter used)
max_records: Integer indicating maximum number of datasets (records) to be returned for the respective call.
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 contacts were successfully found.
dataContact count, status selected, subscriber details.

Example of returned data: 

Unsuccessful Response:

"response" element

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