LeadHaste

Apollo.io API Guide: Build a Safe Prospecting Data Handoff

Dimitar Petkov
Dimitar Petkov·Nov 20, 2026·10 min read

Summarize with AI

The Apollo.io API separates prospect search, enrichment, Apollo contact creation, and delivery to an external CRM. Build the integration around those boundaries. A successful search does not include contact details, an enrichment match does not prove accuracy, and an Apollo contact ID does not prove that Salesforce or HubSpot received the record.

The Apollo.io API has four different jobs

Apollo's API overview covers data discovery, enrichment, contact management, usage, and other workspace operations. Treat them as four auditable jobs:

  1. search Apollo's database for candidate records;
  2. enrich selected candidates with additional fields;
  3. create or update records inside Apollo when needed;
  4. deliver accepted records to the external CRM through a separately verified route.

This separation prevents one common mistake: taking a broad search result and turning it into a send-ready CRM contact in one opaque workflow. Each stage needs a pass condition, an owner, and a durable record of what changed.

StageInput decisionOutput evidenceStop condition
SearchApproved filters and lawful business purposeQuery, page, Apollo person or company IDsResult is outside the target account or role rules
EnrichmentCandidate passes source and suppression checksMatch confidence, returned fields, credit deltaIdentity is ambiguous or cost exceeds the approved route
Apollo contactRecord passes duplicate and required-field checksApollo contact ID, exact request, final stateExisting contact or ambiguous timeout
CRM handoffAccepted field map and ownerCRM record ID, before-and-after fields, sync resultDuplicate, protected-field overwrite, or suppression conflict

Our view is that enrichment should never write directly to production CRM fields. Stage the result first. It is cheaper to reject one uncertain match than to repair a contact, company, owner, and campaign after a bad write spreads.

Authenticate and prove endpoint access

Apollo accepts an API credential in the x-api-key header, according to its authentication documentation. Access can depend on the credential type, configured access, endpoint, and plan.

Apollo's current pricing page lists API access on Free and API enrichment on paid plans. That does not mean every endpoint or data field is available on every account. Start the test by recording the workspace plan, credential type, scopes or access settings, UTC time, and endpoint. Use a dedicated integration credential and keep it out of source code and application logs.

Test one allowed read and one intentionally disallowed operation. Rotate the credential and verify that the retired credential fails. If a production job depends on a seller's personal credential, stop and replace it before launch.

Search is discovery, not enrichment

The People API Search endpoint can return as many as 100 records per page across a documented maximum of 500 pages. It does not return email addresses or phone numbers and currently consumes zero credits.

That makes search useful for narrowing candidates before spending enrichment credits. Use a small per_page during development and keep the query filters with the result. A person ID without the query that produced it cannot explain why the record entered the workflow.

Company Search has different economics. Apollo's API pricing and credits documentation currently lists Company Search at one credit per page, with as many as 100 results per page. Company Enrichment is a separate one-credit-per-company operation. Do not reuse People Search assumptions for company requests.

A release test should confirm the actual response fields and credit movement on the account because current, legacy, and contracted Apollo plans can differ.

Enrichment cost depends on what returns

People Enrichment matches supplied identifiers to Apollo data and can return a match_confidence value. Apollo's current credit guide says demographics or email can use one credit, with eight additional credits when a mobile phone is returned. Waterfall configurations can cost more, and some configured providers may charge for a lookup without a match.

Bulk People Enrichment accepts up to ten people in one request. The batch does not convert the endpoint into one billable operation. Credits are assessed per person under the applicable enrichment rules.

Design the first test to bound the cost:

  • record team credit limits, consumed credits, and remaining credits;
  • enrich one known match and one deliberate no-match;
  • leave phone reveal and waterfall providers off initially;
  • retain submitted identifiers, Apollo person ID, match confidence, returned-field categories, and credit delta;
  • then test a two-record bulk request and reconcile each person separately.

Apollo exposes a credit usage endpoint that reports team-level limit, consumed, and remaining values. The documentation says it costs zero credits and updates within seconds. Call it before and after the fixture rather than estimating from the number of requests.

Match confidence is evidence from Apollo's matching process. It is not proof that the identity, employer, email, or phone is current. Require a separate internal acceptance rule and preserve Apollo's source state rather than relabelling every match as verified.

Contact creation needs explicit deduplication

The Create a Contact endpoint creates a record inside Apollo. It does not create a CRM record by itself. Apollo's conversion tutorial also warns that the normal enriched-person-to-contact flow does not automatically deduplicate every record.

Apollo provides a potential duplicate lookup and a run_dedupe option for contact creation. Use both deliberately. Do not rely on a default that may differ between single and bulk operations.

Maintain your own idempotency ledger indexed by a deterministic source fingerprint, intended Apollo list or owner, and action. The public contact-create reference does not document an idempotency mechanism. If a request times out, reconcile by source fingerprint, email where appropriate, and Apollo IDs before repeating the write.

Test at least these cases:

  1. a new person with a stable source ID;
  2. the same request repeated unchanged;
  3. an existing contact with the same email;
  4. the same name at a different company;
  5. an existing person whose email has changed;
  6. a bulk request containing one invalid record;
  7. a timeout after the server may have accepted the request;
  8. two workers attempting the same write.

Bulk contact creation supports up to 100 contacts per request. Stay far below that maximum until response mapping, partial failures, and dedupe behavior are proven on the workspace. Batch size is a throughput limit, not a quality target.

Rate limits belong in runtime state

Apollo says rate limits vary by endpoint and plan. Its rate-limit documentation describes minute, hour, and day information in response headers and a 429 Too Many Requests response when a limit is exceeded.

Read the headers on every response and store the limit state with the job. Use bounded retries with backoff and jitter only for requests known to be safe to repeat. Enrichment reads and contact writes do not share the same retry risk.

A contact-write timeout has three possible states: rejected, accepted with a lost response, or still processing. Put it into an ambiguous-write queue and reconcile before retrying. A rate-limit handler that blindly resubmits writes can create the duplicates the dedupe check was meant to prevent.

Do not load-test by exhausting a production account. Use a small controlled sequence, confirm 429 handling with a vendor-supported test or mocked receiver where necessary, and validate that queued work preserves order and idempotency.

A CRM handoff is another transaction

Apollo's terms describe customer CRMs and marketing systems as third-party systems outside Apollo's ownership and control. A returned Apollo contact ID therefore proves only the Apollo record.

Transform accepted data into a staging schema before the CRM write. For every field, name the source, prior value, proposed value, overwrite rule, and authority. The CRM should retain control of account owner, lifecycle or opportunity stage, suppression, and seller-corrected identity fields.

Use fill-only updates first. Allow an enriched value to fill a blank approved field, but do not overwrite a corrected phone number, title, company, or consent state without a specific rule. Keep Apollo's result and evidence date beside the accepted value.

The CRM transaction should return its own record ID and final field state. Verify that ID through a fresh CRM read. A connector status or queue acknowledgement is not enough.

Apollo's Terms of Service also put responsibilities on the customer. They prohibit several uses, including Fair Credit Reporting Act purposes, unlawful activity, certain marketing-law violations, resale or unauthorized distribution of business-contact information, and attempts to evade credits or rate limits. Apollo's Privacy Policy says customer-submitted business-contact data may be used to grow, enrich, and verify its contributor database. Review those terms against the exact data being submitted.

Run a two-stage shadow handoff

Use company-controlled or expressly consented fixture records, one deliberate no-match, a dedicated Apollo list where available, and a CRM sandbox. Disconnect production CRM automation during the test.

  1. Record the plan, credential type, endpoint access, credit state, and rate-limit headers.
  2. Run one tightly filtered People Search page. Confirm that it returns no email or phone and causes no credit delta.
  3. Enrich one known match and one no-match with phone and waterfall routes disabled. Record match confidence, fields, and credits.
  4. Run a two-person bulk enrichment request. Reconcile each result and the total credit change.
  5. Transform results into a staging table. Apply required-field, suppression, territory, owner, source, and freshness rules without writing to Apollo or the CRM.
  6. Call the potential-duplicate endpoint. Create one test contact with run_dedupe=true, then retrieve it by the returned Apollo contact ID.
  7. Repeat the logical request. Require the idempotency ledger and reconciliation step to prevent another contact.
  8. Send the accepted record separately to the CRM sandbox. Verify the returned CRM ID, field values, owner, suppression state, and duplicate count with a fresh read.
  9. Exercise an ambiguous timeout and 429 path without uncontrolled retries. Confirm that the job pauses with enough evidence to reconcile. Reverse the CRM changes, remove test data through the supported account route, revoke the credential, and export the evidence.

Release only with zero unexplained writes, zero protected-field overwrites, correct dedupe behavior, bounded credit movement, visible rate-limit handling, and a reversible CRM result. Keep search, enrichment, Apollo contact state, and CRM state reconcilable by stable IDs.

LeadHaste can connect sourcing, enrichment, suppression, CRM ownership, and campaign execution in infrastructure your team controls. See our managed outbound services and outbound resources to define the acceptance fixture before production data moves.

Book your free ICP review →

Frequently Asked Questions

A modern outbound stack includes: data enrichment (Apollo, Clay, ZoomInfo), email infrastructure (Google Workspace, custom domains), sending tools (Smartlead, Instantly), warm-up services (Warmbox), LinkedIn automation (Expandi, Dripify), CRM integration (HubSpot, Salesforce), and analytics platforms. Most agencies use 15–30 tools orchestrated together.

Building your own stack costs $3K–5K/month in software alone, plus a dedicated person to manage it. With a managed service, you get all the tooling plus the expertise to orchestrate it, often at lower total cost. The key question: can you afford to spend 6–8 weeks setting up instead of generating pipeline?

There's no single 'best' tool. It depends on your volume, budget, and integration needs. Smartlead and Instantly are popular for high-volume sending. Apollo doubles as a data and sequencing platform. The real advantage comes from how tools are orchestrated together, not from any single tool choice.

Look for three things: (1) Do you own the infrastructure they build? (2) Are the engagement terms clear, including what happens after the initial build-and-learn period? (3) Can you see transparent metrics and real case studies with specific numbers? LeadHaste starts with a three-month engagement, then moves month-to-month. Avoid vague reporting and providers that own your domains.

Data enrichment is the process of taking basic company or contact data and adding layers of detail: job titles, direct emails, phone numbers, technographics, intent signals, company size, funding stage, and more. Enrichment tools like Apollo, Clay, and ZoomInfo pull from multiple data sources to build a complete prospect profile before outreach begins.

Apollo.ioAPIdata enrichmentCRM integration
Dimitar Petkov

Dimitar Petkov

Co-Founder of LeadHaste. Builds outbound systems that compound. 4x founder, Smartlead Certified Partner, Clay Solutions Partner.

Newsletter

The weekly for people who buy outbound.

Five things that changed in outbound this week, why they matter, and what to do about each. Read by founders, sales leaders and growth leads at B2B companies.

Read past issues →

Ready to build outbound that compounds?

We'll build the entire system for your business, and the infrastructure it runs on stays yours.

Book my free review →