Enriquecer dados de contato usando ZoomInfo no Jitterbit Studio

Introdução

ZoomInfo fornece dados de contatos e empresas B2B através de uma API REST. Este guia mostra como usar o conector HTTP v2 para autenticar com ZoomInfo, criar um roteador de recursos reutilizável que mapeia tipos de endpoint nomeados para caminhos de API e usar esse roteador para pesquisar contatos, enriquecer registros de contato existentes e recuperar dados de empresas.

O padrão-chave neste guia é um roteador de recursos baseado em Case: um único script mapeia um nome de recurso como contact ou company para o caminho correspondente da API ZoomInfo, e uma operação HTTP v2 POST central trata todas as chamadas de API. Isso torna a integração reutilizável: adicionar um novo endpoint ZoomInfo requer apenas uma adição de uma linha ao script do roteador, sem configuração adicional de conexão ou atividade.

Este guia pressupõe uma conta ZoomInfo com credenciais de acesso à API (nome de usuário e senha).

Padrão de design

A autenticação é executada uma vez no início do fluxo de trabalho para obter um JWT. Todas as chamadas ZoomInfo subsequentes seguem a mesma sequência:

O roteador e a atividade POST são compartilhados em todas as chamadas da API ZoomInfo.

A tabela mostra o fluxo conceitual. Na implementação, o roteador de recursos e a atividade POST são etapas dentro de uma operação compartilhada (a operação POST central na Parte 3), enquanto a construção da solicitação e o processamento da resposta são operações separadas e reutilizáveis que você cria por tipo de recurso e invoca com RunOperation (ver Parte 4).

Parte 1: Configurar variáveis de projeto e a conexão HTTP v2

Etapa 1: Criar variáveis de projeto

Armazene credenciais e o JWT de runtime em variáveis de projeto para que valores sensíveis não sejam codificados em scripts ou configuração de atividade.

Abra o menu de ações do projeto e selecione Variáveis de Projeto. Em seguida, adicione:

Marque zoom.password e zoom.jwt como ocultos. Para orientação sobre armazenar credenciais com segurança, consulte Gerenciar credenciais de endpoint.

Etapa 2: Configurar a conexão HTTP v2

1. No Studio, abra seu projeto e clique na guia Project endpoints and connectors (Endpoints e conectores do projeto) na paleta de componentes de design.

2. Clique no conector HTTP v2 para abrir a tela de configuração de conexão.

3. Connection Name (Nome da conexão): Digite ZoomInfo API.

4. Base URL: Digite https://api.zoominfo.com.

5. Authorization (Autorização): Selecione Bearer Token e digite [$zoom.jwt] como o valor do token. A variável de projeto zoom.jwt fica vazia quando o projeto é executado pela primeira vez. A operação de autenticação na Parte 2 a popula antes de qualquer outra chamada ZoomInfo ser feita. O próprio endpoint /authenticate não valida o cabeçalho Authorization, portanto um token vazio na chamada inicial não causa erro.

6. Clique em Test para verificar a conexão e depois clique em Save Changes.

Parte 2: Autenticar e armazenar o JWT

O ZoomInfo usa um modelo de autenticação baseado em JWT. Antes de qualquer chamada de API, uma operação envia credenciais para o endpoint /authenticate e armazena o JWT retornado em zoom.jwt.

Etapa 1: Criar a operação de autenticação

1. Crie uma nova operação e nomeie-a core.ZoomInfo - Get Auth Token.

2. Adicione uma etapa de Transformation. Na transformação, defina um esquema de destino JSON com dois campos: username e password. Mapeie [$zoom.username] e [$zoom.password] para os respectivos campos.

3. Na conexão ZoomInfo API, arraste uma atividade POST após a transformação como o destino.

4. Clique duas vezes na atividade POST para abrir sua configuração.

5. Name: Digite ZoomInfo - Authenticate.

6. Path: Digite /authenticate.

7. Na aba Request, adicione um header Content-Type com o valor application/json.

8. Clique em Finished.

Etapa 2: Extrair e armazenar o JWT

Adicione uma etapa de Script após a atividade POST. O script lê o JWT de $jitterbit.response, que contém o corpo de resposta bruto da atividade HTTP anterior, e armazena-o na variável de projeto:

$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 extrai um valor de campo por caminho JSON. TrimChars remove as aspas ao redor que GetJSONString inclui em valores de string.

Etapa 3: Chamar a operação de autenticação no início de cada fluxo de trabalho

Em qualquer fluxo de trabalho que use ZoomInfo, chame a operação de autenticação como primeira etapa:

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

Se o mesmo fluxo de trabalho executar múltiplas chamadas ZoomInfo, autentique uma vez no início em vez de antes de cada chamada individual.

Parte 3: Criar o roteador de recursos

O roteador de recursos mapeia um tipo de recurso nomeado para o caminho correspondente da API ZoomInfo. Uma operação POST central reutiliza este caminho para cada endpoint.

Etapa 1: Criar o script do roteador

Crie um componente Script nomeado core. Load Zoom API Resource. Este script lê core.zoom.resource, definido pelo chamador, e escreve o caminho da API em 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);

A instrução Case roteia os quatro tipos de recursos suportados. Adicione uma nova ramificação para qualquer endpoint ZoomInfo adicional sem alterar a operação POST ou a conexão.

Etapa 2: Criar a operação POST central

1. Crie uma nova operação e nomeie-a core. ZoomInfo POST API CALL.

2. Adicione o script core. Load Zoom API Resource como primeira etapa para que core.zoom.object seja definido antes da atividade ser executada.

3. Na conexão ZoomInfo API, arraste uma atividade POST após o script.

4. Name: Digite ZoomInfo - POST.

5. Path: Digite [$core.zoom.object]. O Studio resolve a variável em tempo de execução usando o valor definido pelo script do roteador.

6. Na aba Request, adicione um header Content-Type com o valor application/json.

7. Clique em Finished.

Os tipos de recursos suportados e seus caminhos correspondentes são:

Parte 4: Procurar por contatos

Com autenticação e o roteador em funcionamento, cada chamada para o ZoomInfo segue a mesma sequência: defina core.zoom.resource, construa o corpo da solicitação em uma transformação e execute a operação POST central.

Criar as operações de construção de solicitação e processamento de resposta

As operações de construção de solicitação e processamento de resposta mencionadas nas etapas abaixo não são a operação POST central: você cria um par para cada tipo de recurso (contact, enrich_contact, company, scoop). Cada uma é uma operação pequena e com propósito único, construída em torno de uma transformação:

• Operação de construção de solicitação: Contém uma transformação que mapeia as variáveis de entrada (por exemplo, zoom.companyName ou zoom.query_jobTitle) para o corpo da solicitação JSON que o endpoint do ZoomInfo de destino espera. Execute-a antes da operação POST central para que o corpo da solicitação esteja preparado antes da atividade POST enviá-lo.
• Operação de processamento de resposta: Lê a resposta do ZoomInfo e extrai os campos retornados em variáveis ou registros para uso downstream. Analise a resposta com uma transformação que mapeia o schema de resposta para um destino ou com uma etapa de script que chama GetJSONString em $jitterbit.response (a mesma abordagem usada para extrair o JWT na Parte 2).

As três operações são executadas em sequência: construção de solicitação, depois a operação POST central, depois processamento de resposta. Para cada schema de solicitação e resposta do endpoint, consulte a documentação da API do ZoomInfo.

Pesquisa de contatos por nome da empresa

Para recuperar contatos associados a uma empresa, defina o tipo de recurso e o nome da empresa, construa o corpo da solicitação e execute a operação POST:

// 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>");

A operação de construção de solicitação (Zoominfo - Build Request - Contact Info) mapeia zoom.companyName e qualquer filtro de título de trabalho opcional para o formato de solicitação da API de Pesquisa do ZoomInfo. A operação de processamento de resposta extrai os registros de contato retornados em variáveis para uso downstream.

Para o schema de solicitação e resposta da API de Pesquisa do ZoomInfo, consulte a documentação da API do ZoomInfo.

Filtrar contatos por título de trabalho

Para estreitar os resultados para funções específicas, defina zoom.query_jobTitle antes da etapa de construção de solicitação:

$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>");

Para pesquisar em vários títulos de trabalho, passe uma lista separada por vírgulas em zoom.query_jobTitle e itere sobre os valores na operação de construção de solicitação, fazendo uma chamada de pesquisa por título e acumulando resultados.

Parte 5: Enriquecer dados de contato

O enriquecimento de contatos recupera dados detalhados (endereços de email diretos, números de telefone e títulos de trabalho atuais) para contatos já identificados por meio de uma pesquisa ou originários de um registro do Salesforce existente. Use o enriquecimento quando uma pesquisa básica de contatos retorna informações limitadas de contato.

Defina core.zoom.resource como enrich_contact e execute a operação POST central:

$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>");

O corpo da solicitação de enriquecimento geralmente identifica o contato pelo nome e empresa ou por uma ID de contato do ZoomInfo retornada de uma pesquisa anterior. Após o enriquecimento, use os dados retornados para atualizar o registro de contato correspondente do Salesforce. Para mesclar campos enriquecidos no Salesforce, consulte Consultar registros do Salesforce usando SOQL.

Parte 6: Recuperar dados de empresa e scoop

O mesmo roteador processa pesquisas no nível da empresa. A pesquisa de empresas retorna uma ID de empresa do ZoomInfo que pode ser usada em chamadas subsequentes de /search/scoop para recuperar dados recentes de notícias e mudanças de liderança.

// 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>");

Os dados de scoop incluem anúncios de mudanças de liderança, como contratações de novos executivos ou mudanças de funções. Isso é útil para fluxos de trabalho de inteligência de contas que alertam times de vendas ou de contas quando contatos-chave em uma empresa mudam.

Verificar a integração

1. Execute core.ZoomInfo - Get Auth Token isoladamente. Adicione uma chamada WriteToOperationLog após o script de extração de JWT para confirmar que zoom.jwt não está vazio. Verifique os logs de operação pela entrada de log.

2. Execute uma pesquisa de contato por um nome de empresa que você sabe que existe no ZoomInfo. Confirme nos logs que:

   • core.zoom.object está definido como /search/contact pelo script do roteador.
   • A atividade POST retorna um status 200.
   • A operação de resposta do processo produz registros de contato.

3. Se a chamada /authenticate retornar um status diferente de 200, confirme que as variáveis de projeto zoom.username e zoom.password estão definidas corretamente. As credenciais do ZoomInfo diferenciam maiúsculas de minúsculas.

4. Se as chamadas de API subsequentes retornarem 401 Unauthorized, a extração de JWT pode ter falhado silenciosamente. Confirme que o guard RaiseError no script de autenticação está ativo e que zoom.jwt não está vazio antes da próxima cadeia de operações ser executada.

5. Se o roteador gerar um erro "Unknown ZoomInfo resource", verifique se core.zoom.resource está definido como um dos valores suportados (contact, enrich_contact, company, scoop) e que não há espaços em branco à esquerda ou à direita no valor.