Enriquecer dados de contato usando ZoomInfo no Jitterbit Studio

Introdução

O ZoomInfo fornece dados de contato e empresa B2B por meio de uma API REST. Este guia mostra como usar o conector HTTP v2 para autenticar com o ZoomInfo, construir um roteador de recursos reutilizável que mapeia tipos de endpoint nomeados para caminhos da API e usar esse roteador para buscar 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 do ZoomInfo, e uma operação central HTTP v2 POST lida com todas as chamadas da API. Isso torna a integração reutilizável: adicionar um novo endpoint do ZoomInfo requer apenas uma adição de uma linha ao script do roteador, sem necessidade de configuração adicional de conexão ou atividade.

Este guia assume uma conta do 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 subsequentes do ZoomInfo seguem a mesma sequência:

O roteador e a atividade POST são compartilhados entre todas as chamadas da API do 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 em 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 (veja Parte 4).

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

Etapa 1: Criar variáveis do projeto

Armazene credenciais e o JWT de tempo de execução em variáveis do projeto para que valores sensíveis não sejam codificados diretamente em scripts ou na configuração da atividade.

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

Marque zoom.password e zoom.jwt como ocultos. Para orientações sobre como armazenar credenciais de forma segura, veja Gerenciar credenciais de endpoint.

Etapa 2: Configurar a conexão HTTP v2

1. No Studio, abra seu projeto e clique na aba Endpoints e conectores do projeto no painel de componentes de design.

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

3. Nome da Conexão: Insira ZoomInfo API.

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

5. Autorização: Selecione Bearer Token e insira [$zoom.jwt] como o valor do token. A variável do projeto zoom.jwt está vazia quando o projeto é executado pela primeira vez. A operação de autenticação em Parte 2 a preenche antes que qualquer outra chamada ao ZoomInfo seja feita. O endpoint /authenticate em si não valida o cabeçalho Authorization, portanto, um token vazio na chamada inicial não causa um erro.

6. Clique em Testar para verificar a conexão, em seguida clique em Salvar Alterações.

Parte 2: Autenticar e armazenar o JWT

O ZoomInfo utiliza 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.

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

1. Crie uma nova operação e nomeie-a como core.ZoomInfo - Obter Token de Autenticação.

2. Adicione um passo de Transformação. 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. A partir da conexão ZoomInfo API, arraste uma atividade POST após a transformação como destino.

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

5. Nome: Insira ZoomInfo - Autenticar.

6. Caminho: Insira /authenticate.

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

8. Clique em Concluído.

Passo 2: Extrair e armazenar o JWT

Adicione um passo de Script após a atividade POST. O script lê o JWT de $jitterbit.response, que contém o corpo da resposta bruta da atividade HTTP anterior, e o armazena na variável do 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 pelo caminho JSON. TrimChars remove as aspas ao redor que GetJSONString inclui em valores de string.

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

Em qualquer fluxo de trabalho que utilize o ZoomInfo, chame a operação de autenticação como o primeiro passo:

$core.zoom.resource = "authenticate";
RunOperation("<TAG>operation:core.ZoomInfo - Obter Token de Autenticação</TAG>");

Se o mesmo fluxo de trabalho executar várias chamadas do 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 do ZoomInfo. Uma operação POST central reutiliza esse caminho para cada endpoint.

Etapa 1: Criar o script do roteador

Crie um componente de Script chamado core. Load Zoom API Resource. Este script lê core.zoom.resource, definido pelo chamador, e grava 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 declaração Case direciona os quatro tipos de recursos suportados. Adicione um novo ramo para qualquer endpoint adicional do ZoomInfo 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 o primeiro passo para que core.zoom.object seja definido antes da execução da atividade.

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

4. Nome: Insira ZoomInfo - POST.

5. Caminho: Insira [$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 cabeçalho Content-Type com o valor application/json.

7. Clique em Finished.

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

Parte 4: Pesquisar contatos

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

Criar a operação de solicitação de construção e processar a resposta

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

• Operação de solicitação de construçã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 espera. Execute-a antes da operação central POST para que o corpo da solicitação esteja preparado antes que a atividade POST o envie.
• Operação de processamento de resposta: Lê a resposta do ZoomInfo e extrai os campos retornados em variáveis ou registros para uso posterior. Analise a resposta, seja com uma transformação que mapeia o esquema de resposta para um alvo, ou com um passo 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: construir a solicitação, em seguida, a operação central POST, e depois processar a resposta. Para o esquema de solicitação e resposta de cada endpoint, consulte a documentação da API do ZoomInfo.

Pesquisa de contato pelo 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 solicitação de construçã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 posterior.

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

Filtrar contatos por cargo

Para restringir os resultados a funções específicas, defina zoom.query_jobTitle antes da etapa de construção da 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 cargos, passe uma lista separada por vírgulas em zoom.query_jobTitle e itere sobre os valores na operação de construção da 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 e-mail diretos, números de telefone e cargos atuais) para contatos já identificados por meio de uma pesquisa ou provenientes de um registro existente do Salesforce. Use o enriquecimento quando uma pesquisa básica de contato retornar informações limitadas.

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 pela empresa, ou por um ID de contato do ZoomInfo retornado de uma pesquisa anterior. Após o enriquecimento, use os dados retornados para atualizar o registro de contato correspondente no Salesforce. Para mesclar campos enriquecidos no Salesforce, consulte Consultar registros do Salesforce usando SOQL.

Parte 6: Recuperar dados da empresa e scoop

O mesmo roteador lida com consultas em nível de empresa. A pesquisa de empresa retorna um ID de empresa do ZoomInfo que pode ser usado em chamadas subsequentes de /search/scoop para recuperar notícias recentes e dados de mudanças na 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 na liderança, como novas contratações executivas ou mudanças de função. Isso é útil para fluxos de trabalho de inteligência de contas que alertam equipes 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 do JWT para confirmar que zoom.jwt não está vazio. Verifique os logs de operação para a entrada de log.

2. Execute uma busca de contato para 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 são sensíveis a maiúsculas e minúsculas.

4. Se chamadas subsequentes da API retornarem 401 Não Autorizado, a extração do 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 que a próxima cadeia de operações seja executada.

5. Se o roteador gerar um erro "Recurso ZoomInfo desconhecido", 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 no início ou no final do valor.