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)
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. Thebillingfield says which account calls use:own_key(your Apollo account) orclickmax_credits(the Clickmax account).clickmax.apollo.health()rechecks the stored key with Apollo. Use it on connection test screens. Without a key connected, it returnsapollo_not_connected.clickmax.apollo.disconnect()removes the key. Later calls go back to the Clickmax account.
Search people
- 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_statusandcurrently_using_any_of_technology_uids. Other fields are ignored without an error. per_pagegoes up to 100. Pagination comes indata.paginationor indata.total_entries, as Apollo returns it.- To list the people at a company, send the company
idinorganization_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'sidtopeopleMatch.
Identify a person
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,mediumorlowmean Apollo found someone, with more or less certainty.none, ordata.person: null, means the person was not found. The response still succeeds, anddata.personmay carry only the email you sent and the company behind that email's domain, indata.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
When Apollo does not know the domain, the response succeeds with data.organization: null, and nothing is charged.
Find a domain by company name
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.
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.