Apollo.io

Apollo.io is used for company-level enrichment across both the attorney intelligence pipeline (law firms) and the internal sales pipeline (prospect companies). It provides organizational data like employee count, founding year, industry, revenue, and LinkedIn URLs.

API Configuration

Setting	Value
API Base URL	https://api.apollo.io/v1
Auth Header	X-Api-Key: {APOLLO_API_KEY}
Env Variable	APOLLO_API_KEY (Supabase secret)

Edge Functions

apollo-org-search

Purpose: Search for companies by name or domain. Returns matching organizations for selection before enrichment.

Request

{
  "name": "Kirkland & Ellis",
  "domain": "kirkland.com"
}

At least one of name or domain is required.

API Call

const searchParams = {
  page: 1,
  per_page: 10,
};
if (domain) searchParams.organization_domains = [domain];
if (name) searchParams.q_organization_name = name;

const response = await fetch("https://api.apollo.io/v1/mixed_companies/search", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Api-Key": APOLLO_API_KEY,
  },
  body: JSON.stringify(searchParams),
});

Response

{
  "success": true,
  "accounts": [...],
  "organizations": [...],
  "pagination": { "page": 1, "per_page": 10, "total_entries": 3 }
}

apollo-enrich-company

Purpose: Enrich a law firm record in the firms table using Apollo's organization enrichment endpoint.

Request

{
  "domain": "kirkland.com",
  "firmId": "uuid (optional -- updates existing firm)"
}

API Call

const response = await fetch("https://api.apollo.io/v1/organizations/enrich", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Api-Key": APOLLO_API_KEY,
  },
  body: JSON.stringify({ domain }),
});

Fields Mapped to firms Table

Apollo Field	Firms Column	Description
linkedin_url	linkedin_url	Company LinkedIn page
logo_url	logo_url	Company logo image URL
short_description	description	Brief company description
estimated_num_employees	employee_count	Total employee count
founded_year	founded_year	Year company was founded
city	headquarters_city	HQ city
state	headquarters_state	HQ state
country	headquarters_country	HQ country
industry	industry	Industry classification
annual_revenue_printed	revenue_range	Revenue range string
id	apollo_org_id	Apollo organization ID

Behavior

• If firmId is provided: updates the existing firm record (preserves name, tier, domain).
• If only domain is provided: upserts by website (legacy behavior for new firms).
• Sets enrichment_status = 'complete' and last_enriched_at on success.
• Sets enrichment_status = 'failed' or 'not_found' on failure.

apollo-enrich-sales-company

Purpose: Enrich a sales prospect's company in the sales_companies table. Same Apollo API, different destination table.

Request

{
  "companyId": "uuid (optional -- enriches and saves)",
  "domain": "smithlegal.com (for direct lookups)"
}

Fields Mapped to sales_companies Table

Apollo Field	Sales Companies Column
linkedin_url	linkedin_url
logo_url	logo_url
short_description	description
estimated_num_employees	employee_count
founded_year	founded_year
city	headquarters_city
state	headquarters_state
country	headquarters_country
industry	industry
annual_revenue_printed	revenue_range
id	apollo_org_id

Behavior

• If companyId is provided: fetches the company from sales_companies, extracts domain from website or domain field, enriches, and updates the record.
• If only domain is provided: returns enriched data without saving (for preview/search).
• Also backfills name and website from Apollo if local data is sparse.

apollo-search-firm-attorneys

Purpose: Discover attorneys at a law firm using Apollo's people search. This is an alternative to Blitz API's employee-finder that works when the firm has an apollo_org_id.

Request

{
  "firmId": "uuid",
  "maxResults": 100
}

Prerequisites

The firm must have an apollo_org_id (set by apollo-enrich-company). If missing, the function returns an error instructing you to enrich the company first.

API Call

const response = await fetch("https://api.apollo.io/v1/mixed_people/search", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Api-Key": APOLLO_API_KEY,
  },
  body: JSON.stringify({
    organization_ids: [firm.apollo_org_id],
    person_titles: [
      "Partner", "Equity Partner", "Managing Partner", "Senior Partner",
      "Counsel", "Of Counsel", "Senior Counsel", "Special Counsel",
      "Senior Associate", "Associate", "Attorney", "Lawyer",
    ],
    person_locations: ["United States"],
    page: 1,
    per_page: Math.min(maxResults, 100),
  }),
});

Output

Discovered attorneys are upserted into the attorneys table with enrichment_status: 'linkedin_only'. They have LinkedIn URLs and basic info but no email or phone -- those require Blitz API enrichment as a second step.

{
  "success": true,
  "count": 47,
  "message": "Discovered 47 attorneys. Use blitz-enrich-attorney-contacts to get email/phone."
}

Data Flow

Apollo vs Blitz: When to Use Which

Need	Use
Company enrichment (firm or prospect)	Apollo (apollo-enrich-company, apollo-enrich-sales-company)
Attorney discovery at a firm	Blitz (primary) or Apollo (alternative)
Attorney email lookup	Blitz (/v2/enrichment/email) -- Apollo does not provide this
Attorney phone lookup	Blitz (/v2/enrichment/phone) -- Apollo does not provide this
Company search by name/domain	Apollo (apollo-org-search)

The typical workflow is:

1. Enrich firm with Apollo (get apollo_org_id, company data)
2. Discover attorneys with Blitz employee-finder (or Apollo people search)
3. Enrich attorney contacts with Blitz email + phone endpoints

Error Handling

HTTP Status	Meaning
200	Success
400	Missing required parameters
401	Invalid API key
404	No organization found for domain
429	Rate limited
500	Apollo server error

On failure, the enrichment status is set to 'failed' on the company record for visibility in the UI.

Related Documentation

• Blitz API Reference -- Attorney-level email and phone enrichment
• Enrichment Pipeline -- Full enrichment workflow combining Apollo and Blitz