Apollo

Apollo plays two separate roles in iCallAgent, and it's worth knowing which one you want before you connect it:

You want to…	Use Apollo as	Where you configure it
Call the people on an Apollo list, and keep calling new ones as they're added	A contact source for a folder	Contacts → + New group
Let an agent look up or write Apollo records mid-call	An agent tool	The agent's tools, after connecting

One connection covers both. The rest of this page is split the same way.

Connecting

Apollo's OAuth flow is partner-only: you register an app from Apollo's own Settings → Integrations → API → OAuth registration screen, and Apollo has to approve it before the flow will work. Only Apollo users with the Admin or Billing and Seat Manager role can authorise the connection.

Navigate

1. Open the dashboard.
2. Left sidebar → Configure → Integrations.
3. + Add Integration → Apollo.
4. Approve the consent screen in Apollo.

The redirect URL registered on the iCallAgent side is:

https://api.icallagent.com/api/integrations/apollo/callback/

Access tokens last 30 days. iCallAgent refreshes them a few minutes before expiry, and because Apollo issues a new refresh token on every refresh and revokes the old one, the replacement is stored as part of the same operation. If a refresh ever fails — the grant was removed on the Apollo side, for instance — tools return a message asking you to reconnect rather than failing silently, and a folder syncing from Apollo shows the reason on its row.

Scopes

The scopes are fixed when you register the app in Apollo; iCallAgent requests exactly what your app was approved for rather than asking for a wider set, because requesting an unapproved scope fails the whole authorization. What you need depends on which role you're after:

Scope	Needed for
read_user_profile	Always — Apollo adds it by default, and it's what labels the connection with your Apollo account email
tags_list	Listing your Apollo lists when creating a folder
contacts_search	Syncing a folder, and the agent tool's lookup_record
contact_write / contact_update	The agent tool's create_record / update_record on contacts
account_read / account_write	The same actions against accounts
opportunity_read / opportunity_write	The same actions against deals

If a scope is missing, Apollo answers with a permission error and iCallAgent surfaces its text verbatim — the list picker will say so rather than showing an empty list.

Apollo as a contact source

A folder (a contact group) can be tied to one of your Apollo lists. iCallAgent then pulls that list on a schedule, files the contacts into the folder, and — if a campaign follows that folder — queues calls for the ones it hasn't called yet.

Navigate

1. Left sidebar → Configure → Contacts.
2. + New group.
3. Sync from → Apollo.
4. Pick the Apollo list, optionally narrow it with a keyword, and choose how often it syncs: only when you press sync, hourly, or daily.
5. Test this source runs the configuration once and reports what it found before you commit.

Curate the list in Apollo; the folder follows it.

What a sync actually does

Behaviour	Detail
Matching	A record is matched on its Apollo id first, then on phone number — so a contact whose number changed upstream is updated, not duplicated, and one you'd already imported by hand isn't forked into a second row
Contacts with no phone number	Skipped, and counted. They can't be called, and importing them would inflate campaign totals with rows that always fail. The folder reports how many were left behind
Field updates	A blank value from Apollo never overwrites a filled local field
Hand-added contacts	A sync only ever removes members it added itself, so anyone you dragged into the folder stays
Ceiling	5,000 records per sync. Narrow the list in Apollo if it's larger — the preview warns you when you're over
Phone number chosen	The first of mobile, direct, corporate, home, other, then the phone_numbers array

Failures are recorded on the folder itself: the row shows Apollo's own message ("Apollo denied this request — the connected app may be missing a required scope") rather than sending you to a log.

Calling a synced folder

In the campaign wizard's Contacts step, switch from Pick contacts to Use a group and choose the folder. One checkbox decides what happens after the campaign starts:

• Checked — contacts that join the folder later, including from the next Apollo sync, are queued into the running campaign. This is what makes the campaign dynamic.
• Unchecked — the campaign calls the folder's members as they were when it launched.

Blacklisted contacts are left out at enrollment rather than queued and rejected at dial time. See Campaigns for the rest of the wizard.

Apollo as an agent tool

Attach Apollo to an agent and it can read and write Apollo records during a call.

Field	Required	Description
action	Yes	lookup_record (default), create_record, or update_record
object_type	Yes	lead, contact, account, or deal
lookup_field	No	Defaults to email
instructions	No	Notes for the agent on when to use the tool

Apollo has no separate lead object, so lead and contact both map to Apollo contacts. account maps to accounts and deal to opportunities.

Action	What it does	Arguments the agent supplies
lookup_record	Searches your Apollo records	query, email, or phone
create_record	Creates a contact, account, or deal	name (required), email, phone, company
update_record	Updates one record	id (required), plus any of name, email, phone

Two behaviours worth knowing:

• Results are trimmed. Apollo records carry around a hundred fields; the tool returns a small projection (id, name, email, title, company, phone numbers) so the agent isn't fed a wall of JSON mid-call.
• Deal lookup filters locally. Apollo's deal search takes no keyword filter, so iCallAgent pulls a page of opportunities and matches on the deal name itself. Contacts and accounts are filtered by Apollo.

Related

• Campaigns — scheduling, retries, and disclosure settings
• Tools — how agent tools are attached and called
• Integrations overview