> ## Documentation Index
> Fetch the complete documentation index at: https://stage-docs.oktivo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Apollo.io Integration

> Connect Apollo.io to prospect, enrich, and sync leads with Oktivo

# Apollo.io Integration Guide

Apollo.io is a prospecting and sales-intelligence platform. The Oktivo Connecter integrates Apollo so you can pull B2B prospects into your Leads for the AI to call, enrich existing leads with Apollo data, push call outcomes back onto Apollo contacts, and enroll leads into Apollo email sequences.

Unlike a two-way CRM sync, Apollo is a **data source**: it feeds fresh, enriched people into Oktivo and receives your call outcomes.

## Architecture Overview

```
┌─────────────┐   x-api-key    ┌──────────────────┐
│  Apollo.io  │ ◀────────────▶ │  Oktivo Connecter │
│             │                │                  │
│  People DB  │ ── prospects ─▶ │  CrmLead (source │
│  Contacts   │ ◀ call outcome │  = "apollo")     │
└─────────────┘                └──────────────────┘
```

Apollo authenticates with the **OAuth 2.0 partner flow** (the same model as HubSpot). The organization registers one Apollo OAuth app; each customer approves it and their access token is stored encrypted at rest and used only at the moment of a call.

## Setup (organization admin, one time)

1. In Apollo, go to **Settings → Integrations → API Keys → OAuth registration**.
2. Enter your app name and logo, and set the **OAuth Redirect URL** to Oktivo's callback (shown read-only in the Oktivo admin Connecter config):
   `https://<your-backend-domain>/api/v2/connecter/apollo/callback`
3. Select the scopes your integration needs, submit, and copy the **Client ID** and **Client Secret**.
4. In Oktivo, open **Admin → Connecter → Apollo.io** and paste the Client ID + Client Secret. The redirect URL is derived automatically you only need to register it in Apollo.

> [!NOTE]
>
> The customer authorizing the app must have permission to authorize third-party integrations in Apollo (Admin or Billing & Seat Manager, or the "Can authorize third-party apps" permission). Apollo OAuth is a partner capability confirm your Apollo plan supports it.

## Connecting Apollo (customer)

From the Connecter hub, the customer clicks **Connect** on the Apollo card. They're sent to Apollo, sign in, approve the requested scopes, and are redirected back to Oktivo connected no keys to copy. Access tokens are valid \~30 days and are refreshed automatically before they expire.

## Capabilities

### 1. Search & import prospects

From **Connecter → Apollo.io → Search & Import**, build a people search by keywords, job title, seniority, industry, company size, location, or company domain. Preview the matches, select the ones you want, and import them into your Leads.

* Only prospects with a valid phone number (E.164) become leads a phone is required to call.
* Imports dedupe by phone within your account; a repeat import of the same person enriches the existing lead rather than creating a duplicate.
* Enrichment fields (company, title, seniority, department, LinkedIn, industry, company size) are stored on the lead and surfaced as dashboard columns automatically.

### 2. Saved searches (auto-sync)

Save a search to keep new matching prospects flowing in automatically. Enabled saved searches run on a schedule (hourly by default) and import the next page of results each run, advancing a cursor so nothing is re-imported. Pause, run-now, or delete a saved search any time.

### 3. Enrich existing leads

Open a lead and use **Enrich with Apollo** to fill in a missing phone, email, job title, or company from Apollo's people data. Enrichment is gap-fill only it never overwrites a value you've already set. You can also bulk-enrich a selection from the Leads list.

### 4. Push call outcomes

When an AI call completes for an Apollo-connected account, Oktivo upserts the matching Apollo **contact**, logs a call-summary note (disposition, duration, interest, recording), and updates the contact's stage. This happens automatically through the same outbound push path used by the CRM providers.

### 5. Email sequences

From a lead, **Add to Apollo sequence** enrolls the lead's Apollo contact into one of your Apollo email sequences for multi-channel follow-up.

## Making the AI call imported prospects

Importing prospects does **not** dial them automatically. To call them:

* Open a lead and start an AI agent call from the **Call** tab, or
* Build a **Segment** of Apollo-sourced leads (filter on source = `apollo`) and launch a **Campaign** from it, then start the campaign.

## Credits & rate limits

Apollo API usage draws on your Apollo account's credits (a vendor budget, separate from Oktivo credits). Search is credit-light; enrichment and import that reveal contact info consume Apollo credits. The integration:

* Caps each import/sync run to a bounded batch size.
* Trips a circuit breaker per Apollo account on repeated rate-limit/5xx errors to avoid hammering the API.
* Surfaces a clear "out of Apollo credits" message when your account is exhausted.

## Configuration

| Env var | Default | Purpose |
| - | - | - |
| `APOLLO_API_BASE_URL` | `https://app.apollo.io/api/v1` | Apollo OAuth API base URL (token + data endpoints; override for testing). |
| `APOLLO_SYNC_ENABLED` | `true` | Master switch for the saved-search auto-sync scheduler. |

## Error Handling

| Situation | Behavior |
| - | - |
| Expired / revoked token | Auto-refreshed before expiry; if refresh fails, the connection is marked for reconnect. |
| Out of Apollo credits | `402`-class error with a "top up Apollo credits" message; batch stops. |
| Rate limited / Apollo 5xx | Temporary `503`; circuit breaker backs off and the run retries later. |
| Lead has no phone (import) | Skipped and counted; never blocks the rest of the batch. |
| No Apollo match (enrich) | Reported as "no match"; the lead is left unchanged. |

## Next Steps

* [CRM Integration Guide](https://stage-docs.oktivo.com/guides/crm-integration.md) trigger calls from your own CRM
* [Retry Logic Guide](https://stage-docs.oktivo.com/guides/retry-logic.md) configure automatic call retries


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.