Contacts

It provides the basic structure required for storing the various information about a person (last name, first name, mobile telephone number, email address, date of birth...).

List of properties of the contact resource

Contact administration

Property Description
id Id of the contact
listIds List of ids of contact lists in which the contact is mentioned
dateUpdated Date of the last modification for the contact
dateCreated Date contact created

 

Means of contact

 

Property Description
email Id of the contact
phone List of ids of contact lists in which the contact is mentioned
mobile Date of the last modification for the contact
fax Date contact created
facebookId Facebook id
twitterId Twitter id

 

Common core

 

Property Description
civility Civility
firstname First name
lastname Last name
address1 Mailing address: First address line
address2 Mailing address: Second address line
zipcode Mailing address: Postal code
city Mailing address: City
state Mailing address: State
longitude Mailing address: Longitude
latitude Mailing address: Latitude
country Mailing address: Country
birthDate Date of birth
reference Client reference of the contact
company Company

 

Variable fields

 

Property Description
field01 Variable field No. 1
... ...
field15 Variable field No. 15

 

Optout information

 

Property Description
smsOptout null, 'contact' or 'user'
emailOptout null, 'contact', 'user', 'hardbounced' or 'spam'
voiceOptout null, 'contact' or 'user'
voicemailOptout null, 'contact' or 'user'

 

Example of the resource in JSON format

 

{
   "id": "123456789",
   "listIds": [
       "2",
       "9",
       "12"
   ],
   "dateUpdated": "2013-01-02 14:00:00",
   "dateCreated": "2013-01-01 12:00:00",
   "email": "john.doo@domain.com",
   "phone": "+332000000001",
   "mobile": "+336000000001",
   "facebookId": "745932955",
   "twitterId": "14656145",
   "civility": "M.",
   "firstName": "John",
   "lastName": "DOO",
   "address1": "1 rue des Champs Elysée",
   "address2": "Bâtiment C",
   "zipcode": "75000",
   "city": "Paris",
   "country": "France",
   "state": NULL,
   "birthDate": "Paris",
   "reference": "France",
   "field01": "M.",
   "field02": "Michel",
   "field03": "DUPONT",
   "...": "1 rue des Champs Elysée",
   "field15": "Bâtiment C",
   "smsOptout": null,
   "voiceOptout": "user",
   "emailOptout": "contact",
}

Reading contacts

List of available filters

Common filters

Filter Description
id Allows you to filter according to one or more contact ids
listId Allows you to filter the contacts according to the contact lists that they are members of

 

Filters on the contact content (targeting)

 

Filter Description
email Filter according to one or more email addresses
phone Filter according to one or more fixed telephone numbers
mobile Filter according to one or more mobile telephone numbers
facebookId Filter according to one or more Facebook ids
twitterId Filter according to one or more Twitter ids
civility Filter according to one or more civilities
firstname Filter according to one or more first names
lastname Filter according to one or more last names
address1 Filter according an address line 1
address2 Filter according an address line 2
zipcode Filter according to one or more postal codes
city Filter according to one or more cities
state Filter according to one or more states
country Filter according to one or more countries
birthDate Filter according to one or more dates of birth

 

Complex filters

 

Filter Description
complex This filter allows you to combine several filters with ORs in place of the ANDs. List of available operators:
  • "CONTAINS": contains
  • "=": is equal to
  • "<>": is different from
  • "EMPTY": is empty
  • "NOT EMPTY": is defined
  • “OPTOUT": is deactivated (unsubscription, hardbounced, spam, invalid...). This operator is only available for the mobile, email, phone, facebookId and twitterId attributes

Attributes for a contact returned by default

By default, only the id, email, phone, mobile, facebookId, twitterId 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.

For example, to retrieve the default parameters and the information on unsubscription, the following must be specified

GET /rest/contacts.json HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpZCI6ImYyMzE2…
Host: contacts.messengeo.net
Content-Type: application/x-www-form-urlencoded

properties=DEFAULT,smsOptout,emailOptout,voiceOptout,voicemailOptout

Examples

Example 1: Retrieving a contact from its id

GET /rest/contacts.json HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpZCI6ImYyMzE2…
Host: contacts.messengeo.net
Content-Type: application/x-www-form-urlencoded

id=1234,5678

 

With Curl

 

curl
-X GET
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG...ccOqbVow8xOQyQ"
-d id=1234,5678
https://contacts.messengeo.net/rest/contacts

Example 2: Targeting

Retrieving 10 contacts for which the mobile contains "03" and for which the country is "France"

curl
-X GET
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG...ccOqbVow8xOQyQ"
-d limit=10
-d complex[logical]='OR'
-d complex[0][field]='mobile'
-d complex[0][operator]='CONTAINS'
-d complex[0][value]='mobile'
-d complex[1][field]='country'
-d complex[1][operator]='='
-d complex[1][value]='FRANCE'
https://contacts.messengeo.net/rest/contacts

Example 3: Targeting

Retrieving all of the contacts for whom the email address is deactivated

curl
-X GET
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG...ccOqbVow8xOQyQ"
-d email[0][operator]='OPTOUT'
https://contacts.messengeo.net/rest/contacts

Creating contacts

List of parameters to supply in order to create contacts

Parameters Description
contacts Table of contacts. Each contact is in itself a table key/value. Only the contact data listed hereinbelow is accepted: email, phone, mobile, fax, facebookId, twitterId, civility, firstName, lastName, address1, address2, zipcode, city, state, longitude, latitude, country, birthdate, reference, company, field01... field15

Validity of a contact

For a contact to be valid, one of the following five parameters has to be defined and valid:

  • Email address (email)
  • Fixed telephone number (phone)
  • Mobile telephone number (mobile)
  • Facebook id (facebookId)
  • Twitter id (twitterId)

For users for whom the uniqueness criterion is the customer reference, the reference column must be completed.

Deduplicating a contact

There are three possible deduplicating criteria:

  • No deduplicating
  • quintuplet {email, fixed, mobile, facebookid, twitterid}
  • customer reference 1 (reference attribute of each contact)

Each contract chooses his deduplicating criterion When a contact is created that already exists in the database (through its deduplicating criterion), the existing contact is updated with the properties of the new contact. 1 For this uniqueness criterion, any contact whose reference column is not defined will be considered as invalid

Return

This action returns the list of resources created.

{
    "list": [
       {
           "email": null,
           "facebookId": null,
           "firstName": "Jean",
           "id": "98117463",
           "lastName": "DUPONT",
           "mobile": null,
           "phone": "+33296300056",
           "twitterId": null
       }
    ],
    "size": 1,
    "total": null
}

Example

POST /rest/contacts HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpZCI6ImYyMzE2…
Host: contacts.messengeo.net
Content-Type: application/x-www-form-urlencoded

contacts[0][civility]=M.&contacts[0][firstName]=Jean&contacts[0][lastName]=DUPONT&contacts[0][phone]=0296300056

 

With Curl

 

curl
-X POST
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG...ccOqbVow8xOQyQ"
-d contacts[0][civility]='M.'
-d contacts[0][firstName]='Jean'
-d contacts[0][lastName]='DUPONT'
-d contacts[0][phone]='0296300056'
https://contacts.messengeo.net/rest/contacts

 

Updating a contact

List of available filters

Filter

Description

id

Allows you to select a contact to be updated according to its id

reference

Allows you to select the contacts to be updated according to its customer reference
 

List of data of the contact that can be updated

Means of contact:

  • email
  • phone
  • mobile
  • fax
  • facebookId
  • twitterId

 

Common core:

  • civility
  • firstName
  • lastName
  • address1
  • address2
  • zipcode
  • city
  • state
  • longitude
  • latitude
  • country
  • birthDate
  • reference
  • company

 

Variable fields:

  • field01
  • ...
  • field15

Return

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

{
   count: 10,
}
 

Example

PUT /rest/contacts HTTP/1.1

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpZCI6ImYyMzE2…
Host: contacts.messengeo.net
Content-Type: application/x-www-form-urlencoded

id=1234&metaData='{"name":"Mon nouveau nom de famille"}'
 

With Curl

curl

-X PUT

-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG...ccOqbVow8xOQyQ"

-d id=1234

-d metaData='{"name":"Mon nouveau nom de famille"}'

https://contacts.messengeo.net/rest/contacts
 

Deleting one or more contacts

List of available filters

Filter

Description

id

Allows you to select a contact to be updated according to its id

reference

Allows you to select the contacts to be updated according to its customer reference
 

Return

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

{
   count: 10,
}
 

Example

DELETE /rest/contacts HTTP/1.1

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpZCI6ImYyMzE2…
Host: contacts.messengeo.net
Content-Type: application/x-www-form-urlencoded

reference=ABCD
 

With Curl

curl

-X DELETE

-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG...ccOqbVow8xOQyQ"

-d reference=ABCD

https://contacts.messengeo.net/rest/contacts
 

Removing one or more contacts from sendings (action=optout)

This action allows you to remove one or more contacts from sendings without necessarily deleting them from the contact database. Typically, this action is used when the contact does not go through the unsubscription link, or a SMS STOP but when he has used another means.

List of parameters

Parameter

Description

contactIds1

Ids of the contacts that one wants to remove from sendings

listIds1

Ids of the lists of contacts that one wants to remove from sendings

media2

'SMS', 'EMAIL', 'VOICE' or 'VOICEMAIL' or a combination of the three.
 

1 Once of these two parameters is required

2 This parameter is required

Means of contact taken into account

For a contact whose email, phone and mobile fields are present, if the media filter is not used, this service will unsubscribe:

  • The Email address for the EMAIL media

  • The mobile telephone number for the SMS and VOICEMAIL media

  • The fixed telephone number for the VOICE media

Return

This action returns the number of contacts removed from sendings

{
   count: 10,
}
 

Example 1

Removing three contacts from sendings regardless of the media

curl

-X POST

-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG...ccOqbVow8xOQyQ"

-d contactIds='12,15,20'

-d media='SMS,EMAIL,VOICE,VOICEMAIL'

https://contacts.messengeo.net/rest/contacts?action=optout
 

Example 2

Removing all of the contacts of list No. 3 from sendings for the SMS and VOICE media

If you have a file that contains the list of all of your unsubscribed contacts, this is then the example to follow for removing them from sendings on the Digitaleo side.

curl

-X POST

-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG...ccOqbVow8xOQyQ"

-d listIds='3'

-d media='SMS,VOICE'

https://contacts.messengeo.net/rest/contacts?action=optout
 

Reactivating one or more contacts from sendings (action=reactivate)

This action allows you to reactivate one or more contacts for sendings. Of course, if the contact has unsubscribed since the message that he received (unsubscription link for email, SMS STOP, …), this action will not reactivate it. The action makes it possible to reactivate only those contacts that were deactivated via the optout action described hereinabove.

List of parameters

Parameter

Description

contactIds1

Ids of the contacts that one wants to reactivate

listIds1

Ids of the lists of contacts that one wants to remove from sendings

media2

'SMS', 'EMAIL', 'VOICE' or 'VOICEMAIL' or a combination of the three.

1 Once of these two parameters is required

2 This parameter is required

Means of contact taken into account

 

For a contact whose email, phone and mobile fields are present, if the media filter is not used, this service will reactivate:

  • The Email address for the EMAIL media
  • The mobile telephone number for the SMS and VOICEMAIL media
  • The fixed telephone number for the VOICE media

Return

This action returns the number of contacts reactivated

{
   count: 10,
}
 

Example 1

Reactivating three contacts for sendings regardless of the media

curl

-X POST

-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG...ccOqbVow8xOQyQ"

-d contactIds='12,15,20'

-d media='SMS,EMAIL,VOICE,VOICEMAIL'

https://contacts.messengeo.net/rest/contacts?action=reactivate
 

Example 2

Reactivating all of the contacts of list No. 3 for sendings for the SMS and VOICE media

curl

-X POST

-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG...ccOqbVow8xOQyQ"

-d listIds='3'

-d media='SMS,VOICE'

https://contacts.messengeo.net/rest/contacts?action=optout