Apollo Multi-Environment Setup

Overview

Configure Apollo.io for development, staging, and production with isolated API keys, environment-specific rate limits, feature gating, and Kubernetes-native secret management. Apollo provides sandbox tokens for testing that return dummy data without consuming credits.

Prerequisites

• Separate Apollo API keys per environment (or sandbox tokens for dev)
• Node.js 18+

Instructions

Step 1: Environment Configuration Schema

// src/config/apollo-config.ts
import { z } from 'zod';

const EnvironmentSchema = z.enum(['development', 'staging', 'production']);

const ApolloEnvConfig = z.object({
  environment: EnvironmentSchema,
  apiKey: z.string().min(10),
  baseUrl: z.string().url().default('https://api.apollo.io/api/v1'),
  isSandbox: z.boolean().default(false),
  rateLimit: z.object({
    maxPerMinute: z.number().min(1),
    concurrency: z.number().min(1).max(20),
  }),
  features: z.object({
    enrichment: z.boolean(),
    sequences: z.boolean(),
    deals: z.boolean(),
    bulkEnrichment: z.boolean(),
  }),
  credits: z.object({
    dailyBudget: z.number(),
    alertThreshold: z.number(),  // percentage
  }),
  logging: z.object({
    level: z.enum(['debug', 'info', 'warn', 'error']),
    redactPII: z.boolean(),
  }),
});

type ApolloEnvConfig = z.infer<typeof ApolloEnvConfig>;

Step 2: Per-Environment Configs

const configs: Record<string, ApolloEnvConfig> = {
  development: {
    environment: 'development',
    apiKey: process.env.APOLLO_SANDBOX_KEY ?? process.env.APOLLO_API_KEY_DEV!,
    baseUrl: 'https://api.apollo.io/api/v1',
    isSandbox: true,
    rateLimit: { maxPerMinute: 20, concurrency: 2 },
    features: { enrichment: true, sequences: false, deals: false, bulkEnrichment: false },
    credits: { dailyBudget: 10, alertThreshold: 80 },
    logging: { level: 'debug', redactPII: true },
  },
  staging: {
    environment: 'staging',
    apiKey: process.env.APOLLO_API_KEY_STAGING!,
    baseUrl: 'https://api.apollo.io/api/v1',
    isSandbox: false,
    rateLimit: { maxPerMinute: 50, concurrency: 5 },
    features: { enrichment: true, sequences: true, deals: true, bulkEnrichment: true },
    credits: { dailyBudget: 50, alertThreshold: 70 },
    logging: { level: 'info', redactPII: true },
  },
  production: {
    environment: 'production',
    apiKey: process.env.APOLLO_API_KEY_PROD!,
    baseUrl: 'https://api.apollo.io/api/v1',
    isSandbox: false,
    rateLimit: { maxPerMinute: 100, concurrency: 10 },
    features: { enrichment: true, sequences: true, deals: true, bulkEnrichment: true },
    credits: { dailyBudget: 500, alertThreshold: 90 },
    logging: { level: 'warn', redactPII: true

Apollo Observability

Overview

Comprehensive observability for Apollo.io integrations: Prometheus metrics (request count, latency, rate limits, credits), structured logging with PII redaction, OpenTelemetry tracing, and alerting rules. Tracks the metrics that matter: credit burn rate, enrichment success rate, and API health.

Prerequisites

• Valid Apollo API key
• Node.js 18+

Instructions

Step 1: Prometheus Metrics

// src/observability/metrics.ts
import { Counter, Histogram, Gauge, Registry } from 'prom-client';

export const registry = new Registry();

export const requestsTotal = new Counter({
  name: 'apollo_requests_total',
  help: 'Total Apollo API requests by endpoint and status',
  labelNames: ['endpoint', 'method', 'status'] as const,
  registers: [registry],
});

export const requestDuration = new Histogram({
  name: 'apollo_request_duration_seconds',
  help: 'Apollo API request duration',
  labelNames: ['endpoint'] as const,
  buckets: [0.1, 0.25, 0.5, 1, 2.5, 5, 10],
  registers: [registry],
});

export const rateLimitRemaining = new Gauge({
  name: 'apollo_rate_limit_remaining',
  help: 'Remaining requests in current rate limit window',
  labelNames: ['endpoint'] as const,
  registers: [registry],
});

export const creditsUsed = new Counter({
  name: 'apollo_credits_used_total',
  help: 'Total Apollo enrichment credits consumed',
  labelNames: ['type'] as const,  // 'person', 'organization', 'bulk'
  registers: [registry],
});

export const enrichmentSuccessRate = new Gauge({
  name: 'apollo_enrichment_success_rate',
  help: 'Percentage of enrichment calls that found a match',
  registers: [registry],
});

Step 2: Axios Interceptors for Auto-Collection

// src/observability/instrument.ts
import { AxiosInstance } from 'axios';
import { requestsTotal, requestDuration, rateLimitRemaining, creditsUsed } from './metrics';

const CREDIT_ENDPOINTS = ['/people/match', '/people/bulk_match', '/organizations/enrich'];

export function instrumentClient(client: AxiosInstance) {
  client.interceptors.request.use((config) => {
    (config as any)._startTime = Date.now();
    return config;
  });

  client.interceptors.response.use(
    (response) => {
      const endpoint = response.config.url ?? 'unknown';
      const duration = (Date.now() - (response.config as any)._startTime) / 1000;

      requestsTotal.inc({ endpoint, method: response.config.method?.toUpperCase() ?? 'GET', status: String(response.status) });
      requestDuration.observe({ endpoint }, duration);

      // Rate limit tracking
      const remaining = response.headers['x-rate-limit-remaining'

Apollo Performance Tuning

Overview

Optimize Apollo.io API performance through response caching, connection pooling, bulk operations, parallel fetching, and result slimming. Key insight: search is free but slow (~500ms), enrichment costs credits — cache aggressively and batch enrichment calls.

Prerequisites

• Valid Apollo API key
• Node.js 18+

Instructions

Step 1: Connection Pooling

Reuse TCP connections to avoid TLS handshake overhead on every request.

// src/apollo/optimized-client.ts
import axios from 'axios';
import https from 'https';

const httpsAgent = new https.Agent({
  keepAlive: true,
  maxSockets: 10,
  maxFreeSockets: 5,
  timeout: 30_000,
});

export const optimizedClient = axios.create({
  baseURL: 'https://api.apollo.io/api/v1',
  headers: { 'Content-Type': 'application/json', 'x-api-key': process.env.APOLLO_API_KEY! },
  httpsAgent,
  timeout: 15_000,
});

Step 2: Response Caching with Per-Endpoint TTLs

// src/apollo/cache.ts
import { LRUCache } from 'lru-cache';

// Different TTLs based on data volatility
const CACHE_TTLS: Record<string, number> = {
  '/organizations/enrich': 24 * 60 * 60 * 1000,    // 24h — company data rarely changes
  '/people/match': 4 * 60 * 60 * 1000,              // 4h — contact data changes occasionally
  '/mixed_people/api_search': 15 * 60 * 1000,       // 15min — search results are dynamic
  '/mixed_companies/search': 30 * 60 * 1000,         // 30min — company search
  '/contact_stages': 60 * 60 * 1000,                 // 1h — stages rarely change
};

const cache = new LRUCache<string, { data: any; at: number }>({
  max: 5000,
  maxSize: 50 * 1024 * 1024,
  sizeCalculation: (v) => JSON.stringify(v).length,
});

function cacheKey(endpoint: string, params: any): string {
  return `${endpoint}:${JSON.stringify(params)}`;
}

export async function cachedRequest<T>(
  endpoint: string,
  requestFn: () => Promise<T>,
  params: any,
): Promise<T> {
  const key = cacheKey(endpoint, params);
  const ttl = CACHE_TTLS[endpoint] ?? 15 * 60 * 1000;
  const cached = cache.get(key);

  if (cached && Date.now() - cached.at < ttl) return cached.data;

  const data = await requestFn();
  cache.set(key, { data, at: Date.now() });
  return data;
}

export function getCacheStats() {
  return { entries: cache.size, sizeBytes: cache.calculatedSize };
}

Step 3: Use Bulk Endpoints Over Single Calls

Apollo's bulk enrichment endpoint handles 10 records per call vs 1. Massive performance gain.

// src/apollo/bulk-ops.ts
import { optimizedClient } from './optimized-client';
import PQueue from 'p-queue';

const queue = ne

Apollo Production Checklist

Overview

Comprehensive pre-production checklist for Apollo.io integrations with automated validation scripts. Covers authentication, resilience, observability, compliance, and credit management.

Prerequisites

• Valid Apollo.io API credentials
• Node.js 18+
• Completed apollo-install-auth setup

Instructions

Step 1: Authentication & Key Management

// src/scripts/prod-checklist.ts
import axios from 'axios';

interface Check { category: string; name: string; pass: boolean; detail: string; }
const results: Check[] = [];

// 1.1 API key is set (not hardcoded)
results.push({
  category: 'Auth', name: 'API key from env/secrets',
  pass: !!process.env.APOLLO_API_KEY,
  detail: process.env.APOLLO_API_KEY ? 'Loaded from env' : 'NOT SET',
});

// 1.2 Using x-api-key header (not query param)
const { execSync } = await import('child_process');
let usesHeader = true;
try { execSync('grep -rn "params.*api_key" src/ --include="*.ts"', { stdio: 'pipe' }); usesHeader = false; } catch {}
results.push({ category: 'Auth', name: 'x-api-key header auth', pass: usesHeader, detail: usesHeader ? 'OK' : 'Switch to x-api-key header' });

// 1.3 API key is valid
try {
  const resp = await axios.get('https://api.apollo.io/api/v1/auth/health', {
    headers: { 'x-api-key': process.env.APOLLO_API_KEY! },
  });
  results.push({ category: 'Auth', name: 'Key valid', pass: resp.data.is_logged_in, detail: resp.data.is_logged_in ? 'OK' : 'Invalid key' });
} catch (err: any) {
  results.push({ category: 'Auth', name: 'Key valid', pass: false, detail: `HTTP ${err.response?.status}` });
}

// 1.4 .env gitignored
const gitIgnored = execSync('git check-ignore .env 2>/dev/null || echo NOT').toString().trim();
results.push({ category: 'Auth', name: '.env gitignored', pass: gitIgnored !== 'NOT', detail: gitIgnored !== 'NOT' ? 'OK' : 'Add .env to .gitignore' });

Step 2: Resilience & Error Handling

async function fileContains(dir: string, pattern: string): Promise<boolean> {
  try { execSync(`grep -r "${pattern}" ${dir} --include="*.ts" -l`, { stdio: 'pipe' }); return true; }
  catch { return false; }
}

results.push({ category: 'Resilience', name: 'Rate limiting',
  pass: await fileContains('src/', 'rate-limiter\\|SlidingWindow\\|RateLimit'),
  detail: 'Rate limiter implementation' });

results.push({ category: 'Resilience', name: 'Retry logic',
  pass: await fileContains('src/', 'withRetry\\|withBackoff\\|exponential'),
  detail: &#

Apollo Rate Limits

Overview

Implement robust rate limiting and backoff for the Apollo.io API. Apollo uses fixed-window rate limiting with per-endpoint limits. Unlike hourly quotas, Apollo limits are per minute with a burst limit per second. Exceeding them returns HTTP 429.

Prerequisites

• Valid Apollo API key
• Node.js 18+

Instructions

Step 1: Understand Apollo's Rate Limit Structure

Apollo's official rate limits (as of 2025):

Endpoint Category           | Limit/min | Burst/sec | Notes
----------------------------+-----------+-----------+-------------------------------
People Search               | 100       | 10        | /mixed_people/api_search (free)
People Enrichment           | 100       | 10        | /people/match (1 credit each)
Bulk People Enrichment      | 10        | 2         | /people/bulk_match (up to 10/call)
Organization Search         | 100       | 10        | /mixed_companies/search
Organization Enrichment     | 100       | 10        | /organizations/enrich
Contacts CRUD               | 100       | 10        | /contacts/*
Sequences                   | 100       | 10        | /emailer_campaigns/*
Deals                       | 100       | 10        | /opportunities/*

Response headers on every successful call:

• x-rate-limit-limit — max requests per window
• x-rate-limit-remaining — requests remaining in current window
• retry-after — seconds to wait (only on 429 responses)

Step 2: Build a Per-Endpoint Rate Limiter

// src/apollo/rate-limiter.ts
export class SlidingWindowLimiter {
  private timestamps: number[] = [];

  constructor(
    private maxRequests: number = 100,
    private windowMs: number = 60_000,
  ) {}

  async acquire(): Promise<void> {
    const now = Date.now();
    // Remove timestamps outside the window
    this.timestamps = this.timestamps.filter((t) => now - t < this.windowMs);

    if (this.timestamps.length >= this.maxRequests) {
      const oldestInWindow = this.timestamps[0];
      const waitMs = this.windowMs - (now - oldestInWindow) + 100;
      console.warn(`[RateLimit] At capacity (${this.maxRequests}/${this.windowMs}ms). Waiting ${waitMs}ms`);
      await new Promise((r) => setTimeout(r, waitMs));
    }

    this.timestamps.push(Date.now());
  }

  get remaining(): number {
    const now = Date.now();
    this.timestamps = this.timestamps.filter((t) => now - t < this.windowMs);
    return this.maxRequests - this.timestamps.length;
  }
}

// Create limiters per endpoint category
export const limiters = {
  search: new SlidingWindowLimiter(100, 60_000),
  enrichment: new SlidingWindowLimiter(100, 60_000),
  bulkEnrichment: new SlidingWindowLimiter(10, 60_000),
  contacts: new SlidingWindowLimiter(100, 60_000),
  s

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

// src/services/lead-service.ts
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.

// src/services/deal-service.ts
export class DealService {
  private client = getApolloClient();

Apollo SDK Patterns

Overview

Production-ready patterns for Apollo.io API integration. Apollo has no official SDK — these patterns wrap the REST API (https://api.apollo.io/api/v1/) with type safety, retry logic, pagination, and bulk operations. All requests use the x-api-key header.

Prerequisites

• Completed apollo-install-auth setup
• TypeScript 5+ with strict mode

Instructions

Step 1: Type-Safe Client with Zod Validation

// src/apollo/client.ts
import axios, { AxiosInstance } from 'axios';
import { z } from 'zod';

const ConfigSchema = z.object({
  apiKey: z.string().min(10, 'API key too short'),
  baseURL: z.string().url().default('https://api.apollo.io/api/v1'),
  timeout: z.number().default(30_000),
});

let instance: AxiosInstance | null = null;

export function getApolloClient(config?: Partial<z.input<typeof ConfigSchema>>): AxiosInstance {
  if (instance) return instance;

  const parsed = ConfigSchema.parse({
    apiKey: config?.apiKey ?? process.env.APOLLO_API_KEY,
    ...config,
  });

  instance = axios.create({
    baseURL: parsed.baseURL,
    timeout: parsed.timeout,
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': parsed.apiKey,
    },
  });

  return instance;
}

// Reset for testing
export function resetClient() { instance = null; }

Step 2: Custom Error Classes

// src/apollo/errors.ts
import { AxiosError } from 'axios';

export class ApolloApiError extends Error {
  constructor(
    message: string,
    public statusCode: number,
    public endpoint: string,
    public retryable: boolean,
    public requestId?: string,
  ) {
    super(message);
    this.name = 'ApolloApiError';
  }

  static fromAxios(err: AxiosError): ApolloApiError {
    const status = err.response?.status ?? 0;
    const body = err.response?.data as any;
    return new ApolloApiError(
      body?.message ?? err.message,
      status,
      err.config?.url ?? 'unknown',
      [429, 500, 502, 503, 504].includes(status),
      err.response?.headers?.['x-request-id'],
    );
  }
}

export class ApolloRateLimitError extends ApolloApiError {
  constructor(
    public retryAfterMs: number,
    endpoint: string,
  ) {
    super(`Rate limited on ${endpoint}`, 429, endpoint, true);
    this.name = 'ApolloRateLimitError';
  }
}

Step 3: Retry with Exponential Backoff

// src/apollo/retry.ts
import { ApolloApiError } from './errors';

export async function withRetry<T>(
  fn: () => Promise<T>,
  opts: { maxRetries?: number; baseMs?: number; maxMs?: number } = {},
): Promise<T> {
  const { maxRetries = 3, baseMs = 1000, maxMs = 30_000 } = opts;

  for (

Apollo Security Basics

Overview

Security best practices for Apollo.io API integrations. Apollo API keys grant broad access to 275M+ contacts — a leaked key is a serious incident. This covers key management, PII redaction, data access controls, key rotation, and audit procedures.

Prerequisites

• Valid Apollo.io API credentials
• Node.js 18+

Instructions

Step 1: Secure API Key Storage

Apollo supports two key types with different risk profiles:

• Standard key: search + enrichment only (lower risk)
• Master key: full CRM access including delete (highest risk)

// NEVER: const API_KEY = 'abc123';  // hardcoded
// NEVER: params: { api_key: key }   // query string (logged in server access logs)

// ALWAYS: x-api-key header + env var or secret manager
import { SecretManagerServiceClient } from '@google-cloud/secret-manager';

async function getApiKey(): Promise<string> {
  // Dev/staging: environment variable
  if (process.env.APOLLO_API_KEY) return process.env.APOLLO_API_KEY;

  // Production: GCP Secret Manager
  const client = new SecretManagerServiceClient();
  const [version] = await client.accessSecretVersion({
    name: 'projects/my-project/secrets/apollo-api-key/versions/latest',
  });
  return version.payload?.data?.toString() ?? '';
}

# .gitignore — prevent accidental commits
.env
.env.local
.env.*.local
*.pem
secrets/

Step 2: PII Redaction for Logging

Apollo responses contain emails, phone numbers, and LinkedIn profiles. Never log raw responses in production.

// src/apollo/redact.ts
const PII_PATTERNS: [RegExp, string][] = [
  [/\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z]{2,}\b/gi, '[EMAIL]'],
  [/\b\+?\d{1,3}[-.\s]?\(?\d{1,4}\)?[-.\s]?\d{1,4}[-.\s]?\d{1,9}\b/g, '[PHONE]'],
  [/x-api-key[:\s]+["']?[\w-]+["']?/gi, 'x-api-key: [REDACTED]'],
  [/linkedin\.com\/in\/[^\s"',]+/gi, 'linkedin.com/in/[REDACTED]'],
];

export function redactPII(text: string): string {
  let result = text;
  for (const [pattern, replacement] of PII_PATTERNS) {
    result = result.replace(pattern, replacement);
  }
  return result;
}

// Attach as axios interceptor
client.interceptors.response.use((response) => {
  if (process.env.NODE_ENV === 'production') {
    // Never log raw Apollo response data in production
    console.log(`[Apollo] ${response.status} ${response.config.url}`);
  } else {
    console.log('[Apollo]', redactPII(JSON.stringify(response.data).slice(0, 500)));
  }
  return response;
});

Step 3: Use Minimal Key Permissions

// src/apollo/scoped-client.ts
// Use standard keys for read-only operations, master 

Apollo Upgrade Migration

Current State

!npm list axios 2>/dev/null | head -5

Overview

Plan and execute safe upgrades for Apollo.io API integrations. Apollo has made several breaking changes historically (query param auth to header auth, endpoint URL changes, new search endpoints). This covers auditing current usage, building compatibility layers, and migrating safely.

Prerequisites

• Valid Apollo API key
• Node.js 18+

Instructions

Step 1: Audit Current API Usage

// src/scripts/api-audit.ts
import { execSync } from 'child_process';

interface EndpointUsage { endpoint: string; files: string[]; status: 'current' | 'deprecated'; }

const ENDPOINT_MAP = [
  // Current endpoints
  { pattern: '/mixed_people/api_search', status: 'current' as const },
  { pattern: '/mixed_companies/search', status: 'current' as const },
  { pattern: '/people/match', status: 'current' as const },
  { pattern: '/people/bulk_match', status: 'current' as const },
  { pattern: '/organizations/enrich', status: 'current' as const },
  { pattern: '/contacts/search', status: 'current' as const },
  { pattern: '/emailer_campaigns', status: 'current' as const },
  { pattern: '/email_accounts', status: 'current' as const },
  { pattern: '/opportunities', status: 'current' as const },
  // Deprecated patterns
  { pattern: '/people/search', status: 'deprecated' as const },  // old search endpoint
  { pattern: '/organizations/search', status: 'deprecated' as const },
  { pattern: 'api_key.*=', status: 'deprecated' as const },  // query param auth
  { pattern: 'api.apollo.io/v1', status: 'deprecated' as const },  // old base URL (should be /api/v1)
];

function auditUsage(srcDir: string = 'src'): EndpointUsage[] {
  const results: EndpointUsage[] = [];
  for (const ep of ENDPOINT_MAP) {
    try {
      const files = execSync(
        `grep -rl "${ep.pattern}" ${srcDir} --include="*.ts" --include="*.js" 2>/dev/null`,
        { encoding: 'utf-8' },
      ).trim().split('\n').filter(Boolean);
      if (files.length > 0) results.push({ endpoint: ep.pattern, files, status: ep.status });
    } catch { /* no matches */ }
  }

  console.log('=== Apollo API Usage Audit ===');
  for (const r of results) {
    const icon = r.status === 'deprecated' ? 'WARN' : 'OK';
    console.log(`${icon} ${r.endpoint} (${r.files.length} files)`);
    r.files.forEach((f) => console.log(`     ${f}`));
  }
  const deprecated = results.filter((r) => r.status === 'deprecated');
  if (deprecated.length > 0) {
    console.log(`\n${deprecated.le

Apollo Webhooks & Events

Overview

Build event-driven integrations with Apollo.io. Apollo does not have a native webhook system like Stripe — instead, you build real-time sync by polling the API for changes or using third-party webhook platforms (Zapier, Pipedream, Make) that trigger on Apollo events. This skill covers both approaches plus the Contact Stages and Tasks APIs for workflow automation.

Prerequisites

• Apollo account with master API key
• Node.js 18+ with Express
• For polling: a scheduler (cron, Cloud Scheduler, BullMQ)
• For webhook platforms: Zapier/Pipedream/Make account

Instructions

Step 1: Poll for Contact Changes

Since Apollo lacks native webhooks, poll the Contacts Search API for recently updated records.

// src/sync/contact-poller.ts
import axios from 'axios';

const client = axios.create({
  baseURL: 'https://api.apollo.io/api/v1',
  headers: { 'Content-Type': 'application/json', 'x-api-key': process.env.APOLLO_API_KEY! },
});

interface SyncState {
  lastSyncAt: string;  // ISO timestamp
}

export async function pollContactChanges(state: SyncState) {
  const { data } = await client.post('/contacts/search', {
    sort_by_field: 'contact_updated_at',
    sort_ascending: false,
    per_page: 100,
  });

  const lastSync = new Date(state.lastSyncAt);
  const newChanges = data.contacts.filter(
    (c: any) => new Date(c.updated_at) > lastSync,
  );

  // A full page is not a complete incremental window. Paginate before moving
  // the watermark so newer changes cannot hide records still on later pages.
  if (data.contacts.length >= 100) {
    throw new Error('Incremental window reached one page; paginate before advancing sync state');
  }

  if (newChanges.length > 0) {
    console.log(`Found ${newChanges.length} contact changes since ${state.lastSyncAt}`);
    for (const contact of newChanges) {
      await handleContactChange(contact);
    }
    state.lastSyncAt = newChanges
      .map((c: any) => c.updated_at)
      .sort()
      .at(-1) ?? state.lastSyncAt;
  }

  return newChanges;
}

async function handleContactChange(contact: any) {
  console.log(`Contact updated: ${contact.id} — stage: ${contact.contact_stage_id}`);
  // Sync to your CRM, database, or notification system
}

Step 2: Track Contact Stage Changes

Apollo has a Contact Stages system. Use the List Contact Stages endpoint to get stage IDs, then filter contacts by stage.

// src/sync/stage-tracker.ts
export async function getContactStages() {
  const { data } = await client.get('/contact_stages');
  return data.contact_stages.map((s: any) => ({
    id: s.id,
    name: s.name,
    order: s.display_order,
  }));
}

// Find contacts that moved to a s