List Endpoint | Sign-Up.to Permission Marketing API

List v1.2

Lists are held within folders and they contain subscribers. The relationship between a list and a subscriber is called a subscription.

What can I do with list?

Lists are involved in lots of API interactions. They are fundamental to the way you store and utilise your subscriber data.

A subscription is the combination of a subscriber and a list.
Forms submit data to one or more lists.
You target lists when creating tasks.
Lists can be used in powerful automation rules.
You can move a list and its subscriptions by modifying folder_id.
Hide or protect content by checking if a subscription exists on a list.

Over time your collection of lists will grow. Use folders to help manage them efficiently.

GET /list or /list/:id

Attribute	Type	Filter	Sort	Description
id	int	Yes	Yes	Unique ID of the list.
automation_count	int	No	No	Number of Marketing Automation rules associated with this list.
deletable	bool	No	No	Flag indicating whether this list may be deleted. If "false", this resource must be treated as read-only.
folder_id	int	Yes	No	Unique ID of the folder containing this list.
form_count	int	No	No	Number of forms attached to this list.
name	string	Yes	Yes	List name.
note	string/null	No	No	Free-text note for this list. Null if no note has been stored.
optin	bool	No	No	Flag indicating whether this list is linked to an optinautomation rule.
smsautomation_count	int	No	No	Number of SMS Marketing Automation (smsautomation) rules associated with this list.
smsdefault	bool	Yes	No	Flag indicating whether this list receives SMS subscriptions not routed to any other list. Always returns is_deletable = false.
subscription_count	int	No	No	Number of subscriptions associated with this list.
cdate	decimal	No	Yes	Creation timestamp.
mdate	decimal	No	No	Last modification timestamp.

We keep list name private at Sign-Up.to, we recommend you do the same!

HEAD /list or /list/:id

Attribute	Type	Presence	Description
id	int	Optional	Unique ID of the list.
folder_id	int	Optional	Unique ID of the folder containing this list.
name	string	Optional	List name.
smsdefault	bool	Optional	Flag indicating whether this list receives SMS subscriptions not routed to any other list. Always returns is_deletable = false.

POST /list

Attribute	Type	Presence	Description
folder_id	int	Required	Unique ID of the folder containing this list.
name	string	Required	List name.
note	string/null	Optional	Free-text note for this list. Null if no note has been stored.

PUT /list or /list/:id

Attribute	Type	Presence	Description
id	int	Required	Unique ID of the list.
folder_id	int	Optional	Unique ID of the folder containing this list.
name	string	Optional	List name.
note	string/null	Optional	Free-text note for this list. Null if no note has been stored.

DELETE /list or /list/:id

Attribute	Type	Presence	Description
id	int	Required	Unique ID of the list.

A list cannot be deleted if it's the 'primary list' on a form, targeted by a recent task (within 72 hours), the target of a scheduled task, or if deletable is false.

Deleting a list will DELETE all subscriptions associated with it, pause any automation rules which reference it (pending actions will also be cancelled), suspend and delete any pending imports, and remove any other data or actions (legacy) which are stored against the list.

Error codes

Code	Subcode	Message	Description
423	1	List $id is to be or has been targeted	A campaign is scheduled to be sent to this list in the future or has been sent to this list in the last 72 hours.
423	2	List $id is permanent	This list is permanent.
423	3	List $id is attached to a form	This is the primary list for a form.

Please see error handling for more information on error codes.

Examples

Have you seen our example of this endpoint being used with other endpoints?

JSON response

{
    "id":                  2209,
    "automation_count":    2,
    "deletable":           true,
    "folder_id":           123,
    "form_count":          4,
    "name":                "Sales leads Jan 2013",
    "note":                null,
    "optin":               true,
    "smsautomation_count": 5,
    "smsdefault":          false,
    "subscription_count":  5,
    "cdate":               1234966741,
    "mdate":               1234966741
 }