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
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
- Queste operazioni comprendono:
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
- Al contrario, gli aggiornamenti dei contatti devono essere raccolti in batch più grandi e importati come gruppo.
Nota bene
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 hai bisogno di caricare 10 o meno contatti alla volta, utilizza la funzionalità Contatti della nostra API ActiveCampaign V3.
Limitazione del tasso
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 tasso 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 del payload di una singola richiesta bulk_import deve essere inferiore a 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 email
Se i contatti non soddisfano tutti questi requisiti, verranno ignorati dall'importatore.
- L'indirizzo email del contatto non deve essere in un elenco di esclusione
- L'email del contatto non deve essere in un elenco di indirizzi email respinti
- 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
POSTA https://youraccountname.api-us1.com/api/3/import/bulk_import
Struttura delle richieste
JSON
{
"contacts": [{"email": "someone@somewhere.com",
"first_name": "Jane","last_name": "Doe","phone": "123-456-7890","customer_acct_name": "ActiveCampaign","tags": ["dictumst aliquam augue quam sollicitudin rutrum",],"fields": [
{
"id": 1,
"value": "pippo"},
{"id": 2,"value": "pippo|| bar|| baz"}
],
"subscribe": [{"listid": 1}, {"listid": 2}],"unsubscribe": [{"listid": 3}],}],"callback":
}
Risposta
200 OK
{
"Success":1,"queued_contacts":1,"batchId":"0641fbdd-f62f-4c2c-ba02-3a83d5d11ac9",
"message":"Importazione contatti in coda"
}
400 Bad Request
{
"Success":0,
"message":"Il 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 Contatti* (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* (string)
L'indirizzo email del contatto. - first_name (stringa)
Nome del contatto. - last_name (stringa)
Il cognome del contatto. - phone (string)
Il numero di telefono del contatto. - customer_acct_name (stringa)
Nome dell'account del contatto. - matrice tags (stringa)
Ogni stringa nella matrice verrà aggiunta come singolo tag al contatto. I nuovi tag verranno creati se non esistono già. - matrice campi (oggetto)
Un 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". - value* (string)
Il valore del campo personalizzato. È possibile popolare più valori per i campi multi-valore separando i valori diversi dal delimitatore a doppia pipe ( “ || ” ). - subscribe array (object)
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. - Ogni oggetto elenco contiene un singolo campo.
listid* (numero)L'ID dell'elenco da cui annullare l'iscrizione al contatto. È necessario fare riferimento agli elenchi in base all'ID assegnato loro da ActiveCampaign.
Puoi trovare l'ID lista facendo clic sull'elenco nel tuo account ActiveCampaign e visualizzando la barra degli URL. Sarà simile a questo: /app/contacts/?listid=19&status=1
È inoltre possibile recuperare il numero ID per un elenco utilizzando la chiamata API "Recupera tutte le liste". - Matrice di annullamento dell'iscrizione (oggetto)
Matrice di elenchi a cui annullare l'iscrizione del contatto. Ogni oggetto elenco contiene un singolo campo.
listid* (numero)L'ID dell'elenco da cui annullare l'iscrizione al contatto. È necessario fare riferimento agli elenchi in base all'ID assegnato loro da ActiveCampaign.
Puoi trovare l'ID lista facendo clic sull'elenco in ActiveCampaign e visualizzando la barra degli URL. Sarà simile a questo: /app/contacts/?listid=19&status=1
È inoltre possibile recuperare il numero ID per un elenco utilizzando la chiamata API "Recupera tutte le liste".
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
{
"contacts": [ ... Includi contatti qui ... ],"callback": {"url": "www.your_web_server.com","requestType": "POST","detailed_results": "true",
"params": [{"key":"","value":"}]"headers": [
{
"key":"","value":""}]
}}
- url (stringa)
L'endpoint URL a cui l'utilità di importazione effettuerà una richiesta al termine dell'importazione. - requestType (string)
Può essere impostato su "GET" o "POST". Determina il tipo di richiesta HTTP che verrà inviata all'endpoint specificato. - detailed_results (string)
Se impostato su "true" e il parametro requestType è impostato su "POST", il callback includerà il numero di operazioni riuscite e non riuscite nella richiesta di origine, nonché una matrice di messaggi di errore per ogni contatto non riuscito. - params (array)
Un elenco di parametri da includere nella richiesta di callback. 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. - Header (matrice)
- Elenco di header da includere nella richiesta di richiamata. Aggiungere ogni header sotto forma di coppia chiave-valore.
Esempi
Ricezione di una notifica
{
"contatti": [ ... includi contatti qui ... ],"callback": {"url": "www.yourwebsite.com/the/api/to/hit","requestType": "GET",
"params": [{"key":"msg","value":"hello"}]"headers": [
{
"key":"","value":""}]
}}
I parametri verranno aggiunti all'URL come parametri di query nel caso di una “ richiesta ” GET. Gli header 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 gli header.
Risultato:
OTTIENI www.yourwebsite.com/the/api/to/hit?msg=hello
Invio di un messaggio
{
"contatti": [ ... includi contatti qui ... ],"callback": {"requestType": "POST",
"params": [{"key":"msg","value":"Import completed"}]"headers": [
{
"key":"Authorization","value":"Bearer 4u1h_t0k3N"}]
}}
Risultato:
OTTIENI www.yourwebsite.com/the/api/to/hit
JSON
[
{"key":"msg","value":"Importazione completata"}
]
Importare risultati con messaggi di errore
{
"contatti": [ ... includi contatti qui ... ],"callback": {"requestType": "POST","detailed_results": "true",
"headers": [
{
"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:
OTTIENI www.yourwebsite.com/the/api/to/hit
JSON
{
"Success":1,"Failures":0,
"failure_reasons":[]
}