Kontaktdaten mit ZoomInfo in Jitterbit Studio bereichern

Einführung

ZoomInfo stellt B2B-Kontakt- und Unternehmensdaten über eine REST-API bereit. Diese Anleitung zeigt, wie man den HTTP v2-Connector nutzt, um sich bei ZoomInfo zu authentifizieren, einen wiederverwendbaren Ressourcen-Router erstellt, der benannte Endpunkttypen auf API-Pfade abbildet, und diesen Router dann einsetzt, um Kontakte zu suchen, vorhandene Kontaktdatensätze zu bereichern und Unternehmensdaten abzurufen.

Das Schlüsselmuster in dieser Anleitung ist ein Case-basierter Ressourcen-Router: Ein einzelnes Skript bildet einen Ressourcennamen wie contact oder company auf den entsprechenden ZoomInfo-API-Pfad ab, und eine zentrale HTTP v2 POST-Operation verarbeitet alle API-Aufrufe. Dies macht die Integration wiederverwendbar: Das Hinzufügen eines neuen ZoomInfo-Endpunkts erfordert nur eine einzeilige Ergänzung des Router-Skripts, ohne dass zusätzliche Verbindungs- oder Aktivitätskonfiguration nötig ist.

Diese Anleitung setzt ein ZoomInfo-Konto mit API-Zugriffsanmeldedaten (Benutzername und Passwort) voraus.

Designmuster

Die Authentifizierung wird einmalig zu Beginn des Workflows ausgeführt, um ein JWT zu erhalten. Alle nachfolgenden ZoomInfo-Aufrufe folgen derselben Sequenz:

Der Router und die POST-Activity werden über alle ZoomInfo-API-Aufrufe hinweg gemeinsam genutzt.

Die Tabelle zeigt den konzeptionellen Ablauf. In der Implementierung befinden sich der Ressourcen-Router und die POST-Activity als Schritte innerhalb einer gemeinsamen Operation (der zentralen POST-Operation in Teil 3), während die Anfrageerstellung und Antwortenverarbeitung separate, wiederverwendbare Operationen sind, die du pro Ressourcentyp erstellst und mit RunOperation aufrufst (siehe Teil 4).

Teil 1: Projektvariablen und die HTTP v2-Verbindung konfigurieren

Schritt 1: Projektvariablen erstellen

Speichere Anmeldedaten und das JWT zur Laufzeit in Projektvariablen, damit sensible Werte nicht in Skripten oder Aktivitätskonfigurationen hartcodiert sind.

Öffne das Projektaktionsmenü und wähle Projektvariablen. Füge dann hinzu:

Markiere zoom.password und zoom.jwt als verborgen. Hinweise zur sicheren Speicherung von Anmeldedaten findest du unter Endpunkt-Anmeldedaten verwalten.

Schritt 2: Die HTTP v2-Verbindung konfigurieren

1. Öffne in Studio dein Projekt und klicke auf die Registerkarte Projektendpunkte und Connectoren in der Design-Komponentenpalette.

2. Klicke auf den HTTP v2-Connector, um den Verbindungskonfigurationsbildschirm zu öffnen.

3. Verbindungsname: Gib ZoomInfo API ein.

4. Basis-URL: Gib https://api.zoominfo.com ein.

5. Authentifizierung: Wähle Bearer Token und gib [$zoom.jwt] als Token-Wert ein. Die Projektvariable zoom.jwt ist leer, wenn das Projekt zum ersten Mal ausgeführt wird. Die Authenticate-Operation in Teil 2 füllt sie, bevor ein anderer ZoomInfo-Aufruf erfolgt. Der /authenticate-Endpunkt selbst validiert den Authorization-Header nicht, daher verursacht ein leeres Token beim ersten Aufruf keinen Fehler.

6. Klicken Sie auf Test, um die Verbindung zu überprüfen, und klicken Sie dann auf Änderungen speichern.

Teil 2: JWT authentifizieren und speichern

ZoomInfo verwendet ein JWT-basiertes Authentifizierungsmodell. Vor jedem API-Aufruf sendet eine Operation Anmeldedaten an den Endpunkt /authenticate und speichert das zurückgegebene JWT in zoom.jwt.

Schritt 1: Die Authentifizierungsoperation erstellen

1. Erstellen Sie eine neue Operation und nennen Sie sie core.ZoomInfo - Get Auth Token.

2. Fügen Sie einen Transformation-Schritt hinzu. Definieren Sie in der Transformation ein JSON-Zielschema mit zwei Feldern: username und password. Ordnen Sie [$zoom.username] und [$zoom.password] den jeweiligen Feldern zu.

3. Ziehen Sie eine POST-Aktivität aus der ZoomInfo API-Verbindung nach der Transformation als Ziel.

4. Doppelklicken Sie auf die POST-Aktivität, um ihre Konfiguration zu öffnen.

5. Name: Geben Sie ZoomInfo - Authenticate ein.

6. Path: Geben Sie /authenticate ein.

7. Fügen Sie auf der Registerkarte Request einen Content-Type-Header mit dem Wert application/json hinzu.

8. Klicken Sie auf Finished.

Schritt 2: JWT extrahieren und speichern

Fügen Sie nach der POST-Aktivität einen Script-Schritt hinzu. Das Skript liest das JWT aus $jitterbit.response, das den unformatierten Antwortkörper der vorherigen HTTP-Aktivität enthält, und speichert es in der Projektvariablen:

$zoom.jwt = TrimChars(GetJSONString($jitterbit.response, "/jwt"), "\"");
If(length(trim($zoom.jwt)) == 0,
    RaiseError("ZoomInfo authentication failed. Response: " + $jitterbit.response)
);
WriteToOperationLog("ZoomInfo JWT obtained successfully.");

GetJSONString extrahiert einen Feldwert über einen JSON-Pfad. TrimChars entfernt die anführungszeichen, die GetJSONString bei Stringwerten einfügt.

Schritt 3: Die Authentifizierungsoperation am Anfang jedes Workflows aufrufen

Rufen Sie in einem beliebigen Workflow, der ZoomInfo verwendet, die Authentifizierungsoperation als ersten Schritt auf:

$core.zoom.resource = "authenticate";
RunOperation("<TAG>operation:core.ZoomInfo - Get Auth Token</TAG>");

Führt derselbe Workflow mehrere ZoomInfo-Aufrufe durch, authentifizieren Sie sich einmal am Anfang, anstatt vor jedem einzelnen Aufruf.

Teil 3: Den Resource Router erstellen

Der Resource Router ordnet einen benannten Ressourcentyp dem entsprechenden ZoomInfo API-Pfad zu. Eine zentrale POST-Operation verwendet diesen Pfad für jeden Endpunkt erneut.

Schritt 1: Das Router-Skript erstellen

Erstellen Sie eine Script-Komponente mit dem Namen core. Load Zoom API Resource. Dieses Skript liest core.zoom.resource, das vom Aufrufer festgelegt wird, und schreibt den API-Pfad in core.zoom.object:

$core.zoom.resource = ToLower($core.zoom.resource);
If(length($core.zoom.resource) == 0,
    RaiseError("$core.zoom.resource is empty. Set a resource type before running this script.")
);

Case(
    $core.zoom.resource == "contact",
        $core.zoom.object = "/search/contact";
    ,
    $core.zoom.resource == "enrich_contact",
        $core.zoom.object = "/enrich/contact";
    ,
    $core.zoom.resource == "company",
        $core.zoom.object = "/search/company";
    ,
    $core.zoom.resource == "scoop",
        $core.zoom.object = "/search/scoop";
    ,
    true,
        RaiseError("Unknown ZoomInfo resource: [" + $core.zoom.resource + "]")
);

WriteToOperationLog("ZoomInfo resource: " + $core.zoom.resource
    + " → path: " + $core.zoom.object);

Die Case-Anweisung leitet die vier unterstützten Ressourcentypen weiter. Fügen Sie einen neuen Zweig für einen zusätzlichen ZoomInfo-Endpunkt hinzu, ohne die POST-Operation oder Verbindung zu ändern.

Schritt 2: Die zentrale POST-Operation erstellen

1. Erstellen Sie eine neue Operation und nennen Sie sie core. ZoomInfo POST API CALL.

2. Fügen Sie das Skript core. Load Zoom API Resource als ersten Schritt hinzu, damit core.zoom.object vor der Ausführung der Aktivität festgelegt wird.

3. Ziehen Sie eine POST-Aktivität aus der ZoomInfo API-Verbindung nach dem Skript.

4. Name: Geben Sie ZoomInfo - POST ein.

5. Path: Geben Sie [$core.zoom.object] ein. Studio löst die Variable zur Laufzeit mit dem vom Router-Skript festgelegten Wert auf.

6. Fügen Sie auf der Registerkarte Request einen Content-Type-Header mit dem Wert application/json hinzu.

7. Klicken Sie auf Finished.

Die unterstützten Ressourcentypen und ihre entsprechenden Pfade sind:

Teil 4: Nach Kontakten suchen

Mit Authentifizierung und Router an Ort und Stelle folgt jeder ZoomInfo-Aufruf derselben Abfolge: core.zoom.resource festlegen, den Request-Body in einer Transformation erstellen und die zentrale POST-Operation ausführen.

Build-Request- und Process-Response-Operationen erstellen

Die Build-Request- und Process-Response-Operationen, auf die in den folgenden Schritten verwiesen wird, sind nicht die zentrale POST-Operation: Man erstellt ein Paar für jeden Ressourcentyp (contact, enrich_contact, company, scoop). Jedes ist eine kleine, spezialisierte Operation, die um eine Transformation herum aufgebaut ist:

• Build-Request-Operation: Enthält eine Transformation, die die Eingabevariablen (z. B. zoom.companyName oder zoom.query_jobTitle) dem JSON-Request-Body zuordnet, den der ZoomInfo-Zielendpoint erwartet. Man führt sie vor der zentralen POST-Operation aus, damit der Request-Body vorbereitet ist, bevor die POST-Aktivität ihn sendet.
• Process-Response-Operation: Liest die ZoomInfo-Antwort und extrahiert die zurückgegebenen Felder in Variablen oder Datensätze für die Verwendung in nachgelagerten Schritten. Die Antwort wird entweder mit einer Transformation analysiert, die das Antwortschema einem Ziel zuordnet, oder mit einem Scriptschritt, der GetJSONString auf $jitterbit.response aufruft (der gleiche Ansatz, der zum Extrahieren des JWT in Teil 2 verwendet wird).

Die drei Operationen laufen in Reihenfolge ab: Build-Request, dann die zentrale POST-Operation, dann Process-Response. Das Anfrage- und Antwortschema für jeden Endpunkt finden Sie in der ZoomInfo-API-Dokumentation.

Kontaktsuche nach Unternehmensname

Um Kontakte zu finden, die einem Unternehmen zugeordnet sind, wird der Ressourcentyp und der Unternehmensname festgelegt, der Request-Body erstellt und die POST-Operation ausgeführt:

// Authenticate (skip if already done earlier in the workflow)
RunOperation("<TAG>operation:core.ZoomInfo - Get Auth Token</TAG>");

// Set the resource type and search parameters
$core.zoom.resource = "contact";
$zoom.companyName = $salesforce.accountName;

// Build and submit the search
RunOperation("<TAG>operation:Zoominfo - Build Request - Contact Info</TAG>");
RunOperation("<TAG>operation:core. ZoomInfo POST API CALL</TAG>");
RunOperation("<TAG>operation:Zoominfo - Process Request - Contact Info</TAG>");

Die Build-Request-Operation (Zoominfo - Build Request - Contact Info) ordnet zoom.companyName und alle optionalen Jobbezeichnungsfilter dem ZoomInfo-Search-API-Request-Format zu. Die Process-Response-Operation extrahiert die zurückgegebenen Kontaktdatensätze in Variablen für die Verwendung in nachgelagerten Schritten.

Das Anfrage- und Antwortschema für die ZoomInfo Search API finden Sie in der ZoomInfo-API-Dokumentation.

Kontakte nach Jobbezeichnung filtern

Um die Ergebnisse auf bestimmte Rollen einzugrenzen, wird zoom.query_jobTitle vor dem Build-Request-Schritt festgelegt:

$zoom.query_jobTitle = "Chief Executive Officer";
$core.zoom.resource = "contact";
RunOperation("<TAG>operation:Zoominfo - Build Request - Contact Info</TAG>");
RunOperation("<TAG>operation:core. ZoomInfo POST API CALL</TAG>");
RunOperation("<TAG>operation:Zoominfo - Process Request - Contact Info</TAG>");

Um über mehrere Jobbezeichnungen hinweg zu suchen, wird eine kommagetrennte Liste in zoom.query_jobTitle übergeben und die Werte in der Build-Request-Operation durchlaufen, wodurch ein Search-Aufruf pro Bezeichnung ausgeführt und die Ergebnisse akkumuliert werden.

Teil 5: Kontaktdaten anreichern

Die Kontaktanreicherung ruft detaillierte Daten ab (direkte E-Mail-Adressen, Telefonnummern und aktuelle Jobbezeichnungen) für Kontakte, die bereits durch eine Suche identifiziert oder aus einem vorhandenen Salesforce-Datensatz stammen. Man nutzt die Anreicherung, wenn eine grundlegende Kontaktsuche begrenzte Kontaktinformationen zurückgibt.

core.zoom.resource wird auf enrich_contact festgelegt und die zentrale POST-Operation wird ausgeführt:

$core.zoom.resource = "enrich_contact";
RunOperation("<TAG>operation:Zoominfo - Build Enrich Request</TAG>");
RunOperation("<TAG>operation:core. ZoomInfo POST API CALL</TAG>");
RunOperation("<TAG>operation:Zoominfo - Process Enrich Response</TAG>");

Der Anfragebody für die Anreicherung identifiziert den Kontakt normalerweise nach Name und Unternehmen oder nach einer ZoomInfo-Kontakt-ID, die aus einer vorherigen Suche zurückgegeben wurde. Nach der Anreicherung werden die zurückgegebenen Daten zum Aktualisieren des entsprechenden Salesforce-Kontaktdatensatzes verwendet. Zum Zusammenführen angereicherte Felder in Salesforce finden Sie unter Salesforce-Datensätze mit SOQL abfragen.

Teil 6: Unternehmens- und Scoop-Daten abrufen

Der gleiche Router verarbeitet Suchvorgänge auf Unternehmensebene. Die Unternehmenssuche gibt eine ZoomInfo-Unternehmens-ID zurück, die in nachfolgenden /search/scoop-Aufrufen verwendet werden kann, um aktuelle Nachrichten und Führungswechseldaten abzurufen.

// Search for the company record
$zoom.companyName = $salesforce.accountName;
RunOperation("<TAG>operation:core.ZoomInfo Build Request - Get Company</TAG>");
$core.zoom.resource = "company";
RunOperation("<TAG>operation:core. ZoomInfo POST API CALL</TAG>");
RunOperation("<TAG>operation:core.ZoomInfo - Read Response - Get Company Id</TAG>");

// Retrieve scoop data using the company ID from the previous step
RunOperation("<TAG>operation:Build Request - Get Scoop for a Company</TAG>");
$core.zoom.resource = "scoop";
RunOperation("<TAG>operation:core. ZoomInfo POST API CALL</TAG>");
RunOperation("<TAG>operation:Read Response - Scoop for a Company</TAG>");

Scoop-Daten enthalten Ankündigungen von Führungswechseln wie neue Einstellungen von Führungskräften oder Rollenänderungen. Dies ist nützlich für Account-Intelligence-Workflows, die Sales- oder Account-Teams benachrichtigen, wenn sich Schlüsselkontakte bei einem Unternehmen ändern.

Integration überprüfen

1. Führen Sie core.ZoomInfo - Get Auth Token isoliert aus. Fügen Sie einen WriteToOperationLog-Aufruf nach dem JWT-Extraktionsskript hinzu, um zu bestätigen, dass zoom.jwt nicht leer ist. Überprüfen Sie die Operationsprotokolle auf den Protokolleintrag.

2. Führen Sie eine Kontaktsuche nach einem Unternehmensnamen durch, von dem Sie wissen, dass es in ZoomInfo vorhanden ist. Bestätigen Sie in den Protokollen, dass:

   • core.zoom.object vom Router-Skript auf /search/contact gesetzt ist.
   • Die POST-Aktivität den Status 200 zurückgibt.
   • Die Prozessantwort-Operation Kontaktdatensätze erzeugt.

3. Wenn der /authenticate-Aufruf einen Status ungleich 200 zurückgibt, bestätigen Sie, dass die Projektenvariablen zoom.username und zoom.password korrekt gesetzt sind. ZoomInfo-Anmeldedaten unterscheiden zwischen Groß- und Kleinschreibung.

4. Wenn nachfolgende API-Aufrufe 401 Unauthorized zurückgeben, ist die JWT-Extraktion möglicherweise stillschweigend fehlgeschlagen. Bestätigen Sie, dass die RaiseError-Schutzvorrichtung im Authentifizierungsskript aktiv ist und dass zoom.jwt nicht leer ist, bevor die nächste Operationskette ausgeführt wird.

5. Wenn der Router einen Fehler „Unknown ZoomInfo resource" (Unbekannte ZoomInfo-Ressource) verursacht, überprüfen Sie, dass core.zoom.resource auf einen der unterstützten Werte (contact, enrich_contact, company, scoop) gesetzt ist und dass der Wert kein führendes oder nachfolgendes Leerzeichen enthält.