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.

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

GET /list or /list/:id

AttributeTypeFilterSortDescription
id
intYesYesUnique ID of the list.
automation_count
intNoNoNumber of Marketing Automation rules associated with this list.
deletable
boolNoNoFlag indicating whether this list may be deleted. If "false", this resource must be treated as read-only.
folder_id
intYesNoUnique ID of the folder containing this list.
form_count
intNoNoNumber of forms attached to this list.
name
stringYesYesList name.
note
string/nullNoNoFree-text note for this list. Null if no note has been stored.
optin
boolNoNoFlag indicating whether this list is linked to an optinautomation rule.
smsautomation_count
intNoNoNumber of SMS Marketing Automation (smsautomation) rules associated with this list.
smsdefault
boolYesNoFlag indicating whether this list receives SMS subscriptions not routed to any other list. Always returns is_deletable = false.
subscription_count
intNoNoNumber of subscriptions associated with this list.
cdate
decimalNoYesCreation timestamp.
mdate
decimalNoNoLast modification timestamp.

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

HEAD /list or /list/:id

AttributeTypePresenceDescription
id
intOptionalUnique ID of the list.
folder_id
intOptionalUnique ID of the folder containing this list.
name
stringOptionalList name.
smsdefault
boolOptionalFlag indicating whether this list receives SMS subscriptions not routed to any other list. Always returns is_deletable = false.

POST /list

AttributeTypePresenceDescription
folder_id
intRequiredUnique ID of the folder containing this list.
name
stringRequiredList name.
note
string/nullOptionalFree-text note for this list. Null if no note has been stored.

PUT /list or /list/:id

AttributeTypePresenceDescription
id
intRequiredUnique ID of the list.
folder_id
intOptionalUnique ID of the folder containing this list.
name
stringOptionalList name.
note
string/nullOptionalFree-text note for this list. Null if no note has been stored.

DELETE /list or /list/:id

AttributeTypePresenceDescription
id
intRequiredUnique 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

CodeSubcodeMessageDescription
423
1
List $id is to be or has been targetedA 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 permanentThis list is permanent.
423
3
List $id is attached to a formThis 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
 }