Account Lists

API Set Name: accountlists

• POST /accountlists
• GET /accountlists
• GET /accountlists/{id}
• PUT /accountlists/{id}
• PUT /accountlists/{id}/clear
• DELETE /accountlists/{id}

API Description and Functional Purpose:

The accountlists collection contains names of lists used to define segments of your audience. For example, you may have lists for "Weekly Specials", "Daily Deals" and "Fashion Newsletter". Each represents subscriber selections on information and promotions they requested to receive. You may also use accountlists to represent groups or segments you determine to be important such as "New Customers", "VIPs" or "Net Promoters".

Additional information:

• A contact can be associated with one or more lists.
• There is no limit to how many lists can be created.
• List names are required to be unique, so it is important to use a naming convention that supports the creation of multiple lists over time.

Resource Associations:

The following resource collections are associated to this collection.

Collection	Association
contacts	Contacts can be associated to accountlists, identifying a contact as a member of one or more account lists.

POST /accountlists

Method	URI Path
POST	/accountlists
Creates a new account list in the Cordial database using the appropriate JSON body. Posting more than one time for the same list name will generate an error.

Parameters

*Required

Parameter	Type	Description	Example
*name	string	Unique name to identify and reference the list	safe-drivers

Example JSON Requests

The following will create a new accountlist named "safe_drivers". Note that list names must be unique.

{
  "name": "safe_drivers"
}

Example Request URIs

The following URI in conjunction with the JSON will perform the POST.

http://<path>/accountlists

GET /accountlists

Method	URI Path
GET	/accountlists
Retrieves all account lists from the Cordial database. Using a query string parameter, it is also possible to filter the response by list "name" to retrieve information for a single list.

Example Request URIs

The following URI will retrieve all accountlists.

http://<path>/accountlists

The following URI will retrieve an accountlist where the list name is "safe_drivers".

http://<path>/accountlists?name=safe_drivers

GET /accountlists/{id}

Method	URI Path
GET	/accountlists/{id}
Retrieves an account list from the Cordial database. The accountlist is defined by the accountlist's unique "id" value. For example, /accountlists/128 would return the response data for the list with the id value of "128".

Example Request URIs

The following URI will retrieve an accountlist where the id value is "128". Note that when a list is created, an "id" value is generated uniquely for that list.

http://<path>/accountlists/128

PUT /accountlists/{id}

Method	URI Path
PUT	/accountlists/{id}
Updates the list name to a new value and enables or disables date tracking.

Parameters

*Required

Parameter	Type	Description	Example
*id	number	Unique list id to identify and reference the list.	128
*name	string	Updated list name to replace the existing value.	vip_guests
enhanced	boolean	Enable or disable date tracking when contacts are added to the list.	true, false

Example JSON Requests

The following will update the existing accountlist name "guests" to "vip_guests" and enable date tracking.

{
  "id": 128,
  "name": "vip_guests",
  "enhanced": true
}

Example Request URIs

The following URI in conjunction with the JSON will perform the PUT.

http://<path>/accountlists/128

PUT /accountlists/{id}/clear

Method	URI Path
PUT	/accountlists/{id}/clear
Removes all contact list association while retaining the list itself in the Cordial database.

Example Request URIs

The following URI will clear all contacts from an accountlist where the id value is "128". Note that when a list is cleared, no contacts will be deleted from the system.

http://<path>/accountlists/128/clear

DELETE /accountlists/{id}

Method	URI Path
DELETE	/accountlists/{id}
Deletes an account list within the Cordial database. The accountlist is defined by the accountlist's unique "id" value. For example, /accountlists/128 would delete the list with the id value of "128".

Example Request URIs

The following URI will delete an accountlist where the id value is "128". Note that when a list is created, an "id" value is generated uniquely for that list.

http://<path>/accountlists/128