Kontaktinformationen mit ZoomInfo im Jitterbit Studio anreichern

Einführung

ZoomInfo bietet B2B-Kontakt- und Unternehmensdaten über eine REST-API an. Dieser Leitfaden zeigt, wie man den HTTP v2-Connector verwendet, um sich bei ZoomInfo zu authentifizieren, einen wiederverwendbaren Ressourcenrouter zu erstellen, der benannte Endpunkttypen den API-Pfaden zuordnet, und diesen Router verwendet, um nach Kontakten zu suchen, bestehende Kontaktaufzeichnungen anzureichern und Unternehmensdaten abzurufen.

Das zentrale Muster in diesem Leitfaden ist ein Case-basierter Ressourcenrouter: Ein einzelnes Skript ordnet einen Ressourcennamen wie contact oder company dem entsprechenden ZoomInfo-API-Pfad zu, 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 zum Router-Skript, ohne zusätzliche Verbindungs- oder Aktivitätseinrichtungen.

Dieser Leitfaden setzt ein ZoomInfo-Konto mit API-Zugangsdaten (Benutzername und Passwort) voraus.

Entwurfsmuster

Die Authentifizierung erfolgt einmal zu Beginn des Workflows, um ein JWT zu erhalten. Alle nachfolgenden ZoomInfo-Aufrufe folgen derselben Reihenfolge:

Der Router und die POST-Aktivität werden über alle ZoomInfo-API-Aufrufe hinweg geteilt.

Die Tabelle zeigt den konzeptionellen Ablauf. In der Implementierung sind der Ressourcenrouter und die POST-Aktivität Schritte innerhalb einer gemeinsamen Operation (der zentralen POST-Operation in Teil 3), während die Anforderungsbildung und die Prozessantwort separate, wiederverwendbare Operationen sind, die Sie pro Ressourcentyp erstellen und mit RunOperation aufrufen (siehe Teil 4).

Teil 1: Projektvariablen und die HTTP v2-Verbindung konfigurieren

Schritt 1: Projektvariablen erstellen

Speichern Sie Anmeldeinformationen und das Laufzeit-JWT in Projektvariablen, damit sensible Werte nicht in Skripten oder Aktivitätskonfigurationen fest codiert sind.

Öffnen Sie das Aktionsmenü des Projekts und wählen Sie Projektvariablen. Fügen Sie dann hinzu:

Markieren Sie zoom.password und zoom.jwt als verborgen. Für Hinweise zur sicheren Speicherung von Anmeldeinformationen siehe Verwalten von Endpunktanmeldeinformationen.

Schritt 2: Die HTTP v2-Verbindung konfigurieren

1. Öffnen Sie im Studio Ihr Projekt und klicken Sie auf die Registerkarte Projektendpunkte und -verbinder im Design-Komponentenpalette.

2. Klicken Sie auf den HTTP v2-Connector, um den Bildschirm zur Konfiguration der Verbindung zu öffnen.

3. Verbindungsname: Geben Sie ZoomInfo API ein.

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

5. Autorisierung: Wählen Sie Bearer-Token und geben Sie [$zoom.jwt] als Tokenwert ein. Die Projektvariable zoom.jwt ist leer, wenn das Projekt zum ersten Mal ausgeführt wird. Die Authentifizierungsoperation in Teil 2 füllt sie aus, bevor ein anderer ZoomInfo-Aufruf gemacht wird. Der Endpunkt /authenticate selbst validiert den Authorization-Header nicht, sodass ein leeres Token beim ersten Aufruf keinen Fehler verursacht.

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

Teil 2: Authentifizieren und JWT speichern

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

Schritt 1: Erstellen Sie die Authentifizierungsoperation

1. Erstellen Sie eine neue Operation und benennen Sie sie core.ZoomInfo - Authentifizierungstoken abrufen.

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

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

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

5. Name: Geben Sie ZoomInfo - Authentifizieren ein.

6. Pfad: Geben Sie /authenticate ein.

7. Fügen Sie im Tab Anfrage einen Content-Type-Header mit dem Wert application/json hinzu.

8. Klicken Sie auf Fertig.

Schritt 2: JWT extrahieren und speichern

Fügen Sie nach der POST-Aktivität einen Skript-Schritt hinzu. Das Skript liest das JWT aus $jitterbit.response, das den Rohantwortkörper der vorhergehenden 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 anhand des JSON-Pfads. TrimChars entfernt die umgebenden Anführungszeichen, die GetJSONString in Stringwerten enthält.

Schritt 3: Rufen Sie die Authentifizierungsoperation zu Beginn jedes Workflows auf

In jedem Workflow, der ZoomInfo verwendet, rufen Sie die Authentifizierungsoperation als ersten Schritt auf:

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

Wenn derselbe Workflow mehrere ZoomInfo-Aufrufe ausführt, authentifizieren Sie sich einmal zu Beginn, anstatt vor jedem einzelnen Aufruf.

Teil 3: Erstellen des Ressourcen-Routers

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

Schritt 1: Erstellen des Router-Skripts

Erstellen Sie eine Skriptkomponente 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 jeden zusätzlichen ZoomInfo-Endpunkt hinzu, ohne die POST-Operation oder die Verbindung zu ändern.

Schritt 2: Erstellen der zentralen POST-Operation

1. Erstellen Sie eine neue Operation und benennen 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 aus der ZoomInfo API-Verbindung eine POST-Aktivität nach dem Skript.

4. Name: Geben Sie ZoomInfo - POST ein.

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

6. Fügen Sie im Tab Anfrage einen Content-Type-Header mit dem Wert application/json hinzu.

7. Klicken Sie auf Fertig.

Die unterstützten Ressourcentypen und ihre entsprechenden Pfade sind:

Teil 4: Suchen nach Kontakten

Mit der Authentifizierung und dem Router an Ort und Stelle folgt jeder ZoomInfo-Aufruf derselben Abfolge: Setzen von core.zoom.resource, Erstellen des Anforderungskörpers in einer Transformation und Ausführen der zentralen POST-Operation.

Erstellen der Anforderung und Verarbeiten der Antwortoperationen

Die im Folgenden genannten Anforderungs- und Antwortverarbeitungsoperationen sind nicht die zentrale POST-Operation: Sie erstellen ein Paar für jeden Ressourcentyp (contact, enrich_contact, company, scoop). Jede ist eine kleine, zielgerichtete Operation, die sich um eine Transformation dreht:

• Anforderungsoperation erstellen: Enthält eine Transformation, die die Eingangsvariablen (zum Beispiel zoom.companyName oder zoom.query_jobTitle) dem JSON-Anforderungskörper zuordnet, den der Ziel-ZoomInfo-Endpunkt erwartet. Führen Sie sie vor der zentralen POST-Operation aus, damit der Anforderungskörper vorbereitet ist, bevor die POST-Aktivität ihn sendet.
• Antwortverarbeitungsoperation: Liest die ZoomInfo-Antwort und extrahiert die zurückgegebenen Felder in Variablen oder Datensätze für die nachgelagerte Verwendung. Analysieren Sie die Antwort entweder mit einer Transformation, die das Antwortschema einem Ziel zuordnet, oder mit einem Skript-Schritt, der GetJSONString auf $jitterbit.response aufruft (derselbe Ansatz, der verwendet wird, um das JWT in Teil 2 zu extrahieren).

Die drei Operationen werden in folgender Reihenfolge ausgeführt: Anforderung erstellen, dann die zentrale POST-Operation, dann Antwort verarbeiten. Für das Anforderungs- und Antwortschema jedes Endpunkts siehe die ZoomInfo API-Dokumentation.

Kontaktsuche nach Unternehmensnamen

Um Kontakte zu erhalten, die mit einem Unternehmen verbunden sind, setzen Sie den Ressourcentyp und den Unternehmensnamen, erstellen den Anforderungskörper und führen die POST-Operation aus:

// 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 Anforderungsoperation erstellen (Zoominfo - Build Request - Contact Info) ordnet zoom.companyName und jeden optionalen Jobtitel-Filter dem ZoomInfo Search API-Anforderungsformat zu. Die Antwortverarbeitungsoperation extrahiert die zurückgegebenen Kontaktaufzeichnungen in Variablen für die nachgelagerte Verwendung.

Für das Schema der Anforderung und Antwort der ZoomInfo-Such-API siehe die ZoomInfo API-Dokumentation.

Kontakte nach Berufsbezeichnung filtern

Um die Ergebnisse auf bestimmte Rollen einzugrenzen, setze zoom.query_jobTitle vor dem Schritt zur Anforderungsbildung:

$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 Berufsbezeichnungen zu suchen, übergebe eine durch Kommas getrennte Liste in zoom.query_jobTitle und iteriere über die Werte in der Anforderungsbildungsoperation, indem du für jede Bezeichnung einen Suchaufruf machst und die Ergebnisse sammelst.

Teil 5: Kontaktdaten anreichern

Die Anreicherung von Kontakten ruft detaillierte Daten (direkte E-Mail-Adressen, Telefonnummern und aktuelle Berufsbezeichnungen) für bereits identifizierte Kontakte ab, die durch eine Suche oder aus einem bestehenden Salesforce-Datensatz stammen. Verwende die Anreicherung, wenn eine grundlegende Kontaktsuche nur begrenzte Kontaktinformationen zurückgibt.

Setze core.zoom.resource auf enrich_contact und führe die zentrale POST-Operation aus:

$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 Anreicherungsanfragekörper identifiziert typischerweise den Kontakt nach Name und Unternehmen oder durch eine ZoomInfo-Kontakt-ID, die aus einer vorherigen Suche zurückgegeben wurde. Nach der Anreicherung verwende die zurückgegebenen Daten, um den entsprechenden Salesforce-Kontaktdatensatz zu aktualisieren. Für das Zusammenführen angereicherter Felder in Salesforce siehe Salesforce-Datensätze mit SOQL abfragen.

Teil 6: Unternehmens- und Scoop-Daten abrufen

Der gleiche Router verarbeitet Unternehmensabfragen. Die Unternehmenssuche gibt eine ZoomInfo-Unternehmens-ID zurück, die in nachfolgenden /search/scoop-Aufrufen verwendet werden kann, um aktuelle Nachrichten und Daten zu Führungswechseln 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 umfassen Ankündigungen von Führungswechseln wie neue Führungskräfteinstellungen oder Rollenwechsel. Dies ist nützlich für Account-Intelligence-Workflows, die Vertriebs- oder Account-Teams benachrichtigen, wenn sich wichtige Kontakte in einem Unternehmen ändern.

Die Integration überprüfen

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

2. Führen Sie eine Kontaktsuche nach einem Firmennamen durch, von dem Sie wissen, dass er in ZoomInfo existiert. Bestätigen Sie in den Protokollen, dass:

   • core.zoom.object durch das Router-Skript auf /search/contact gesetzt ist.
   • Die POST-Aktivität einen Status von 200 zurückgibt.
   • Die Prozessantwortoperation Kontaktdatensätze produziert.

3. Wenn der Aufruf /authenticate einen Status ungleich 200 zurückgibt, bestätigen Sie, dass die Projektvariablen zoom.username und zoom.password korrekt gesetzt sind. Die ZoomInfo-Anmeldeinformationen sind groß- und kleinschreibungsempfindlich.

4. Wenn nachfolgende API-Aufrufe 401 Unauthorized zurückgeben, könnte die JWT-Extraktion stillschweigend fehlgeschlagen sein. Bestätigen Sie, dass die RaiseError-Schutzvorrichtung im Authentifizierungsskript aktiv ist und dass zoom.jwt vor der Ausführung der nächsten Operation nicht leer ist.

5. Wenn der Router einen Fehler "Unbekannte ZoomInfo-Ressource" ausgibt, überprüfen Sie, ob core.zoom.resource auf einen der unterstützten Werte (contact, enrich_contact, company, scoop) gesetzt ist und dass keine führenden oder nachfolgenden Leerzeichen im Wert vorhanden sind.