API Overview

Broadcast API

REST API: Lists


The Lists resource allows retrieval of all lists, subscribers in that list (active or unsubscribed), creation of lists, updating of individual lists, and addition/removal of subscribers from lists.


Root Resource URI

/2011-03-01/Lists

Resource Properties


A List Instance resource is represented by the following properties:


Property Description
ListID String representing the unique system ID for an individual list
ListName String representing the name of the list.
Notes Text representing the notes of the list. Empty if unavailable for this subscriber.
Created Unix timestamp (GMT) representing the creation time and date of this subscriber.

List Instance Resource


Root Resource URI

/2011-03-01/Lists

HTTP GET

Returns account lists


GET /2011-03-01/lists

Response: GET Lists

Returns a paginated subset of all account lists (paginated)

HTTP POST


Creates a new list


POST /2011-03-01/lists

The following parameters are required to create a new list:


Property Description
ListName String representing the name of an individual list

The following parameters are optional to create a new list:


Property Description
Notes Text representing the notes of the list. Empty if unavailable for this list.

Response: POST New List Response

Returns the newly created list


HTTP PUT


Not Supported


HTTP DELETE


Not Supported

Individual List Instance Resource


Root Resource URI

/2011-03-01/Lists/Individual

HTTP GET


Returns a single list


GET /2011-03-01/lists/individual

The following parameters are required to get a single list:


Property Description
ListID Integer representing the unique ID of an individual list

Response: GET Individual List


HTTP POST


Not Supported


HTTP PUT


Not Supported


HTTP DELETE


Not Supported


Delete List Instance Resource


Root Resource URI

/2011-03-01/Lists/Delete

HTTP POST


Deletes a single list


POST /2011-03-01/lists/delete

The following parameters are required to delete a single list:


Property Description
ListID Integer representing the unique ID of an individual list

Response: Delete List

Deletes the list from the account. Returns HTTP 204 response if successful (no body).


HTTP GET


Not Supported


HTTP PUT


Not Supported


HTTP DELETE


Not Supported


All List Subscribers Instance Resource


Root Resource URI

/2011-03-01/Lists/Subscribers

HTTP GET


Returns all list subscribers


GET /2011-03-01/Lists/Subscribers

Add List Subscriber Instance Resource


Root Resource URI

/2011-03-01/Lists/AddSubscriber

HTTP POST


Adds an existing subscriber to a single list


POST /2011-03-01/lists/addSubscriber

The following parameters are required to add a new list subscriber:


Property Description
ListID Integer representing the unique ID of an individual list
SubscriberID Integer representing the unique ID of an individual subscriber

Response: Add List Subscriber

Adds the subscriber to the list specified.


Response: POST New List Subscriber

The response is identical to the Individual List Resource response outlined above.


HTTP GET


Not Supported


HTTP PUT


Not Supported


HTTP DELETE


Not Supported


Remove List Subscriber Instance Resource


Root Resource URI

/2011-03-01/Lists/removeSubscriber

HTTP POST


Removes an existing subscriber from a single list


POST /2011-03-01/lists/removeSubscriber

The following parameters are required to remove a list subscriber:


Property Description
ListID Integer representing the unique ID of an individual list
SubscriberID Integer representing the unique ID of an individual subscriber

Response: POST Remove List Subscriber

The response is identical to the Individual List Resource response outlined above.


HTTP GET


Not Supported


HTTP PUT


Not Supported


HTTP DELETE


Not Supported