Utilizzare l'API dell'utilità di importazione contatti in blocco

Con ActiveCampaign, puoi utilizzare l'API Bulk Contact Importer per caricare un gran numero di contatti nel tuo account con una sola chiamata API.

Prendi nota

  • L'API Bulk Contact Importer è disponibile su tutti i piani ActiveCampaign
  • Questa funzione è per gli utenti avanzati che hanno familiarità con l'API e sono a proprio agio nell'usarla per importare contatti

Informazioni sull'API dell'utilità di importazione contatti in blocco

L'importatore di contatti alla rinfusa è progettato per eseguire operazioni su grandi quantità di contatti contemporaneamente. Queste operazioni comprendono:

  • Creazione di nuovi contatti
  • Aggiornamento dei contatti esistenti
  • Impostazione dei campi nei contatti
  • Tag dei contatti
  • Aggiunta di contatti alle liste

Note

L'importatore di contatti in blocco non è progettato per supportare operazioni frequenti che coinvolgono un numero limitato di contatti o per sincronizzare gli aggiornamenti in tempo reale da un database esterno. Al contrario, gli aggiornamenti dei contatti devono essere raccolti in batch più grandi e importati come gruppo. I contatti possono essere importati in lotti fino a 250 articoli.

Se è necessario caricare 10 o meno contatti alla volta, utilizzare la funzionalità Contatti della nostraAPI ActiveCampaign V3.  

Limitazione della velocità

Il processo di importazione di massa è ottimizzato per il caricamento di elenchi più grandi di contatti. L'esecuzione di richieste frequenti che coinvolgono un numero limitato di contatti richiede un sovraccarico significativo e può influire sulle prestazioni ’ dell'importatore. Di conseguenza, applichiamo i seguenti limiti di tariffa all'API dell'utilità di importazione dei contatti in blocco:

  • Per le richieste contenenti un singolo contatto, è disponibile un limite di 20 richieste al minuto
  • Per le richieste contenenti più contatti, è disponibile un limite di 100 richieste al minuto

È consigliabile che tutti gli utenti tentino di eseguire il batch degli aggiornamenti in gruppi il più grande possibile prima di avviare un'importazione.

Limitazione delle dimensioni del carico utile

La dimensione massima del payload di una singola bulk_import richiesta è di 400000 byte.

Contatti ignorati

I contatti devono soddisfare tutti i criteri seguenti per poter essere creati o aggiornati con questa API:

  • I contatti importati potrebbero non superare il limite dell'account
  • Il contatto deve avere un indirizzo e-mail
  • L'indirizzo ’ di posta elettronica del contatto non deve essere in un elenco di esclusione
  • L'e-mail del contatto non deve essere in un elenco di indirizzi e-mail rimbalzati
  • Il contatto non deve aver annullato l'iscrizione a un elenco a cui l'importazione li aggiungerà

Se i contatti non soddisfano tutti questi requisiti, verranno ignorati dall'importatore.

Documentazione API

POST https://youraccountname.api-us1.com/api/3/import/bulk_import

Struttura delle richieste

JSON
•
Contatti:
    •
        "email": "someone@somewhere.com",
        Nome Jane
        Cognome "Doe",
        Telefono 5
		"customer_acct_name": ActiveCampaign
        Tag
            		"dictumst aliquam augue quam sollicitudin rutrum",
        		•
        Campi
Id 1, "value": "foo"},
Id 2,"value": "foo||bar||baz"}
        •
        "subscribe": [{"listid": 1}, {"listid": 2
        "unsubscribe": [{"listid": 3
    •
•
"callback": <facoltativo, vedere di seguito>
•

Risposta
200 OK
•
Successo:
"queued_contacts":1,
"batchId":"0641fbdd-f62f-4c2c-ba02-3a83d5d11ac9",
"messaggio":"Importazione contatti in coda"
•
 
400 Richiesta non richiesta
•
Successo:
"messaggio":"Payload JSON non ha superato la convalida. Correggere i guastiMotivo e riprovare. L'importazione non è stata accodata per l'elaborazione.",
"failureReasons":["Il payload deve contenere un campo 'contatti'"]
}

 

Params corpo

matrice contacts* (oggetto)

Matrice di oggetti contenenti informazioni su un singolo contatto. Fino a 250 contatti possono essere inclusi in una singola richiesta. Ogni contatto può contenere i seguenti campi:

  • email* (stringa)
    E-mail del contatto.
  • first_name (stringa)
    Nome del contatto.
  • last_name (stringa)
    Cognome del contatto.
  • telefono (stringa)
    Numero di telefono del contatto.
  • customer_acct_name (stringa)
    Nome dell'account del contatto.
  • tag array (stringa)
    Ogni stringa nella matrice verrà aggiunta come singolo tag al contatto. I nuovi tag verranno creati se non esistono già.
  • matrice fields (oggetto)
    Elenco di campi personalizzati da applicare al contatto. Ogni campo deve contenere due campi: Ogni contatto può avere fino a N campi personalizzati.
  • id*   (numero)
    ID del campo personalizzato. Ai campi personalizzati deve essere fatto riferimento dall'ID assegnato loro da ActiveCampaign. È possibile recuperare il numero ID per un campo personalizzato utilizzando la chiamata API "Elenca tutti i campi personalizzati".
  • valore*   (stringa)
    Valore del campo personalizzato. È possibile popolare più valori per i campi multi-valore separando i valori diversi dal delimitatore a doppia pipe ( “ || ” ).
  • subscribe array (oggetto)
    Matrice di elenchi a cui sottoscrivere il contatto. I contatti non possono essere sottoscritti a elenchi da cui hanno precedentemente annullato l'iscrizione. Ogni oggetto elenco contiene un singolo campo.
  • listid* (numero)
    ID dell'elenco a cui sottoscrivere il contatto. È necessario fare riferimento agli elenchi in base all'ID assegnato loro da ActiveCampaign.

    È possibile trovare l'ID elenco facendo clic sull'elenco nell'account ActiveCampaign, quindi visualizzando la barra degli URL. Avrà un aspetto simile al seguente: /app/contatti/? listid=19&stato=1

    È inoltre possibile recuperare il numero ID di un elenco utilizzando la chiamata API "Recupera tutti gli elenchi".
  • annullare la sottoscrizione alla matrice (oggetto)
    Matrice di elenchi a cui annullare l'iscrizione al contatto. Ogni oggetto elenco contiene un singolo campo.
  • listid*   (numero)
    ID dell'elenco da cui annullare l'iscrizione al contatto. È necessario fare riferimento agli elenchi in base all'ID assegnato loro da ActiveCampaign.

    È possibile trovare l'ID elenco facendo clic sull'elenco in ActiveCampaign, quindi visualizzando la barra degli URL. Avrà un aspetto simile al seguente: /app/contatti/? listid=19&stato=1

    È inoltre possibile recuperare il numero ID di un elenco utilizzando la chiamata API "Recupera tutti gli elenchi".

Callback

L'endpoint contatto di massa dispone di una funzione di callback per notificare agli utenti quando un'importazione è completata. Includere le informazioni seguenti in una richiesta di importazione contatti per l'utilizzo di questa funzionalità:

JSON
•
“url”: “www.your_web_server.com”,
"contatti": [ ... includere i contatti qui ... ],
“callback ” : {
	“requestType”: “POST ” ,
	“detailed_results: ”“ vero ” ,
	“parametri ” : [
		{“key”:””,”value”:””}
    •
	“intestazioni ” : [
		{“key”:””,”value”:””}
    •
•
}
  • URL   (stringa)
    Endpoint URL a cui l'utilità di importazione farà una richiesta una volta completata l'importazione.
  • requestType (stringa)
    Può essere impostato su “ GET ” o POST “” . Determina il tipo di richiesta HTTP che verrà inviata all'endpoint specificato.
  • detailed_results (stringa)
    Se impostato su “ true ” e il parametro requestType è impostato “ su POST , il ” callback includerà il numero di successi e errori nella richiesta di origine, nonché una matrice di messaggi di errore per ogni contatto non riuscito.
  • parami   (matrice)
    Elenco di parametri da includere nella richiesta di richiamata. Aggiungere ogni parametro sotto forma di coppia chiave-valore. Per una richiesta GET, ogni parametro verrà aggiunto alla fine dell'URL in una stringa di query. Per una richiesta POST, i parametri saranno inclusi nel corpo della richiesta. 
  • intestazioni (matrice)
    Elenco di intestazioni da includere nella richiesta di richiamata. Aggiungere ogni intestazione sotto forma di coppia chiave-valore.

Esempi

Ricezione di una notifica

{
"contatti": [ ... includere i contatti qui ... ],
“callback ” : {
	“url”: “www.yourwebsite.com/the/api/to/hit”,
    “requestType”: “OTTIENI ” ,
	“parametri ” : [
		{“key”:”msg”,”value”:”hello”}
    •
	“intestazioni ” : [
		{“key”:””,”value”:””}
    •
•
}

 

I parametri verranno aggiunti all'URL come parametri di query nel caso di una “ richiesta ” GET. Le intestazioni verranno applicate alla richiesta prima che venga inviata. Questo endpoint accetta qualsiasi valore stringa sia per le chiavi che per i valori sia per i parametri che per le intestazioni.

Risultato:

GET www.yourwebsite.com/the/api/to/hit?msg=hello

Invio di un messaggio

{
"contatti": [ ... includere i contatti qui ... ],
“callback ” : {
	“requestType”: “POST ” ,
	“parametri ” : [
		{“key”:”msg”,”value”:”Import completed”}
    •
	“intestazioni ” : [
		{“key”:”Authorization”,”value”:”Bearer 4u1h_t0k3N”}
    •
•
}

 

Risultato:

GET www.yourwebsite.com/the/api/to/hit

JSON
•
{“key”:”msg”,”value”:”Import completed”}
]

 

Importare risultati con messaggi di errore

{
"contatti": [ ... includere i contatti qui ... ],
“callback ” : {
	“requestType”: “POST ” ,
	“detailed_results: ”“ vero ” ,
	“intestazioni ” : [
		{“key”:””,”value”:””}
    •
•
}

 

Quando il “ detailed_results ” è impostato su "True", il callback includerà:

  • Oggetto JSON contenente i parametri specificati
  • Altri tre campi della risposta che possono aiutare con il monitoraggio e il debug

Risultato:

GET www.yourwebsite.com/the/api/to/hit

JSON
•
Successo:
"Errori":0,
"failure_reasons":[]
}
Questo articolo ti è stato utile?
Utenti che ritengono sia utile: 1 su 5

Have more questions? Submit a request

Start free trial