# How can we help?

## Overview

The account lists collection contains names of lists used to define segments of your audience. For example, you might have lists for Weekly Specials, Daily Deals, or Fashion Newsletter to represent each subscriber's selection for information and promotions they requested to receive. You might also use account lists to represent groups or segments you determine to be important such as New Customers, VIPs, or Net Promoters.

**API set name: accountlists**

### 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's important to use a naming convention that supports the creation of multiple lists over time.

## Authentication

Cordial's core APIs use https Basic Authentication (BA). From within the Cordial platform, you can generate an encoded [API key for your account](https://support.cordial.com/hc/en-us/articles/115005365087) and use it for authorization.

## 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. |

## Methods, parameters, and examples

- [POST/v2/accountlists](https://support.cordial.com/hc/en-us/articles/204570497-Account-lists-API#postAccountLists)
- [GET/v2/accountlists](https://support.cordial.com/hc/en-us/articles/204570497-Account-lists-API#getAccountLists)
- [GET/v2/accountlists/{id}](https://support.cordial.com/hc/en-us/articles/204570497-Account-lists-API#getAccountListsId)
- [GET/v2/accountlists/{id}/count](https://support.cordial.com/hc/en-us/articles/204570497-Account-lists-API#getAccountListsIdCount)
- [PUT/v2/accountlists/{id}](https://support.cordial.com/hc/en-us/articles/204570497-Account-lists-API#updateAccountListsId)
- [PUT/v2/accountlists/{id}/clear](https://support.cordial.com/hc/en-us/articles/204570497-Account-lists-API#clearAccountListsId)
- [DELETE/v2/accountlists/{id}](https://support.cordial.com/hc/en-us/articles/204570497-Account-lists-API#deleteAccountListsId)

## POST/v2/accountlists

| Method | URL Path |
| --- | --- |
| POST | /v2/accountlists |
| - Creates a new account list in the Cordial database using the appropriate JSON body.<br>- When a list is created, an id value is generated uniquely for that list.<br>- Posting more than one time for the same list name will generate an error. |

- [Parameters](https://support.cordial.com/hc/en-us/articles/204570497-Account-lists-API#zp-1-0)
- [Example JSON request](https://support.cordial.com/hc/en-us/articles/204570497-Account-lists-API#zp-1-1)
- [Example request URL](https://support.cordial.com/hc/en-us/articles/204570497-Account-lists-API#zp-1-2)

\*Required

| Parameter | Type | Description | Example |
| --- | --- | --- | --- |
| \*name | string | Unique name to identify and reference the list. | safe-drivers |
| enhanced | boolean | Automatically track the date each contact is added to the list.<br>Possible values: true, false | true |

The following will create a new accountlist named "safe_drivers" that tracks when each contact is added to the list.

```
{
  "name": "safe_drivers",
  "enhanced": true
}
```

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

```
https://<path>/v2/accountlists
```

## GET/v2/accountlists

| Method | URL Path |
| --- | --- |
| GET | /v2/accountlists |
| - Retrieves all account lists from the Cordial database.<br>- It's possible to filter the response data for a specific list using the list name query string parameter. |

- [Example request URLs](https://support.cordial.com/hc/en-us/articles/204570497-Account-lists-API#zp-2-0)

The following URL will retrieve all accountlists.

```
https://<path>/v2/accountlists
```

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

```
https://<path>/v2/accountlists?name=safe_drivers
```

## GET/v2/accountlists/{id}

| Method | URL Path |
| --- | --- |
| GET | /v2/accountlists/{id} |
| - Retrieves the specified account list from the Cordial database.<br>- The accountlist is defined by the accountlist's unique id value.<br>- For example, /accountlists/128 would return the response data for the list with the id value of "128". |

- [Example Request URL](https://support.cordial.com/hc/en-us/articles/204570497-Account-lists-API#zp-3-0)

The following URL 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.

```
https://<path>/v2/accountlists/128
```

## GET/v2/accountlists/{id}/count

| Method | URL Path |
| --- | --- |
| GET | /accountlists/{id}/count |
| - Retrieves the specified account list from the Cordial database.<br>- The accountlist is defined by the accountlist's unique id value.<br>- For example, /accountlists/128/count would return the response data for the list with the id value of "128" and the count of contacts assigned to this list. |

- [Example request URL](https://support.cordial.com/hc/en-us/articles/204570497-Account-lists-API#zp-4-0)

The following URL will retrieve an accountlist where the id value is "128" and the count of contacts assigned to this list. Note that when a list is created, an id value is generated uniquely for that list.

```
https://<path>/v2/accountlists/128/count
```

## PUT/v2/accountlists/{id}

| Method | URL Path |
| --- | --- |
| PUT | /v2/accountlists/{id} |
| Updates the list name to a new value, and it enables or disables date tracking. Enabling list tracking will automatically track the date each contact was added to the list. |

- [Parameters](https://support.cordial.com/hc/en-us/articles/204570497-Account-lists-API#zp-5-0)
- [Example JSON request](https://support.cordial.com/hc/en-us/articles/204570497-Account-lists-API#zp-5-1)
- [Example request URL](https://support.cordial.com/hc/en-us/articles/204570497-Account-lists-API#zp-5-2)

\* Required

| Parameter | Type | Description | Example |
| --- | --- | --- | --- |
| \* id | number | Unique list value 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 for when contacts are added to the list.<br>Possible values: true, false | true |

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

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

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

```
https://<path>/v2/accountlists/128
```

## PUT/v2/accountlists/{id}/clear

| Method | URL Path |
| --- | --- |
| PUT | /v2/accountlists/{id}/clear |
| Removes all contact list associations for the given list id while retaining the list itself in the Cordial database. Note that when a list is cleared, no contacts will be deleted from the system. |

- [Example request URL](https://support.cordial.com/hc/en-us/articles/204570497-Account-lists-API#zp-6-0)

The following URL will clear all contacts from an accountlist where the id value is "128".

```
https://<path>/v2/accountlists/128/clear
```

## DELETE/v2/accountlists/{id}

| Method | URL Path |
| --- | --- |
| DELETE | /v2/accountlists/{id} |
| Deletes an existing account list from within the Cordial database.<br>The accountlist is defined by the accountlist's unique **id** value.<br>For example, /v2/accountlists/128 would delete the list with the **id** value of "128". |

- [Example request URL](https://support.cordial.com/hc/en-us/articles/204570497-Account-lists-API#zp-7-0)

The following URL will delete an accountlist where the **id** value is "128".

```
https://<path>/v2/accountlists/128
```

## Test in Swagger

You can [access and test Cordial's APIs in Swagger](https://support.cordial.com/hc/en-us/articles/216197618).

## Error responses

You can find common error responses on the [Global API error responses](https://support.cordial.com/hc/en-us/articles/4402427843597-Global-API-Error-Responses) page.