Creates a contact list with specific contacts.
Endpoint
POST https://api.emarsys.net/api/v2/contactlist
Parameters
Required paremeters
| Name | Type | Description | Comments |
|---|---|---|---|
| name | string | Name of the contact list. | |
| key_id | mixed | Key which identifies the contacts. | You can use a field ID, id or uid. The default value is 3, it has to be provided. |
| external_ids | array | List of contact IDs to be inserted. The external_id for key_id 3 has to be provided. | The maximum value is 10,000 contacts. |
Optional parameters
| Name | Type | Description | Comments |
|---|---|---|---|
| description | string | Additional information about the contact list. |
Request Example
Simple Values
{
"key_id": "3",
"name": "asgard_protectors",
"description": "those who fight for Asgard",
"external_ids":
[
"thor@example.com",
"odin@example.com",
"loki@example.com"
]
}
Multichoice Values
{
"key_id": "123",
"name": "asgard_protectors",
"description": "those who fight for Asgard",
"external_ids":
[
[1,2,3],
[2,3],
[1,4]
]
}
Result Example
{
"replyCode": 0,
"replyText": "OK",
"data":
{
"id": 123,
"errors":
{
"loki@example.com":
{
"2008": "No contact found with the external id: 3 - loki@example.com"
}
}
}
}
Result example details
| Name | Description |
|---|---|
| id | ID of the contact list |
| errors | Lists any error(s) and contains the ID and error message as a key-value pair. |
Please note that when no contacts are defined for the contact list,errorsis not shown. If contacts were defined for
the contact list but no error occurred, the following is displayed:
{
"replyCode": 0,
"replyText": "OK",
"data": {
"id": 123,
"errors": []
}
}
Errors
| HTTP Code | Reply Code | Message | Description |
|---|---|---|---|
| 400 | 2007 | Invalid data format for field ID: [field_id]. Scalar expected. | In case of multichoice fields, the key_id should be a multichoice field_id and the format of the input should be: choice_id1,choice_id2;choice_id1,choice_id3, etc. The values of the choice_ids can be queried with the Listing Available Field Choices endpoint. |
| 400 | 2008 | No contact found with the external ID: [field_id]. | Please specify a contact with an existing field_id. |
| 500 | 3001 | List name is not set. | Please specify a name for the list. |
| 500 | 3002 | The list of external IDs exceeds the maximum size. | The number of IDs is limited to 10,000. |
| 500 | 3003 | Invalid datatype for the list of external IDs. Array expected. | Please specify an array. |
| 500 | 3004 | List name is not set. | Please specify a name for the list. |
| 500 | 3005 | Contact list with the requested name already exists. | The name provided is not unique. |