Accessing contacts data using the REST API

The following is a description of functions to access contacts data using the REST API.

Contacts data manipulation

Common parameters

Contact data manipulation operations are very similar one another.

Request body is encoded as a structure with two main fields: "options" and "values".

Request Body field "options"

Request Body field "values"

This object contains the list of fields to be associated to the new contact, use the field id as key, for instance "email", "name", etc.

For decimal numbers use a string JSON type and the separator indicated for the user who is performing the operation.
Example: "decimal_number": "1234.56" or "decimal_number": "1234,56" depending on the format of the real numbers indicated in the user's international settings.

Response Body fields

The response is a structure with these fields

Subscribe contact

Using the Status field, admitted values are subscribed, unconfirmed, unsubscribed and suspended.

POST https://apiserver/ws/rest/api/v19/contacts/subscribe

Result: a new contact is subscribed or, if already present, updated and its corresponding status set to 'subscribed', see Common parameters for parameters.

Request body example:

{
    "options": {
        "iddatabase": 1,
        "sendemail": true,
        "idtemplate": 8
    },
    "values": {
        "email":"myemail@domain.com"            
    }
}

Response example:

{
    "ok": false,
    "idcontact": 123,
    "action":"insert",
    "pk":"myemail@domain.com",
    "sendemail":{
        "emailsent":true,
        "emailaddress":"myemail@domain.com",
        "idsimplemessage":1
    },
    "enterworkflow": null
}

Further request body example:

{
    "options": {
        "iddatabase": 1,
        "enterworkflow": true,
        "enterworkflowonactions":"insert",
        "key": "contactadded"
    },
    "values": {
        "email":"myemail@domain.com"            
    }
}

Example of possible response to previous request:

{
    "ok": true,
    "idcontact": 123,
    "action":"insert",
    "pk":"myemail@domain.com",
    "enterworkflow":{
        "workflowentered":true,
        "idworkflowsessions": [1, 3, 5]
    },
    "sendemail": null
}

Unsubscribe contact

POST https://apiserver/ws/rest/api/v19/contacts/unsubscribe

Result: an existing contact is unsubscribed, fields other than "status" can be updated, see Common parameters for parameters.

Request Body example 1 (using idcontact):

{
  "values": {
    "idcontact":65,
    "CAUSA_ELIMINAZIONE":1
  }
} 

Request Body example 2 (using primarykey and iddatabase):

{
    "options": {            
        "iddatabase": 1           
    },
    "values": {
        "email":"myemail@domain.com"
    }
}

Request Body example 3 (using sendemail):

{
    "options": {            
        "iddatabase": 1,      
        "sendemail": true,
        "sendemailonactions": "update,delete",
        "idtemplate": 8     
    },
    "values": {
        "email":"myemail@domain.com"
    }
}

Response example:

{
    "ok": false,
    "idcontact": 65,
    "action":"insert",
    "pk":"myemail@domain.com",
    "errors": null,
    "sendemail": null,
    "enterworkflow": null
}

Update single contact data using the primary key

POST https://apiserver/ws/rest/api/v19/contacts/merge

Result: an existing contact is updated, if a contact does not exist, then it is created with status='subscribed', see Common parameters for parameters.

Request Body example 1 (using idcontact):

{
    "options": {            
    },
    "values": {
        "idcontact":65            
    }
}

Request Body example 2 (using primarykey and iddatabase):

{
    "options": {            
        "iddatabase": 1           
    },
    "values": {
        "email":"myemail@domain.com"
    }
}

Response example:

{
    "ok": false,
    "idcontact": 65,
    "action":"insert",
    "pk":"myemail@domain.com",
    "errors": null,
    "sendemail": null,
    "enterworkflow": null
}

Get single contact

GET https://apiserver/ws/rest/api/v19/contacts/contact/{idcontact}

Result: gets every field of a single contact

Query parameters:

Get a Web Tracking ID for single contact

GET https://apiserver/ws/rest/api/v19/webtracking/contact/{idcontact}

Result: gets a Web Tracking ID for a single contact

Path parameters:

Response example:

{
    "idcontact": 1234,
    "idwebtracking": "xxxxxxxxx",
    "idaddressbook": 5555,
    "primaryKey": "foo@example.com"
}

Update single contact by ID

POST https://apiserver/ws/rest/api/v19/contacts/contact/{idcontact}

Result: update a single contact, see Common parameters for parameters

Query parameters:

Update multiple contact data with batch service

POST https://apiserver/ws/rest/api/v19/contacts/batchmerge

Result: an existing contact is updated, if a contact does not exist, then it is created with status='subscribed', see Common parameters for parameters.

Return values: List of MergeResult

Request Body example:

{
        "iddatabase":1,
        "options":{            
            "denyupdatecontact":true           
        },
        "contacts":[
            {"values":[
                {
                    "field":"email",
                    "value":"myemail@domain.com"
                },
                {
                    "field":"NAME",
                    "value":"name1"
                }
            ]},
            {"values":[
                {
                    "field":"email",
                    "value":"myemail2@domain.com"
                },
                {
                    "field":"NAME",
                    "value":"name2"
                }
            ]}
        ]
    }
    

Response example:

[
    {
        "ok":true,
        "idcontact":1,
        "action":"insert",
        "pk":"myemail1@domain.com",
        "errors": null,
        "sendemail":null,
        "enterworkflow":null,
        "idwebtracking":null
    },
    {
        "ok":false,
        "idcontact":65,
        "action":"update",
        "pk":"myemail2@domain.com",
        "errors": 
            [{
                "type":"ACTION_NOT_ALLOWED",
                "field":null
            }],
        "sendemail":null,
        "enterworkflow":null,
        "idwebtracking":null
    }
]

Permissions: Manage contacts of database

Queries

Query a list of contact

GET https://apiserver/ws/rest/api/v19/contacts/query?query=QUERY

Result: returns a list of contacts

See query documentation in order to learn how to write a SELECT query of the CONTACTS table

Note: if you have to export a large volume of data, consider using the Bulk export API

Note: the query MUST be escaped as every URL parameter

Query parameters:

Query examples:

query=SELECT * FROM CONTACTS WHERE email='myemail@domain.com' and iddatabase=6

query=SELECT * FROM CONTACTS WHERE email='myemail@domain.com' and iddatabase=6