List Subscribers

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>

results matching ""

    No results matching ""