REST API

Legacy Poppulo platform REST API

List Subscribers

Overview

Name	Description
HTTP Method	`GET`
URL	`https://api.newsweaver.com/v2/{account code}/subscribers`
Query Parameters	`Yes`
Request representation	`N/A`
Response representation	Subscriber List
Success Response Code	`200 Ok`

Name	Allowed Values	Description	Default
`ext_id`	Text	Filter the list by given subscriber External ID	`N/A`
`status`	`active` `opt_out` `inactive` `all`	Filter the list to subscribers with the given status	`active`
`permission`	[name of a permission]	Restrict to subscribers associated with this permission	`N/A`
`tags`	[tag name or tag expression]	Only include subscribers matching the given tag expression	`N/A`
`search`	[saved search name]	Only include subscribers matching the named saved search	`N/A`
`added_from`	`Date`	Only include subscribers added since this date	`N/A`
`added_to`	`Date`	Only include subscribers added before this date	`N/A`
`fields`	[comma separated list of custom fields and field names]	Used to restrict the size of the XML returned by omitting unnecessary fields	`All custom fields, and status email date_created source mail_format salutation first_name middle_name surname company position_company phone_number fax_number address_1 address_2 address_3 city postal_code county_state country personal_details work_details work_location`
`order_asc`	`status` `email` `date_created` `source` `mail_format` `first_name` `middle_name` `surname` `company` `position_company` `city` `postal_code` `county_state` `country`	Sort the list in ascending order by the given field	`N/A`
`order_desc`	`status` `email` `date_created` `source` `mail_format` `first_name` `middle_name` `surname` `company` `position_company` `city` `postal_code` `county_state` `country`	Sort the list in descending order by the given field	`N/A`

Errors

403 - Forbidden if API user doesn't have READ access to SUBSCRIBERS
Common errors (user/account authentication errors, API usage limit errors)

Other notes:

Using order_asc and order_desc together is undefined.
You cannot sort by multiple fields.
Using personal_details, work_details and/or work_location will include additional information about the subscriber.

Example: GET https://api.newsweaver.com/v2/example-account/subscribers?fields=email,personal_details,work_details,work_location

<subscribers total="1" uri="https://api.newsweaver.com/v2/example-account/subscribers?fields=email,personal_details,work_details,work_location">
    <itemsPerPage>1000</itemsPerPage>
    <startIndex>0</startIndex>
    <totalResults>1</totalResults>
    <subscriber date_modified="2011-09-07T15:06:02Z" uri="https://api.newsweaver.com/v2/example-account/subscriber/1hkmrwl75za">
        <email>bob.robertson@example.com</email>
        <personal_details>
            <employee_id>EMP_001</employee_id>
            <gender>Male</gender>
            <date_of_birth>1995-10-09</date_of_birth>
            <employee_start_date>2020-01-01 00:00:00.0</employee_start_date>
            <preferred_name>Bob</preferred_name>
        </personal_details>
        <work_details>
            <employment_status>Contract</employment_status>
            <department>Engineering</department>
            <division>QA</division>
            <business_unit>Software Development</business_unit>
            <function>Senior Software Engineer</function>
            <team>Improvements</team>
            <pay_grade>Grade 1</pay_grade>
            <cost_centre>2</cost_centre>
        </work_details>
        <work_location>
            <office_building>5100</office_building>
            <site_location>Cork Airport Business Park</site_location>
            <region>Munster</region>
            <country_code>IRL</country_code>
        </work_details>
    </subscriber>
</subscribers>

Tag expressions are tags names separated by pipes or semicolons. Pipes indicate OR, semicolons mean AND. It is not possible to mix both delimiters in a single expression. Tag names that themselves contain pipes or semicolons need to be escaped using a backslash.

Example	Parameter Meaning
`?tags=Some%20Tag`	Subscribers with `Some Tag`
`?tags=Tag_A\|Tag_B\|Tag_C`	Subscribers with any of `Tag_A` or `Tag_B` or `Tag_C`
`?tags=Tag_1;Tag_2;Tag_3`	Subscribers with all of `Tag_1` and `Tag_2` and `Tag_3`
`?tags=Odd;Tag\|Name`	Subscribers with tag `Odd;Tag\|Name`
`?tags=One\|Two;Three`	Not allowed, cannot mix `;` and `\|` together

Example: GET https://api.newsweaver.com/v2/example-account/subscribers

<subscribers total="2" uri="https://api.newsweaver.com/v2/example-account/subscribers">
    <itemsPerPage>1000</itemsPerPage>
    <startIndex>0</startIndex>
    <totalResults>2</totalResults>
    <subscriber date_modified="2011-09-07T15:06:02Z" uri="https://api.newsweaver.com/v2/example-account/subscriber/1hkmrwl75za">
        <status>ACTIVE</status>
        <email>bob.robertson@example.com</email>
        <external_id>11343247</external_id>
    </subscriber>
    <subscriber date_modified="2011-06-01T10:30:29Z" uri="https://api.newsweaver.com/v2/example-account/subscriber/dldps01yfvz">
        <status>ACTIVE</status>
        <email>joe.bloggs@example.com</email>
        <external_id>24574791</external_id>
    </subscriber>
</subscribers>

Overview

Errors

Other notes: