Pular para o conteúdo principal
POST
Pesquisa de pessoas
Cada ação retorna output normalizado. A saída nativa do Provedor não é repetida ali; ela permanece no Run e pode ser lida com Get Run. search retorna total_matches e output.items[], uma linha por pessoa. enrich e find_email retornam uma pessoa com os mesmos campos no nível superior. Um valor que o Provedor selecionado não informa é null; o Glasser não o preenche. Leia result_status separadamente de status: success, no_result, error ou pending. Uma resposta vazia, mas válida, é no_result e mantém o formato da ação: todos os campos são null, ou items é []. find_email sem um e-mail é no_result. charge_usd totaliza o runs desta resposta e permanece nulo até que todos os Runs sejam concluídos. Com provider: auto, o fallback pode criar vários Runs, cada um listado em runs[] com sua própria cobrança. Consulte Seleção de Provedor e cobranças.

​
Saída por ação

Todos os campos estão presentes em todas as linhas; um valor que o Provedor não informa é null. Os campos seguem as convenções de campos. Uma pessoa tem estes campos: name, first_name, last_name, job_title, seniority, department, headline, linkedin_url, city, region, country, country_code, email, email_status, email_catch_all, email_source, phone, company_name, company_domain, company_linkedin_url, apollo_match_confidence, pdl_likelihood, hunter_email_score, zoominfo_accuracy_score.
  • Nomes, cargos e rótulos são apresentados conforme o Provedor os informa. Os nomes do PDL são escritos em minúsculas. name é null quando o Provedor fornece apenas o nome e o sobrenome; o Glasser não os combina. A busca do Apollo oculta o sobrenome, portanto last_name é null.
  • seniority e department são rótulos do próprio vocabulário do Provedor que responde (por exemplo, Apollo founder, PDL cxo, LeadMagic C-Team). Eles não são valores de seniorities da solicitação e não são comparáveis entre Provedores.
  • email é o endereço que o Provedor fornece como e-mail profissional. O PDL o preenche apenas a partir de work_email; os outros endereços permanecem no Run. As linhas de busca do Apollo, ZoomInfo e LeadMagic não têm e-mail.
  • email_status é o próprio rótulo de verificação do Provedor (verified, VERIFIED, valid). Os Provedores verificam de maneiras diferentes, portanto não compare os rótulos. Leia-os junto com email_catch_all (o domínio aceita todos os endereços, portanto uma verificação da caixa de entrada não pode confirmar este) e email_source (Hunter: found na web ou generated a partir do padrão de endereços do domínio). O Hunter cobra por um endereço gerado.
  • total_matches contabiliza as correspondências em todo o conjunto de dados do Provedor, não apenas nesta página. Ele é null para o LeadMagic, que fornece apenas a contagem da página.
  • As pontuações do modelo próprio de um Provedor mantêm o nome dele e são null para os demais: apollo_match_confidence (alta, média, baixa, nenhuma), pdl_likelihood (1–10), hunter_email_score (0–100), zoominfo_accuracy_score (0–100).

​
Filtros

  • O PDL corresponde a job_titles exatamente como fornecido, portanto “CTO” não corresponde a “Co-founder & CTO”. Ele corresponde a locations como substring, portanto “london” também corresponde a “new london, connecticut”.
  • O ZoomInfo não tem nível founder, owner, partner, head, entry ou intern; portanto, com auto, essas solicitações ignoram o ZoomInfo. O senior do ZoomInfo é todo o nível “Non Manager”, que também inclui colaboradores individuais juniores.
  • A busca do Hunter lista apenas os endereços pessoais em company_domain, não caixas de e-mail de função, como info@. O enriquecimento do Prospeo retorna apenas pessoas para as quais mantém um e-mail profissional verificado. find_email via Apollo também aceita linkedin_url por conta própria; uma correspondência do Apollo sem um e-mail real é considerada uma falha e não é cobrada.

Cabeçalhos

​
idempotency-key
string
obrigatório

Gere um valor exclusivo para cada execução pretendida (recomenda-se um UUID). Tente novamente com a mesma chave e os mesmos parâmetros de execução para recuperar o Run original sem uma segunda cobrança. Alterar os parâmetros de execução com a mesma chave retorna 409; alterar task_id ou metadata não atualiza o Run original.

Minimum string length: 1

Corpo

application/json
​
action
enum<string> | null

Padrão: search.

  • search: forneça pelo menos um de job_titles, seniorities, locations, company_domain ou keywords. As linhas do Apollo e do ZoomInfo não contêm e-mail nem telefone; as linhas do PDL são registros completos; o Hunter lista os endereços pessoais em company_domain.
  • list_employees: forneça company_domain. Leia até 100 perfis de funcionários e seus cargos reais do LeadMagic; esta é uma amostra, não uma lista completa de funcionários da empresa. Não se aplicam filtros de cargo ou localização.
  • enrich: forneça linkedin_url, email ou full_name junto com company_domain. O Prospeo retorna apenas pessoas para as quais possui um e-mail corporativo verificado.
  • find_email: forneça full_name e company_domain. O Apollo também aceita apenas linkedin_url; uma correspondência do Apollo sem um e-mail real é considerada um caso sem resultado e não é cobrada.
  • verify_email: forneça email. Vereditos inválidos, catch-all, descartáveis e desconhecidos são respostas bem-sucedidas, não resultados ausentes. Use completed_at do Run final como horário da verificação.
  • find_phone: o LeadMagic exige linkedin_url; o Prospeo também aceita email ou full_name junto com company_domain. Encontra um número de celular; não envia mensagens nem faz chamadas.

Os filtros nunca são descartados silenciosamente. Com auto, os provedores de dados que não conseguem aplicá-los são ignorados; um provedor de dados nomeado que não consegue aplicá-los retorna 400.

Opções disponíveis:
search,
list_employees,
enrich,
find_email,
verify_email,
find_phone
​
provider
enum<string> | null

Padrão auto: selecione o primeiro provedor de dados elegível na ordem de preferência da Glasser. Um provedor de dados nomeado deve aceitar a solicitação e ser permitido pela sua Key; ele não usa fallback para outro provedor de dados. Os valores disponíveis estão listados abaixo.

Opções disponíveis:
auto,
apollo,
pdl,
leadmagic,
zoominfo,
hunter,
prospeo
​
job_titles
string[] | null

Cargos a serem correspondidos. O PDL corresponde a cada cargo exatamente como fornecido; portanto, 'CTO' não corresponde a 'Co-founder & CTO'.

Required array length: 1 - 20 elements
Required string length: 1 - 200
​
seniorities
enum<string>[] | null

Níveis de senioridade: um ou mais entre owner, founder, c_suite, partner, vp, head, director, manager, senior, entry e intern. Um provedor de dados sem um nível correspondente retorna 400 quando nomeado e é ignorado com auto. O ZoomInfo não tem os níveis founder, owner, partner, head, entry ou intern; seu nível senior corresponde a toda a categoria Non Manager, que também inclui colaboradores individuais juniores.

Required array length: 1 - 11 elements
Opções disponíveis:
owner,
founder,
c_suite,
partner,
vp,
head,
director,
manager,
senior,
entry,
intern
​
locations
string[] | null

Localizações em texto livre. O PDL corresponde a cada uma como uma substring do nome da localização da pessoa; portanto, 'london' também corresponde a 'new london, connecticut'.

Required array length: 1 - 20 elements
Required string length: 1 - 200
​
company_domain
string | null

Um domínio de site, como stripe.com. Uma URL completa é aceita e reduzida ao host.

Required string length: 3 - 253
​
keywords
string | null
Required string length: 1 - 300
​
full_name
string | null
Required string length: 1 - 200
​
email
string | null

Um endereço de e-mail.

Maximum string length: 320
Pattern: ^[^\s@]+@[^\s@]+\.[^\s@]+$
​
linkedin_url
string | null

A URL do perfil da pessoa no LinkedIn, linkedin.com/in/<slug>. Não é uma página de empresa.

Maximum string length: 2048
Pattern: linkedin\.com\/in\/[^/?#\s]+
​
limit
integer | null

Linhas a retornar. Mantenha esse valor pequeno: a regra de cobrança do endpoint roteado pode consultá-lo. Cada capacidade impõe um limite adicional.

Intervalo obrigatório: 1 <= x <= 100
​
task_id
string | null

Agrupe Runs relacionados, incluindo o fallback automático, em um único Task. Reutilize uma string estável e filtre a lista de Runs por task para recuperá-los.

​
metadata

Campos opcionais de rastreamento, retornados no Run e disponíveis como filtros. Eles nunca são enviados ao provedor de dados nem afetam o roteamento, o Price ou a idempotência.

  • Até 20 chaves: letras minúsculas, dígitos e sublinhados; comece com uma letra; no máximo 40 caracteres.
  • Valores: strings de 1–500 caracteres.
  • user_id: o ID opaco do seu usuário final, nunca o endereço de e-mail ou o nome.

Entradas inválidas são descartadas por inteiro, não truncadas. A solicitação continua, e o Run retorna os campos que foram armazenados.

Resposta

Success

​
id
string
obrigatório
​
run_url
string
obrigatório

Abra este Run no console. Requer associação ao Workspace.

​
provider
string
obrigatório
Pattern: ^[a-z0-9][a-z0-9-]*$
​
endpoint
string
obrigatório
Pattern: ^\/.+$
​
endpoint_version
integer
obrigatório
​
status
enum<string>
obrigatório

QUEUED ou RUNNING: ainda em andamento. COMPLETED: uma resposta do provedor de dados está disponível, incluindo respostas não 2xx. FAILED: consulte failure. STOPPED: interrompido antes do envio. Leia charge_usd separadamente de status.

Opções disponíveis:
QUEUED,
RUNNING,
COMPLETED,
FAILED,
STOPPED
​
failure
object | null
obrigatório

Motivo da falha do Run. Não nulo somente quando status é FAILED.

​
input
object
obrigatório
​
output
object
obrigatório

Campos normalizados por ação; enrich e find_email retornam uma pessoa com os mesmos campos de uma linha de pesquisa. A saída nativa do provedor de dados não é repetida aqui; ela permanece no Run (GET /v1/runs/:id). Os valores que um provedor de dados não informar serão nulos; uma resposta vazia tem o formato da ação com todos os campos nulos ou items: [], com result_status no_result. Nomes, cargos e rótulos são apresentados como informados pelo provedor de dados. Uma pontuação do próprio modelo de um provedor de dados recebe o nome desse provedor (pdl_likelihood) e é nula para os demais.

  • search: total_matches, items[]: name, first_name, last_name, job_title, seniority, department, headline, linkedin_url, city, region, country, country_code, email, email_status, email_catch_all, email_source, phone, company_name, company_domain, company_linkedin_url, apollo_match_confidence, pdl_likelihood, hunter_email_score, zoominfo_accuracy_score
  • list_employees: total_matches, items[]: name, first_name, last_name, job_title, seniority, department, headline, linkedin_url, city, region, country, country_code, email, email_status, email_catch_all, email_source, phone, company_name, company_domain, company_linkedin_url, apollo_match_confidence, pdl_likelihood, hunter_email_score, zoominfo_accuracy_score
  • enrich: name, first_name, last_name, job_title, seniority, department, headline, linkedin_url, city, region, country, country_code, email, email_status, email_catch_all, email_source, phone, company_name, company_domain, company_linkedin_url, apollo_match_confidence, pdl_likelihood, hunter_email_score, zoominfo_accuracy_score
  • find_email: name, first_name, last_name, job_title, seniority, department, headline, linkedin_url, city, region, country, country_code, email, email_status, email_catch_all, email_source, phone, company_name, company_domain, company_linkedin_url, apollo_match_confidence, pdl_likelihood, hunter_email_score, zoominfo_accuracy_score
  • find_phone: name, first_name, last_name, job_title, seniority, department, headline, linkedin_url, city, region, country, country_code, email, email_status, email_catch_all, email_source, phone, company_name, company_domain, company_linkedin_url, apollo_match_confidence, pdl_likelihood, hunter_email_score, zoominfo_accuracy_score
  • verify_email: email, email_status, email_catch_all, email_disposable, email_webmail, hunter_email_score
​
provider_response
object | null
obrigatório

Não nulo somente quando o status for COMPLETED.

  • Para respostas 2xx, output contém o JSON nativo do provedor de dados (qualquer formato) ou null para um corpo vazio.
  • Para respostas não 2xx, error contém o corpo de erro do provedor de dados e output é null.

Os campos confidenciais são removidos de ambos os corpos.

​
charge_usd
string | null
obrigatório

Cobrança total dos Runs nesta resposta de Solution. Nulo até que todos os Runs listados sejam finalizados. Cada Run mantém sua própria cobrança; falhas também podem ser cobradas.

Pattern: ^(0|[1-9]\d*)\.(\d{2}|\d{2}\d{0,3}[1-9])$
​
charge_basis
object | null
obrigatório

Base de cobrança de um único Run ou nulo para um total de vários Runs. Leia runs[].charge_basis para cada cobrança.

​
stoppable
boolean
obrigatório

Indica se uma solicitação de parada pode ser aceita no momento. Isso não garante que o Run possa ser interrompido antes do dispatch.

​
stop_requested_at
string<date-time> | null
obrigatório

Quando uma parada foi solicitada. O Run ainda pode continuar se o dispatch já tiver começado.

​
created_at
string<date-time>
obrigatório

Timestamp UTC no formato ISO-8601

​
started_at
string<date-time> | null
obrigatório

Timestamp UTC no formato ISO-8601

​
completed_at
string<date-time> | null
obrigatório

Timestamp UTC no formato ISO-8601

​
task_id
string | null
obrigatório
​
metadata
object
obrigatório

Seus campos de rastreamento armazenados. Use-os para filtrar Runs. Eles nunca são enviados ao provedor de dados nem afetam o roteamento, o Price ou a idempotência.

  • Até 20 chaves: letras minúsculas, dígitos e sublinhados; devem começar com uma letra; no máximo 40 caracteres.
  • Valores: strings de 1 a 500 caracteres.
  • user_id: o ID opaco do seu usuário final, nunca o endereço de e-mail ou o nome dele.
​
action
enum<string>
obrigatório
Opções disponíveis:
search,
list_employees,
enrich,
find_email,
verify_email,
find_phone
​
result_status
enum<string>
obrigatório

Status de entrega comercial, independente do ciclo de vida final do Run em status. no_result é uma resposta vazia, mas válida; error significa que a saída do provedor de dados não pôde ser entregue.

Opções disponíveis:
success,
no_result,
error,
pending
​
error
object | null
obrigatório
​
runs
object[]
obrigatório
​
result_url
string
obrigatório

Caminho de URL autenticado e somente leitura para consultar este resultado normalizado e a cobrança total. Use-o com a origem da API. Não cria Runs nem retoma o fallback. GET /v1/runs/:id ainda retorna o Run nativo e individual.