Build an Apollo Lead Enrichment Agent With Cost Controls

The safe Apollo lead enrichment pattern is search first, shortlist second, and enrich only the reviewed few. Do not ask an agent to enrich every result or start outreach in the same run.

That separation controls three things at once: Apollo provider credits, Aident execution credits, and the amount of personal data entering the workflow. It also gives a reviewer a clean stop point before the expensive and privacy-sensitive step.

The Short Answer

The live Aident Loadout contracts on August 12, 2026 supported this sequence:

Apollo's official People API Search documentation makes the same provider boundary explicit: search does not return email addresses or phone numbers, and enrichment is a separate endpoint. Apollo currently documents people search as zero provider credits and people enrichment as variable, depending on the data returned.

The prices above are dated Aident preflight evidence, not permanent promises. Rediscover and preflight the current Actions before each batch.

Keep Aident Credits and Apollo Credits Separate

An agent can pass Aident preflight and still fail at Apollo's provider boundary.

The bounded verification for this guide proved that distinction:

• a people-search input preflighted at zero Aident credits and executed once, returning a valid empty shortlist;

• a one-lead enrichment input preflighted at exactly 2 Aident credits but was not executed because there was no reviewed lead key;

• an optional organization-first search preflighted at exactly 2 Aident credits, then Apollo rejected the provider request for insufficient Apollo lead credits.

Do not treat the provider rejection as permission to bypass Loadout or call Apollo directly. It is a useful stop result. Add provider budget, narrow the job, or end the run.

Apollo's API pricing guide says credit use depends on both the endpoint and returned data. It also recommends testing a small request before scaling. Aident preflight covers the Aident execution estimate; it cannot promise that the connected Apollo workspace has provider credits for the final call.

Start From the Live Actions

Install or update Aident Loadout from the canonical guide:

Follow https://aident.ai/SETUP.md

Confirm the account and Vault state:

aident account auth status
aident vault vault --action status

Search by job rather than copying an internal identifier from an old article:

aident capabilities search \
  --queries '[
    "find candidate leads in Apollo from an ideal customer profile",
    "enrich a reviewed subset of Apollo lead IDs"
  ]' \
  --types '["action"]' \
  --targetEnv staging

Keep the exact public Action names returned by discovery. Inspect both current contracts:

aident capabilities get \
  --name "<current Apollo ICP people-search Action>" \
  --parts '["inputSchema","outputSchema","examples"]'

aident capabilities get \
  --name "<current Apollo lead-enrichment Action>" \
  --parts '["inputSchema","outputSchema","examples"]'

Stop if discovery is ambiguous, the connection is missing, or the enrichment result does not accept the stable lead key returned by search.

Define a Bounded ICP Contract

Write the inclusion and exclusion rules before calling Apollo. A useful first contract includes:

• one or two job-title families;

• one geography;

• an employee range;

• any required company domains or industries;

• explicit excluded domains; and

• a hard maximum shortlist size.

Avoid a vague request such as “find everyone who might buy.” It is impossible to review and encourages an agent to widen filters until it returns volume.

For example, preflight a small people search:

aident capabilities preflight \
  --name "<current Apollo ICP people-search Action>" \
  --input '{
    "icp": {
      "titles": ["VP Engineering", "Head of AI"],
      "geo": ["United States"],
      "keywords": ["developer tools", "AI agents"],
      "employeeRange": "11-200"
    },
    "limit": 10,
    "maxLeads": 5,
    "runName": "reviewed-apollo-test",
    "notes": "Shortlist only. Do not enrich or contact."
  }'

Preflight must validate the exact input and quote the current Aident cost without dispatching Apollo. If the input is valid and the quote fits the ceiling, execute the search once. An empty shortlist is a valid result. Do not automatically broaden the ICP or repeat the request.

Review Before Enrichment

Search results should be candidates, not permission to collect more data.

Review the returned organization, title, location, and stable external lead key. Remove obvious mismatches and duplicates. Keep only the leads needed for the immediate business question.

Then preflight the narrowest enrichment call:

aident capabilities preflight \
  --name "<current Apollo lead-enrichment Action>" \
  --input '{
    "leadIds": ["<one reviewed external lead key>"],
    "runId": "<search run ID>",
    "revealPersonalEmails": false
  }'

The current contract accepts at most ten lead IDs. Start with one. Keep revealPersonalEmails false unless the user has a specific, lawful need for personal email data.

Execute only when:

• the lead key came from the reviewed search run;

• the exact Aident quote is within budget;

• the Apollo workspace has the required provider credits;

• the requested fields are necessary for the stated job; and

• retention, consent, and outreach rules are already defined.

This article stops at enrichment. Creating contacts, adding people to a sequence, or sending messages is a separate write workflow with its own review.

Account-First Prospecting Is Optional

When the ICP depends on company characteristics, start with an organization search, shortlist domains, and pass only those domains into people search. This produces a clearer account-first funnel.

It can also consume provider credits. In the dated verification, the organization-search Action passed its 2-credit Aident preflight but Apollo rejected the call because the connected workspace lacked lead credits. The correct behavior was to stop. The article does not claim an end-to-end organization result.

If you already have an approved account list, skip the organization lookup. Reuse those domains as the single source of truth instead of paying to rediscover them.

What to Record in the Receipt

Keep a compact, privacy-conscious receipt:

• the normalized ICP and exclusions;

• discovery date and public Action names;

• search and enrichment preflight quotes;

• search run ID;

• counts received, filtered, selected, and enriched;

• provider success or failure status;

• credits charged by each layer when available; and

• reviewer and downstream authorization state.

Do not store prompts, raw provider responses, personal emails, or phone numbers in a general analytics log. Use the Action audit workflow for operational attribution, and keep product analytics separate from sensitive lead records.

For agent-wide spend limits, use the cost guardrails workflow. Credit approval and consequence approval remain separate decisions, as explained in the risk-versus-spend approval workflow.

A Safe Prompt for Codex or Claude Code

Follow https://aident.ai/SETUP.md

Build one bounded Apollo lead-enrichment review with the installed public aident
CLI. Confirm account and Vault status, discover the current Apollo people-search
and lead-enrichment Actions in staging, and inspect both schemas.

Before any provider call, show me the normalized ICP, exclusions, hard result
limit, exact public Action names, risk levels, current Aident credit estimates,
and any Apollo provider-credit dependency. Do not copy internal identifiers into
the report.

Search at most 10 candidates and return at most 5. Do not broaden filters or
repeat an empty search. Do not enrich automatically. Show only non-sensitive
shortlist fields and stable external lead keys.

Wait for my approval before enrichment. If approved, preflight one reviewed lead
with personal email reveal disabled. Stop if the input is invalid, the estimate
is unavailable or above 2 Aident credits, Apollo reports insufficient provider
credits, or the lead key is not from the reviewed run. Do not create contacts,
add sequences, send outreach, or bypass Aident Loadout

Success is not a large lead list. Success is one explainable funnel from ICP to shortlist to optional enrichment, with a receipt that proves where both budget and data expanded.

Failure Matrix

Build One Bounded Apollo Run

Follow https://aident.ai/SETUP.md

Set up Aident Loadout and review one Apollo enrichment

Sources

• Aident Loadout setup guide, reviewed August 12, 2026.

• Live Aident Loadout catalog, schemas, preflights, and bounded Apollo checks, inspected August 12, 2026.

• Apollo People API Search, reviewed August 12, 2026.

• Apollo People Enrichment, reviewed August 12, 2026.

• Apollo API pricing and credits, reviewed August 12, 2026.

Refresh this guide when the live search or enrichment schema, risk, pricing, provider-credit behavior, result-key contract, or Apollo data policy changes.