Verwenden Sie die Bulk Contact Importer API

Mit ActiveCampaign können Sie die Bulk Contact Importer API verwenden, um eine große Anzahl von Kontakten mit nur einem API-Aufruf in Ihr Konto hochzuladen.

Zur Kenntnis nehmen

  • Die Bulk Contact Importer API ist für alle ActiveCampaign-Tarife verfügbar
  • Diese Funktion ist für fortgeschrittene Benutzer gedacht, die mit der API vertraut sind und sie problemlos zum Importieren von Kontakten verwenden können

Über die Bulk Contact Importer API

Der Bulk-Kontakt-Importer wurde entwickelt, um Operationen an großen Mengen von Kontakten auf einmal durchzuführen. Diese Vorgänge umfassen:

  • Neue Kontakte anlegen
  • Vorhandene Kontakte aktualisieren
  • Felder an Kontakten einstellen
  • Kontakte markieren
  • Hinzufügen von Kontakten zu Listen

Anmerkung

Der Bulk Contact Importer ist nicht dafür ausgelegt, häufige Vorgänge mit einer kleinen Anzahl von Kontakten zu unterstützen oder Aktualisierungen in Echtzeit mit einer externen Datenbank zu synchronisieren. Stattdessen sollten die Kontaktaktualisierungen in größeren Stapeln gesammelt und als Gruppe importiert werden. Kontakte können in Stapeln von bis zu 250 Elementen importiert werden.

Wenn Sie 10 oder weniger Kontakte auf einmal hochladen müssen, verwenden Sie bitte die Kontakte-Funktionalität unserer ActiveCampaign API V3

Tarifbegrenzung

Der Bulk-Importer-Prozess ist für das Hochladen größerer Listen von Kontakten optimiert. Die Ausführung häufiger Anfragen, die eine kleine Anzahl von Kontakten betreffen, erfordert einen erheblichen Overhead und kann die Leistung des Importers’beeinträchtigen. Aus diesem Grund erzwingen wir die folgenden Ratenbeschränkungen für die Bulk Contact Importer API:

  • Für Anfragen, die einen einzelnen Kontakt enthalten, gibt es ein Limit von 20 Anfragen pro Minute
  • Für Anfragen, die mehrere Kontakte enthalten, gibt es ein Limit von 100 Anfragen pro Minute

Wir empfehlen, dass alle Benutzer versuchen, Updates in möglichst großen Gruppen zu bündeln, bevor sie einen Import starten.

Begrenzung der Nutzlastgröße

Die maximale Nutzdatengröße einer einzelnen bulk_import-Anfrage beträgt 400000 Bytes.

Übersprungene Kontakte

Kontakte müssen alle folgenden Kriterien erfüllen, damit sie mit dieser API erstellt oder aktualisiert werden können:

  • Die importierten Kontakte dürfen Ihr Kontolimit nicht überschreiten
  • Der Kontakt muss eine E-Mail-Adresse haben
  • Die E-Mail-Adresse der Kontaktperson’darf nicht in einer Ausschlussliste stehen.
  • Die E-Mail des Kontakts’darf nicht auf einer Liste mit abgelehnten E-Mail-Adressen stehen.
  • Der Kontakt darf sich nicht von einer Liste abgemeldet haben, zu der der Import ihn hinzufügen würde

Wenn die Kontakte nicht alle diese Anforderungen erfüllen, werden sie vom Importeur übersprungen.

API-Dokumentation

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

Struktur anfordern

JSON
{
"contacts": [
    {
        "E-Mail": "someone@somewhere.com",
        Vorname Jane
        Nachname "Doe",
        Telefon 123-456-7890.
		"kunden_accct_name": ActiveCampaign
        "tags": [
            		"dictumst aliquam augue quam sollicitudin rutrum",
        		],
        "Felder": [
ID 1, "Wert": "foo"},
ID 2, "Wert": "foobarbaz"}
        ],
        "abonnieren": [{"listid": 1}, {"listid": 2.
        "abbestellen": [{"listid": 3.
    }
],
"callback": <optional, siehe unten>
}

Antwort
200 OK
{
Erfolg:
"queued_contacts":1,
"batchId": "0641fbdd-f62f-4c2c-ba02-3a83d5d11ac9",
"Nachricht": "Kontaktimport in der Warteschlange"
}
 
400 Schlechte Anfrage
{
Erfolg:
"message": "JSON-Payload hat die Validierung nicht bestanden. Bitte fixieren Sie failureReasons und versuchen Sie es erneut. Der Import stand nicht in der Warteschlange für die Verarbeitung.",
"failureReasons":["Payload muss ein 'contacts'-Feld enthalten"]
}

 

Körper-Parameter

Kontakte* Array (Objekt)

Ein Array von Objekten, das Informationen über einen einzelnen Kontakt enthält. Es können bis zu 250 Kontakte in einer einzigen Anfrage enthalten sein. Jeder Kontakt kann die folgenden Felder enthalten:

  • email* (Zeichenkette)
    Der Kontakt’s E-Mail.
  • first_name (string)
    Der Vorname des Kontakts’.
  • last_name (string)
    Der Nachname des Kontakts’.
  • Telefon (Zeichenkette)
    Die Telefonnummer des Kontakts’.
  • customer_acct_name (string)
    Der Name des Kontakts’s Konto.
  • tags array (Zeichenkette)
    Jede Zeichenkette im Array wird als einzelnes Tag zum Kontakt hinzugefügt. Es werden neue Tags erstellt, wenn sie nicht bereits vorhanden sind.
  • fields array (Objekt)
    Eine Liste von benutzerdefinierten Feldern, die auf den Kontakt angewendet werden sollen. Jedes Feld muss zwei Felder enthalten: Jeder Kontakt kann bis zu N benutzerdefinierte Felder haben.
  • id* (Nummer)
    Die ID des benutzerdefinierten Feldes. Benutzerdefinierte Felder müssen über die ID referenziert werden, die ActiveCampaign ihnen zuweist. Sie können die ID-Nummer für ein benutzerdefiniertes Feld abrufen, indem Sie den API-Aufruf "Alle benutzerdefinierten Felder auflisten" verwenden.
  • Wert* (String)
    Der Wert des benutzerdefinierten Feldes. Bei mehrwertigen Feldern können mehrere Werte aufgefüllt werden, indem die verschiedenen Werte durch das Doppelrohrtrennzeichen (“” ) getrennt werden.
  • Array abonnieren (Objekt)
    Ein Array von Listen, bei denen der Kontakt abonniert werden soll. Kontakte können nicht in Listen eingetragen werden, von denen sie sich zuvor abgemeldet haben. Jedes Listenobjekt enthält ein einzelnes Feld.
  • listid* (Zahl)
    Die ID der Liste, in der der Kontakt abonniert werden soll. Listen müssen über die ID referenziert werden, die ActiveCampaign ihnen zuweist.

    Sie können die Listen-ID finden, indem Sie in Ihrem ActiveCampaign-Konto auf die Liste klicken und dann die URL-Leiste anzeigen. Es wird in etwa so aussehen: /app/contacts/?listid=19&status=1

    Sie können die ID-Nummer für eine Liste auch mit dem API-Aufruf "Alle Listen abrufen" abrufen.
  • Abmelde-Array (Objekt)
    Ein Array von Listen, in die der Kontakt abgemeldet werden soll. Jedes Listenobjekt enthält ein einzelnes Feld.
  • listid* (Nummer)
    Die ID der Liste, aus der der Kontakt abgemeldet werden soll. Listen müssen über die ID referenziert werden, die ActiveCampaign ihnen zuweist.

    Sie können die Listen-ID finden, indem Sie auf die Liste in Ihrer ActiveCampaign klicken und dann die URL-Leiste anzeigen. Es wird in etwa so aussehen: /app/contacts/?listid=19&status=1

    Sie können die ID-Nummer für eine Liste auch mit dem API-Aufruf "Alle Listen abrufen" abrufen.

Rückrufe

Der Massenkontakt-Endpunkt verfügt über eine Callback-Funktion, um Benutzer zu benachrichtigen, wenn ein Import abgeschlossen ist. Fügen Sie die folgenden Informationen in eine Kontaktimportanfrage ein, um diese Funktion zu nutzen:

JSON
{
“url”: “www.your_web_server.com”,
"Kontakte": [ ... hier Kontakte einfügen ... ],
“Rückruf”: {
	“requestType”: “POST”,
	“detailed_results”: “true”,
	“params”: [
		{“Schlüssel”:””,”Wert”:””}
    ]
	“headers”: [
		{“Schlüssel”:””,”Wert”:””}
    ]
}
}
  • url (string)
    Der URL-Endpunkt, an den der Importer eine Anfrage stellt, sobald der Import abgeschlossen ist.
  • requestType (Zeichenkette)
    Kann entweder auf “GET” oder “POST” gesetzt werden. Legt den Typ der HTTP-Anfrage fest, die an den angegebenen Endpunkt gesendet wird.
  • detailed_results (string)
    Wenn “true” und der requestType-Parameter auf “POST” gesetzt ist, enthält der Callback die Anzahl der Erfolge und Misserfolge in der Ursprungsanforderung sowie ein Array mit Fehlermeldungen für jeden fehlgeschlagenen Kontakt.
  • params (Array)
    Eine Liste von Parametern, die in die Callback-Anforderung aufgenommen werden sollen. Fügen Sie jeden Parameter in Form eines Schlüssel-Wert-Paares hinzu. Bei einer GET-Anfrage wird jeder Parameter in einem Query-String an das Ende der URL angehängt. Bei einer POST-Anforderung werden die Parameter in den Körper der Anforderung aufgenommen. 
  • Kopfzeilen (Array)
    Eine Liste von Kopfzeilen, die in die Callback-Anforderung aufgenommen werden sollen. Fügen Sie jeden Header in Form eines Schlüssel-Wert-Paares hinzu.

Beispiele

Empfangen einer Benachrichtigung

{
"Kontakte": [ ... hier Kontakte einfügen ... ],
“Rückruf”: {
	“url”: “www.yourwebsite.com/the/api/to/hit”,
    “requestType”: “GET”,
	“params”: [
		{“key”:”msg”,”value”:”hello”}
    ]
	“headers”: [
		{“Schlüssel”:””,”Wert”:””}
    ]
}
}

 

Params werden im Falle einer “GET” Anfrage als Abfrageparameter an die URL angehängt. Kopfzeilen werden auf die Anfrage angewendet, bevor sie gesendet wird. Dieser Endpunkt akzeptiert beliebige Zeichenkettenwerte für Schlüssel und Werte für Params und Header.

Ergebnis:

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

Senden einer Nachricht

{
"Kontakte": [ ... hier Kontakte einfügen ... ],
“Rückruf”: {
	“requestType”: “POST”,
	“params”: [
		{“key”:”msg”,”value”:”Import completed”}
    ]
	“headers”: [
		{“key”:”Authorization”,”value”:”Bearer 4u1h_t0k3N”}
    ]
}
}

 

Ergebnis:

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

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

 

Importergebnisse mit Fehlermeldungen

{
"Kontakte": [ ... hier Kontakte einfügen ... ],
“Rückruf”: {
	“requestType”: “POST”,
	“detailed_results”: “true”,
	“headers”: [
		{“Schlüssel”:””,”Wert”:””}
    ]
}
}

 

Wenn der Parameter “detailed_results” auf "True" gesetzt ist, enthält der Callback:

  • Ein JSON-Objekt mit den angegebenen Parametern
  • Drei weitere Felder in der Antwort, die bei der Überwachung und Fehlersuche helfen können

Ergebnis:

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

JSON
{
Erfolg:
"Ausfälle":0,
"failure_reasons":[]
}
Haben Sie Fragen? Anfrage einreichen