For AI agents: the complete documentation index is available at https://docs.clickmax.io/llms.txt, the full documentation bundle is available at https://docs.clickmax.io/llms-full.txt, and this page is available as Markdown at https://docs.clickmax.io/reference/api/apollo.md.
  • Português
  • Como usar a Apollo pela API da Clickmax

    A API da Clickmax faz chamadas à Apollo.io para buscar pessoas e empresas e identificar contatos, com a mesma chave de API da Clickmax que você já usa nas outras chamadas. Você não precisa ter conta na Apollo: sem chave própria conectada, a Clickmax faz a chamada pela conta dela. Se preferir usar a sua conta Apollo, conecte a chave dela ao workspace, e as chamadas passam a gastar os créditos e a contar nos limites da sua conta Apollo.

    Antes de começar, você precisa de:

    • uma chave de API do workspace da Clickmax (veja Autenticação na API da Clickmax);
    • só para usar a sua conta Apollo: uma chave de API da Apollo, criada nas configurações da sua conta Apollo, com acesso aos endpoints que você vai usar, e permissão para gerenciar integrações no workspace.

    A conexão com a Apollo existe só pela API. Ela não aparece na tela de Integrações.

    Os exemplos usam o SDK TypeScript. Pela API HTTP, os caminhos são os mesmos, sob /api/v0/apollo/. As respostas trazem o corpo da Apollo sem mudanças dentro de data.

    Usar a sua conta Apollo (opcional)

    import { Clickmax } from '@clickmax/public-sdk'
    
    const clickmax = new Clickmax(process.env.CLICKMAX_API_KEY!)
    
    const [ok, error, status] = await clickmax.apollo.connect({
      apiKey: process.env.APOLLO_API_KEY!,
    })

    A Clickmax confere a chave com a Apollo antes de guardar, sem gastar créditos. Uma chave recusada não é guardada. Conectar de novo troca a chave anterior. Cada workspace tem uma chave Apollo.

    • clickmax.apollo.status() mostra se há uma chave conectada, sem consultar a Apollo. O campo billing diz qual conta as chamadas usam: own_key (a sua conta Apollo) ou clickmax_credits (a conta da Clickmax).
    • clickmax.apollo.health() confere de novo a chave guardada com a Apollo. Use nas telas de teste de conexão. Sem chave conectada, volta o erro apollo_not_connected.
    • clickmax.apollo.disconnect() remove a chave. As chamadas seguintes voltam a usar a conta da Clickmax.

    Buscar pessoas

    const [ok, error, result] = await clickmax.apollo.peopleSearch({
      person_titles: ['diretor comercial'],
      person_seniorities: ['owner', 'founder', 'c_suite', 'director'],
      organization_locations: ['Belo Horizonte, Brazil'],
      organization_num_employees_ranges: ['11,50', '51,200'],
      page: 1,
      per_page: 100,
    })
    
    for (const person of result?.data.people ?? []) {
      console.log(person.id, person.first_name, person.title, person.organization?.name)
    }
    • Os filtros aceitos são q_keywords, q_organization_name, q_organization_keyword_tags, organization_locations, organization_num_employees_ranges, organization_ids, organization_domains, person_titles, person_titles_current_only, person_seniorities, person_locations, contact_email_status e currently_using_any_of_technology_uids. Outros campos são ignorados sem erro.
    • per_page vai até 100. A paginação vem em data.pagination ou em data.total_entries, como a Apollo devolver.
    • Para listar quem trabalha numa empresa, envie o id da empresa em organization_ids.
    • A busca não é cobrada. Ela não traz e-mail, telefone nem o sobrenome completo (vem em last_name_obfuscated). Para isso, passe o id de cada pessoa para peopleMatch.

    Identificar uma pessoa

    const [ok, error, result] = await clickmax.apollo.peopleMatch({
      email: '[email protected]',
      reveal_personal_emails: true,
    })
    
    const person = result?.data.person
    if (person && person.match_confidence !== 'none') {
      console.log(person.name, person.title, person.email, person.organization?.primary_domain)
    }

    Envie um destes: id, email, linkedin_url, ou um nome (first_name + last_name, ou name) junto com domain ou organization_name. Sem nenhum deles, a chamada volta com erro invalid_input antes de chegar à Apollo.

    Confira data.person.match_confidence para saber se a Apollo encontrou a pessoa:

    • high, medium ou low indicam que a Apollo achou alguém, com mais ou menos certeza.
    • none, ou data.person: null, indica que a pessoa não foi encontrada. Mesmo assim, a resposta é de sucesso, e data.person pode vir preenchido só com o e-mail enviado e a empresa do domínio desse e-mail, em data.person.organization.

    A identificação só é cobrada quando encontra a pessoa. Com match_confidence: none, nada é cobrado.

    Telefones e o waterfall de e-mail não são pedidos: a Apollo só entrega esses dados depois, por webhook.

    Buscar a empresa pelo domínio

    const [ok, error, result] = await clickmax.apollo.organizationEnrich({ domain: 'empresa.com.br' })
    
    console.log(result?.data.organization?.id, result?.data.organization?.estimated_num_employees)

    Quando a Apollo não conhece o domínio, a resposta é de sucesso com data.organization: null, e nada é cobrado.

    Descobrir o domínio pelo nome da empresa

    const [ok, error, result] = await clickmax.apollo.organizationSearch({
      q_organization_name: 'Empresa Exemplo',
      page: 1,
      per_page: 3,
    })
    
    const domain = result?.data.organizations?.[0]?.primary_domain

    Cada página é cobrada, mesmo quando vem vazia.

    Tempo limite

    Todas as chamadas que consultam a Apollo aceitam timeout, de 1000 a 60000 milissegundos, com padrão de 30000. Mantenha o timeout do cliente da Clickmax (padrão de 60000) acima do timeout da chamada, para receber a resposta da Apollo em vez de um erro de tempo do SDK.

    Erros da Apollo

    Leia o code do erro para decidir o que fazer.

    codeStatusO que significaO que fazer
    apollo_not_connected412health foi chamado sem chave Apollo conectadaConecte a sua chave com apollo.connect, ou não confira a chave
    apollo_key_invalid412A Apollo recusou a sua chave conectadaConecte uma chave válida, ou desconecte para usar a conta da Clickmax
    apollo_forbidden403A Apollo negou a chamada, por exemplo porque o plano da sua conta Apollo ou a chave não liberam esse endpointAjuste a chave ou a conta na Apollo; a mensagem traz o motivo
    apollo_insufficient_credits402A sua conta Apollo está sem créditosRecarregue a conta na Apollo
    apollo_rate_limited429A Apollo limitou as chamadas da sua contaEspere o tempo de retryAfter e tente de novo. Quando a Apollo não informa o tempo, retryAfter vem com 10 segundos
    apollo_timeout504A Apollo não respondeu a tempoTente de novo ou aumente o timeout
    apollo_invalid_request400A Apollo recusou os parâmetrosCorrija a chamada; a mensagem traz o motivo
    apollo_unavailable502 ou 503A Apollo falhou, ou a conta da Clickmax na Apollo está indisponível no momentoTente de novo mais tarde, respeitando retryAfter quando vier, ou conecte a sua chave

    Ao conectar, uma chave recusada volta com status 422 e não é guardada.

    A Clickmax não repete chamadas à Apollo por conta própria. Os limites de chamadas da API da Clickmax continuam valendo.