For AI agents: the complete documentation index is available at https://docs.clickmax.io/en/llms.txt, the full documentation bundle is available at https://docs.clickmax.io/en/llms-full.txt, and this page is available as Markdown at https://docs.clickmax.io/en/reference/api/apollo.md.
  • English
  • How to use Apollo through the Clickmax API

    The Clickmax API calls Apollo.io to search people and companies and identify contacts, with the same Clickmax API key you use for other calls. You do not need an Apollo account: without a key of your own connected, Clickmax makes the call on its own account. If you prefer your Apollo account, connect its key to the workspace, and calls then spend the credits and count toward the limits of your Apollo account.

    Before you start, you need:

    • a Clickmax workspace API key (see Authentication in the Clickmax API);
    • only to use your own Apollo account: an Apollo API key, created in your Apollo account settings, with access to the endpoints you will use, and permission to manage integrations in the workspace.

    The Apollo connection exists only through the API. It does not appear on the Integrations screen.

    The examples use the TypeScript SDK. Over HTTP, the paths are the same, under /api/v0/apollo/. Responses carry Apollo's body unchanged inside data.

    Use your own Apollo account (optional)

    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!,
    })

    Clickmax checks the key with Apollo before storing it, without spending credits. A rejected key is not stored. Connecting again replaces the previous key. Each workspace has one Apollo key.

    • clickmax.apollo.status() tells whether a key is connected, without calling Apollo. The billing field says which account calls use: own_key (your Apollo account) or clickmax_credits (the Clickmax account).
    • clickmax.apollo.health() rechecks the stored key with Apollo. Use it on connection test screens. Without a key connected, it returns apollo_not_connected.
    • clickmax.apollo.disconnect() removes the key. Later calls go back to the Clickmax account.

    Search people

    const [ok, error, result] = await clickmax.apollo.peopleSearch({
      person_titles: ['sales director'],
      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)
    }
    • Accepted filters are 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 and currently_using_any_of_technology_uids. Other fields are ignored without an error.
    • per_page goes up to 100. Pagination comes in data.pagination or in data.total_entries, as Apollo returns it.
    • To list the people at a company, send the company id in organization_ids.
    • Search is not charged. It does not return emails, phone numbers or the full last name (it comes in last_name_obfuscated). For those, pass each person's id to peopleMatch.

    Identify a person

    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)
    }

    Send one of: id, email, linkedin_url, or a name (first_name + last_name, or name) together with domain or organization_name. Without any of them, the call fails with invalid_input before reaching Apollo.

    Check data.person.match_confidence to know whether Apollo found the person:

    • high, medium or low mean Apollo found someone, with more or less certainty.
    • none, or data.person: null, means the person was not found. The response still succeeds, and data.person may carry only the email you sent and the company behind that email's domain, in data.person.organization.

    Identifying is charged only when the person is found. With match_confidence: none, nothing is charged.

    Phone numbers and email waterfall are not requested: Apollo only delivers that data later, by webhook.

    Get a company by domain

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

    When Apollo does not know the domain, the response succeeds with data.organization: null, and nothing is charged.

    Find a domain by company name

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

    Each page is charged, even an empty one.

    Timeout

    Every call that reaches Apollo accepts timeout, from 1000 to 60000 milliseconds, defaulting to 30000. Keep the Clickmax client timeout (default 60000) above the call's timeout, so you get Apollo's answer instead of an SDK timeout error.

    Apollo errors

    Read the error code to decide what to do.

    codeStatusMeaningWhat to do
    apollo_not_connected412health was called with no Apollo key connectedConnect your key with apollo.connect, or skip the key check
    apollo_key_invalid412Apollo rejected your connected keyConnect a valid key, or disconnect it to use the Clickmax account
    apollo_forbidden403Apollo denied the call, for example because your Apollo account plan or the key does not allow this endpointAdjust the key or account in Apollo; the message says why
    apollo_insufficient_credits402Your Apollo account has no credits leftTop up the account in Apollo
    apollo_rate_limited429Apollo is limiting your account's callsWait for retryAfter and try again. When Apollo gives no wait time, retryAfter is 10 seconds
    apollo_timeout504Apollo did not answer in timeTry again or raise timeout
    apollo_invalid_request400Apollo rejected the parametersFix the call; the message says why
    apollo_unavailable502 or 503Apollo failed, or the Clickmax Apollo account is unavailable right nowTry again later, honoring retryAfter when present, or connect your own key

    On connect, a rejected key returns status 422 and is not stored.

    Clickmax does not retry Apollo calls on its own. The Clickmax API rate limits still apply.