Accedere ai dati dei contatti con API REST

Di seguito vengono descritte le funzioni per accedere ai dati dei contatti utilizzando l'API REST.

Dati dei contatti

Parametri comuni

Le operazioni di manipolazione dei dati dei contatti sono molto simili tra loro.

La richiesta è codificata come una struttura con due campi principali: "options" e "values".

Request Body campo "options"

Request Body field "values"

Questo oggetto contiene la lista dei campi da associare al nuovo contatto, usa il campo ID come chiave, ad esempio "email", "name", ecc.

Per i numeri decimali usa una stringa di tipo JSON e il separatore indicato per l'utente che esegue l'operazione.
Esempio: "decimal_number": "1234.56" o "decimal_number": "1234,56" a seconda del formato dei numeri reali indicati nelle impostazioni internazionali dell'utente.

Response Body fields

La risposta è una struttura con questi campi:

Iscrivi un contatto 

Se usi il campo Status, i valori ammessi sono: subscribed, unconfirmed, unsubscribed e suspended.

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

Risultato: un nuovo contatto viene iscritto o, se già presente, aggiornato e il suo stato corrispondente viene impostato a 'subscribed', per i parametri vedi Parametri comuni.

Esempio di richiesta:

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

Esempio di richiesta:

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

Ulteriori esempi:

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

Esempio di possibile risposta alla richiesta precedente:

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

Disiscrivi un contatto

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

Risultato: un contatto esistente viene disiscritto, i campi diversi da "status" possono essere aggiornati, per i parametri vedi Parametri comuni.

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"
    }
}

Esempio di risposta:

{
    "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

Risultato: un contatto esistente viene aggiornato, se un contatto non esiste viene creato con stato = 'subscribed', vedi Parametri comuni per i parametri.

Request Body example 1 (usando idcontact):

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

Request Body example 2 (usando primarykey e 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 di un contatto

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

Risultato: ottiene tutti i campi di un contatto

Parametri per la query:

Get a Web Tracking ID for single contact

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

Risultato: ottiene un ID Web Tracking ID per un singolo contatto.

Path parameters:

Esempio di risposta:

{
    "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}

Risultato: modifica un singolo contatto, vedi Parametri comuni per i parametri.

Parametri della query:

Update multiple contact data with batch service

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

Risultato: un contatto esistente viene modificato; se un contatto non esiste allora viene creato con lo stato = 'subscribed' (iscritto), vedi Parametri comuni per i parametri..

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
    }
]

Permessi: Manage contacts of database

Query

Query a list of contact

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

Risultato: returns a list of contacts

Vedi la documentazione sulle query per scoprire come scrivere una query di tipo SELECT sulla tabella dei contatti (CONTACTS).

Nota: se devi esportare un grande volume di dati, considera di utilizzare Bulk export API

Nota: la query MUST be escaped as every URL parameter

Parametri della query:

Esempio di query:

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

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