The list resource allows contacts to be grouped together. The main interest is to establish distribution lists for sending campaigns, but these lists can also be used to deactivate a set of contacts.

List of properties of the list resource

Property	Description
id	Id of the list of contacts
name	Name of the list of contacts
description	Description of the list of contacts
stats	Statistics of the list of contacts (cf. paragraph for the details)
importErrors	Link to the CSV file containing the list of invalid contacts as well as the reason for which they were not imported.   If the list was not created from a file, this parameter is null.
importLines	Number of contacts present in the file that was used to create this list.   If the list was not created from a file, this parameter is null.
importInvalid	Number of contacts present in the file that was used to create this list but which were not important because they are invalid.   If the list was not created from a file, this parameter is null.
importStatus	Flag making it possible to know whether or not a list is in the process of being imported. "on": The file is being processed "10": percentage processed of the file "ok": The file is fully processed
dateUpdated	Date of the last modification for the contact
dateCreated	Date of creation of the contact

By default, only the id, name and description attributes are returned. To access the other attributes, they must be specified in the properties parameter. Recall that the default attributes have an alias via the 'DEFAULT' keyword.

List of statistics returned

Property	Description
subscribers	Number of contacts present in the list
sms	Number of contacts that can be reached for an SMS sending.   As such, the following are not counted Contacts that have unsubscribed for this media Contacts that the customer has deliberately unsubscribed Deleted contacts
email	Number of contacts that can be reached for an email sending.   As such, the following are not counted Contacts that have unsubscribed for this media Contacts that the customer has deliberately unsubscribed Deleted contacts Hardbounced contacts
voice	Number of contacts that can be reached for a PUSH voice sending.   As such, the following are not counted Contacts that have unsubscribed for this media Contacts that the customer has deliberately unsubscribed Deleted contacts
voicemail	Number of contacts that can be reached for Message on answering machine sending.   As such, the following are not counted Contacts that have unsubscribed for this media Contacts that the customer has deliberately unsubscribed Deleted contacts

 

Example of the resource in JSON format

{
   "id": "123456789",
   "name": "Ma liste de contacts",
   "dateUpdated": "2013-01-02 14:00:00",
   "dateCreated": "2013-01-01 12:00:00",
   "importErrors": "https://contacts.messengeo.net/rest/list.csv...",
   "importLines": "204586",
   "importInvalid": "50007",
   "importStatus": "ok",
   "stats": {
       "subscribers": "103456",
       "sms": "100003",
       "email": "45689",
       "voice": "564",
       "voicemail": "1025",
   }
}

Reading contact lists

List of available filters

Filter	Description
id	Allows you to select the lists to be retrieved from their id

Example

Retrieving two lists from their ids:

GET /rest/lists HTTP/1.1 Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpZCI6ImYyMzE2… Host: contacts.messengeo.net Content-Type: application/x-www-form-urlencoded id=12,65

Creating a list of contacts

List of parameters to supply in order to create contacts

Parameters	Description
name	Name of the list of contacts   This parameter is required
description	Description of the list of contacts

Return

This action returns the list of contact lists created.

{
	"list": [
   	{
       	"id": "7606",
       	"name": "Ma liste de diffusion"
   	}
	],
	"size": 1,
	"total": null
}

Example

POST /rest/lists HTTP/1.1 Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpZCI6ImYyMzE2… Host: api.messengeo.net Content-Type: application/x-www-form-urlencoded name='Ma liste de diffusion'

With Curl

curl -X POST -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG...ccOqbVow8xOQyQ" -d name='Ma liste de diffusion' https://contacts.messengeo.net/rest/lists

Updating a list of contacts

List of available filters

Filter	Description
id	Allows you to select the lists to be updated according to their id

List of data of the contact list that can be updated

Filter	Description
name	Name of the distribution list
description	Description of the distribution list

This action returns the number of lists concerned by the filter passed as input

{
   count: 10,
}

Example

PUT /rest/lists HTTP/1.1 Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpZCI6ImYyMzE2… Host: contacts.messengeo.net Content-Type: application/x-www-form-urlencoded id=1234&metaData='{"name":"New name of the list","description":"New description of the list"}'

With Curl

curl -X PUT -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG...ccOqbVow8xOQyQ" -d id=1234 -d metaData='{"name":"New name of the list","description":"New description of the list"}' https://contacts.messengeo.net/rest/lists

Deleting one or more lists of contacts

List of available filters

Filter	Description
id	Allows you to select the lists to be deleted according to their id

Return

This method returns the number of contacts concerned by the filter passed as input

{
   count: 10,
}

Example

DELETE /rest/lists HTTP/1.1 Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpZCI6ImYyMzE2… Host: contacts.messengeo.net Content-Type: application/x-www-form-urlencoded id=12,78

With Curl

curl -X DELETE -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG...ccOqbVow8xOQyQ" -d id=12,78 https://contacts.messengeo.net/rest/lists

Merging lists of contacts (action=merge)

This action allows you to create a list of contacts using two (or more) contact lists.

List of parameters

Parameter	Description
listIds	List of the list ids
name	Name of the list of contacts to be created

Note: If one of the contact list ids is not correct, the creating of the new list will not take place. An error is returned indicating the ids with errors.

Return

This action returns the list created following the merger of the other lists:

{
   "size": 1,
   "total": null,
   "list": [
   {
       "id": "2671",
       "name": "Ma liste fusionnée"
   }
   ]
}

Example

POST /rest/lists?action=merge HTTP/1.1 Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpZCI6ImYyMzE2… Host: contacts.messengeo.net Content-Type: application/x-www-form-urlencoded listIds=12,78,890&name='Ma liste fusionnée'

Avec Curl

curl -X POST -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG...ccOqbVow8xOQyQ" -d listIds=12,78,890 -d name='Ma liste fusionnée' https://contacts.messengeo.net/rest/lists?action=merge

Importing a contact list from a file (action=import)

This action comprises two steps:

• Creating a list of contacts.

• Creating contacts (or updating contacts for those that were already present in the database).

With the return of the REST call, only the list of contacts was created. The contacts are created subsequently asynchronously. It is possible to monitor the unfolding of the import via the import* attributes of the list resource. As such, when importing a large file, the response time corresponds approximately to the upload time of the file on the platform managing the contacts, with the file being processed afterwards.

This action is to be favored (with respect to the create action on a contact) when there is a large number of contacts to create or synchronize.

List of parameters to supply

Parameter	Description
name	Name of the list of contacts to be created
ignoreFirstLine	Indicates if the first line is a column header line (ignoreFirstLine=true) or if it is a contact (ignoreFirstLine=false)
contactFile	Name of the list of contacts

Format of the files to be imported

The csv and excel (xls, xlsx) formats are authorized. It is also possible to zip the file in order to save time during the upload. The file cannot exceed a size of 20Mb.

With regards to the format of the column headers, two things are possible:

• Either the CSV file does not contain any column headers and then the order of the columns of the contacts must comply with the following order: Civility, First name, Last name, Email, Fixed Telephone, Mobile, Fax, Address 1, Address 2, Postal code, City, State, Country, Date of birth, Company, Reference, Field 1, …, Field 15

• Or the file contains column headers and then, the order of the column is not important as long as the name of the column header is complied with.

Return

This action returns the list created:

{
   "size": 1,
   "total": null,
   "list": [
   {
       "id": "2671",
       "name": "Ma liste importée"
   }
   ]
}

Example

curl -X POST -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG...ccOqbVow8xOQyQ" -d name='Ma liste importée' -d ignoreFirstLine='true' -F contactFile=@/path/to/file/liste.csv https://contacts.messengeo.net/rest/lists?action=import

 

Adding one or more contacts to a list (action=contactadd)

List of available filters

Filter	Description
id	Id of the list to which the contacts are to be added This parameter is required

Specifying the contact or contacts to be added

This data is to be passed in the metaData parameter (cf. examples).

Parameter	Description
contactIds	Ids of the contacts that one wants to add to a contact list This parameter is required

Return

This action returns the number of contacts added in the list

{
   count: 3,
}

Example

curl -X POST -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG...ccOqbVow8xOQyQ" -d id=7606 -d metaData='{"contactIds":"81583724,81583721,81583720" }' https://contacts.messengeo.net/rest/lists?action=contactadd

Removing one or more contacts from a list (action=contactremove)

List of available filters

Filter	Description
id	Id of the list from which the contacts are to be removed This parameter is required

Specifying the contact or contacts to be added

This data is to be passed in the metaData parameter (cf. examples).

Parameter	Description
contactIds	Ids of the contacts that one wants to remove from a contact list This parameter is required

Return

This action returns the number of contacts removed from the list

{
   count: 3,
}

Example

curl -X POST -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG...ccOqbVow8xOQyQ" -d id=7606 -d metaData='{"contactIds":"81583724,81583721,81583720" }' https://contacts.messengeo.net/rest/lists?action=contactremove