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 */
"emailonly": "{boolean: emailonly*}", /* optional: default is "false" */
"pagination": { /* optional */
"limit": "{*max_records*}", /* required */
"next": "{*start_at_record_number*}" /* optional: default 0 */
}
}
}"json_request" element
| Field Name | Description |
| username | Username used to login to Pinpointe |
| usertoken | Unique token assigned to Pinpointe account |
| requesttype | Tags |
| requestmethod | GetTagSubscribers |
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
"tag"
| Field Name | Description |
| tag (Required if "name" element not used) | ID of tag(s) mailing list to be searched. At least one required. |
| extag | ID of optional tag(s) mailing lists who contacts should be excluded from the search. |
| status | Select from the options provided to search for contacts with that status. |
| tagname (Required if "tag" element not used) | Find the tag mailing list with this name. |
"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. |
"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 to 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". |
"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 Name | Description |
| status | Will return SUCCESS if contacts were successfully found. |
| data | Contact count, status selected, subscriber details. |
Unsuccessful Response:
"response" element
| Field Name | Description |
| status | Will return FAILED if unsuccessful |
| errormessage | Text explaining why request failed |