Lists - Heyloyalty/api GitHub Wiki
Gets basic info about all lists.
GET /lists
| Name | Description | Default |
|---|---|---|
| orderby | The name of the field to order by | created_at |
| order | The order direction. Ascending: 1, Descending: -1. | 1 |
| supports | When set to email, sms or smsplus, only lists supporting this campaign type will be returned |
Status: 200 OK
[
{
"id": 1,
"name": "Customers",
"created_at": "2013-05-28 13:58:12",
"members": 80376,
"open_rate": 39,
"click_rate": 12
},
{
"id": 2,
"name": "Loyalty Club",
"created_at": "2013-05-28 13:58:12",
"members": 4821,
"open_rate": 78,
"click_rate": 26
}
]
Lists not found
Status 404 List not found
Gets information about a single list.
GET /lists/:id
The method takes no parameters.
Status: 200 OK
{
"id": 1,
"name": "Customers",
"fields": {
"firstname": {
"id": 1,
"type": "fixed",
"type_id": 1,
"format": "text",
"name": "firstname",
"label": "First Name"
},
"lastname": {
"id": 2,
"type": "fixed",
"type_id": 2,
"format": "text",
"name": "lastname",
"label": "Last Name"
},
"email": {
"id": 3,
"type": "fixed",
"type_id": 3,
"format": "text",
"name": "email",
"label": "E-mail"
},
"interests": {
"id": 4,
"type": "custom",
"type_id": 18,
"format": "multi",
"name": "interests",
"label": "Interests",
"options": {
7: "Music",
8: "Books",
9: "Movies",
10: "Travel",
11: "Sports",
12: "Cooking",
13: "Shopping"
}
}
}
}
List not found
Status 404 List not found
Creates a new list.
POST /lists
| Name | Description | Required |
|---|---|---|
| name | Name of the list | x |
| country_id | Id of primary list country. (Fx. 1 for Denmark) | x |
| duplicates | How to handle duplicate members. Can be "allow", "allow_email", "allow_mobile" and "disallow". | x |
| fields | An array of fields. Se below. | x |
Fields determine what kind of information can be stored on members who are added to the list. There are two types of fields, Fixed fields and Custom fields. A Fixed field has a predefined name, label and format, which can't be altered. Custom fields on the other hand, allows for customization of these attributes.
The following Fixed fields are available:
| Name | Format |
|---|---|
| firstname | Text |
| lastname | Text |
| Text | |
| mobile | Number |
| sex | Single choice |
| birthdate | Date |
| address | Text |
| postalcode | Number |
| city | Text |
| Country | Single choice |
| Password | Text |
| Reference | Text |
The Format determines what kind of data a field can hold, and how input is presented.
The following formats are available:
| Name | Description | Input |
|---|---|---|
| text | Text | A string with a maximum length of 255 characters. |
| number | Number | An integer |
| date | Date | An ISO 8601 date (YYYY-MM-DD) |
| boolean | Yes/No (Checkbox) | An integer which can only by 1 or 0. |
| choice | Single choice | An integer representing the id of an option |
| multi | Multiple choice | An array of integers representing options |
| Name | Description |
|---|---|
| type | Field type. Can be "fixed" or "custom" |
| name | Name of the field. When type is "fixed" this must match one of the Fixed field names. |
| fallback | Field fallback. Default value, if field left empty this will be set. |
| format | Field format. Only required for custom fields. |
| label | Field label. Only required for custom fields. |
| options | An array of options. Only required for custom fields with format "choice" or "multi". Each option should specify a label. For example options[0][label]=First&options[1][label]=Second
|
A list must have either an email or mobile field.
Parameters for creating a list named "Customers" that does not allow duplicates with a firstname and email field.
name=Customers&country_id=1&duplicates=disallow&fields[0][type]=fixed&fields[0][name]=firstname&fields[1][type]=fixed&fields[1][name]=email
Parameters for creating a list named "Customers" that does not allow duplicates with an email field, and a custom field named "shoe_size".
name=Customers&country_id=1&duplicates=disallow&fields[0][type]=fixed&fields[0][name]=email&fields[1][type]=custom&fields[1][format]=number&fields[1][name]=shoe_size&fields[1][label]=Shoe size
The id of the new list is returned.
Status: 201 Created
{"id":1}
List not found
Status 404 List not found
Missing required field
Status 400 bad request
{"error": "The name field is required."}}{"error": "The country id field is required."}{"error": "The duplicates field is required."}Updates an existing list.
PUT /lists/:id
This method accepts the same parameters as when creating a list, with a few additions.
Note that this method overrides all fields. Existing fields not specified in the fields parameter will be deleted. see Patch to avoid deleting not specified fields
Existing custom fields and options must also provide an id. (Can be retrieved from get single list method).
Status: 204 No Content
List not found Status 404 list not found
Missing required field Status 400 bad request
{"error": "The name field is required."}}{"error": "The country id field is required."}{"error": "The duplicates field is required."}The method does not return anything on success.
Warning!! when you delete a list all your campaigns and automations that are sent from that list is also deleted. Members on the list are deleted aswell.
DELETE /lists/:id
The method takes no parameters.
Status: 204 No Content
The method does not return anything on success.
List not found
Status 404 list not found