Apollo Reference Architecture
Overview
Production-ready reference architecture for Apollo.io integrations. Layered design with API client, service layer, background jobs, database models, CRM sync, and deals pipeline โ all built around Apollo's REST API with correct endpoints and x-api-key authentication.
Prerequisites
- Apollo master API key
- Node.js 18+ with TypeScript
- PostgreSQL for data layer
- Redis for job queues
Instructions
Step 1: Architecture Diagram
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ API Layer โ Express routes
โ POST /api/leads/search GET /api/org/:d โ POST /api/deals
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ Service Layer โ Business logic
โ LeadService EnrichService DealService โ SequenceService
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ Client Layer โ Apollo API wrapper
โ ApolloClient RateLimiter Cache โ CreditTracker
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ Background Jobs โ BullMQ queues
โ EnrichJob SyncJob StageChangeJob โ TaskCreatorJob
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ Data Layer โ Prisma/TypeORM
โ Contact Organization Deal AuditLog โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Step 2: Service Layer
import { getApolloClient } from '../apollo/client';
import { withRetry } from '../apollo/retry';
import { cachedRequest } from '../apollo/cache';
export class LeadService {
private client = getApolloClient();
async searchPeople(params: { domains: string[]; titles?: string[]; seniorities?: string[]; page?: number }) {
return cachedRequest('/mixed_people/api_search',
() => withRetry(() => this.client.post('/mixed_people/api_search', {
q_organization_domains_list: params.domains,
person_titles: params.titles,
person_seniorities: params.seniorities,
page: params.page ?? 1, per_page: 100,
})),
params,
);
}
async enrichPerson(email: string) {
return withRetry(() => this.client.post('/people/match', { email }));
}
async enrichOrg(domain: string) {
return cachedRequest('/organizations/enrich',
() => withRetry(() => this.client.get('/organizations/enrich', { params: { domain } })),
{ domain },
);
}
}
Step 3: Deals/Opportunities Service
Apollo has a full Deals API for tracking revenue pipeline.
export class DealService {
private client = getApolloClient();
async createDeal(params: {
name: string;
amount: number;
ownerId: string; // Apollo user ID
accountId?: string; // Apollo account ID
contactIds?: string[]; // Apollo contact IDs
stageId?: string; // Deal stage ID
}) {
const { data } = await this.client.post('/opportunities', {
name: params.name,
amount: params.amount,
owner_id: params.ownerId,
account_id: params.accountId,
contact_ids: params.contactIds,
opportunity_stage_id: params.stageId,
});
return { dealId: data.opportunity.id, name: data.opportunity.name };
}
async listDeals(page: number = 1) {
const { data } = await this..(, { page, : });
data..( ({
: d., : d., : d.,
: d.?., : d.?.,
}));
}
() {
{ data } = ..();
data..( ({ : s., : s., : s. }));
}
() {
..(, {
: updates.,
: updates.,
});
}
}
Step 4: Background Job Processing
import { Queue, Worker, Job } from 'bullmq';
import { LeadService } from '../services/lead-service';
const connection = { host: process.env.REDIS_HOST ?? 'localhost', port: 6379 };
export const enrichmentQueue = new Queue('apollo-enrichment', {
connection,
defaultJobOptions: {
attempts: 3,
backoff: { type: 'exponential', delay: 5000 },
removeOnComplete: 1000,
},
});
const leadService = new LeadService();
new Worker('apollo-enrichment', async (job: Job) => {
switch (job.name) {
case 'enrich-person':
return leadService.enrichPerson(job.data.email);
case 'enrich-org':
leadService.(job..);
: {
: [] = [];
( domain job..) {
{ data } = leadService.({ : [domain] });
results.(...data.);
job.(results.);
}
{ : results. };
}
}
}, { connection, : , : { : , : } });
Step 5: Database Model
import { Entity, Column, PrimaryColumn, CreateDateColumn, UpdateDateColumn } from 'typeorm';
@Entity('contacts')
export class Contact {
@PrimaryColumn() apolloId: string;
@Column({ unique: true }) email: string;
@Column() name: string;
@Column({ nullable: true }) title: string;
@Column({ nullable: true }) : ;
({ : }) : ;
({ : }) : ;
({ : , : }) : <, >;
({ : }) : ;
() : ;
() : ;
}
Step 6: API Routes
import { Router } from 'express';
import { LeadService } from '../services/lead-service';
import { DealService } from '../services/deal-service';
const router = Router();
const leads = new LeadService();
const deals = new DealService();
router.post('/api/leads/search', async (req, res) => {
const { data } = await leads.searchPeople(req.body);
res.json({ leads: data.people, pagination: data.pagination });
});
router.post('/api/leads/enrich', async (req, res) => {
const { data } = await leads.enrichPerson(req.body.email);
res.json({ contact: data.person });
});
router.get('/api/organizations/:domain', async (req, res) => {
const { data } = await leads.(req..);
res.({ : data. });
});
router.(, (req, res) => {
result = deals.(req.);
res.(result);
});
router.(, (req, res) => {
list = deals.((req.. ) || );
res.({ : list });
});
{ router };
Output
- Layered architecture: API, Service, Client, Jobs, Data
LeadService with cached search and retried enrichmentDealService with create, list, update, and stage management- BullMQ background jobs for async enrichment
- Database model (Prisma + TypeORM)
- Express API routes for search, enrichment, and deals
Error Handling
| Layer | Strategy |
|---|
| Client | Retry with backoff, circuit breaker for prolonged outages |
| Service | Cache fallback on failure, credit budget enforcement |
| Jobs | 3 retries with exponential backoff, dead letter after max |
| API | Structured JSON error responses with error codes |
Resources
Next Steps
Proceed to apollo-multi-env-setup for environment configuration.
