apollo

The layout is conventional and sensible: a config file holding APOLLO_BASE_URL and APOLLO_API_KEY, loaded automatically by the scripts, with low-level helpers beneath higher-level operations. The trade-off to internalise is economic rather than technical. Enrichment calls consume credits per record, so an agent that loops over a list before narrowing it can burn a monthly quota in one pass; broad search first, enrich the shortlist second. Because the config lives in a file rather than the environment, be deliberate about where that file is written so the key is not committed alongside example configs.

Use case: Enriching and searching people and organisation records when the request set has already been narrowed.

# Working with the apollo enrichment scripts The skill ships generic request helpers plus a small set of task-specific wrappers. The wrappers are the reliable path: people search, website enrichment by domain, and bulk organisation lookup. The generic helper exists for endpoints the wrappers do not cover, and endpoint availability varies, so read a 403 from a generic call as an entitlement question before treating it as a bug. ## Auth and rate limits The credential travels in a header that the scripts set for you, so you only manage the environment file. Two operational facts dominate real use: some endpoints require a master key on a paid plan, and many endpoints rate-limit on the order of hundreds of calls per hour. A 429 under bulk work is expected, not exceptional. ## Order of operations Resolve the organisation by domain first, cache the identifier it returns, and enrich people against that identifier. Keyword-first people searches burn quota on near-duplicates and leave you guessing which company each contact belongs to. ```bash # resolve the company, then enrich against its stable identifier ./apollo-enrich-website.sh "example.com" ./apollo-orgs-bulk.sh "organisation-id-from-the-previous-call" # generic passthrough only when no wrapper covers the endpoint ./apollo-post.sh "/api/v1/mixed_people/api_search" '{"q_keywords":"vp marketing","page":1,"per_page":5}' ``` ## Tips - Start from a domain or an organisation identifier; it keeps results stable across pages. - Read the environment file before debugging any script. Most failures are a missing base address or key. - Store identifiers you resolve rather than display names, so later lookups do not depend on re-searching. - gotcha: enrichment endpoints often sit behind paid tiers, so a 403 can be correct behaviour for a valid request; confirm the plan before rewriting the call. - gotcha: retrying a 429 immediately compounds the problem. Back off by a delay proportional to the batch size.