Fathom.video Connector

The Fathom.video connector ingests meeting recordings, transcripts, participant lists, and summaries from Fathom's API. Meeting data is stored for future validation and analysis, but is explicitly excluded from the scoring engine in the current phase.

Ingest-only connector

Fathom data is stored but not scored. The meeting_recorded activity type is intentionally not mapped in the scoring engine's CHANNEL_MAP. Scoring integration is planned for Phase 5+.

Prerequisites

Before connecting Fathom.video, you need:

1. A Fathom.video account with API access
2. An API key generated from the Fathom dashboard
3. The environment variables listed below

Environment Variables

Variable	Description
CONNECTOR_ENCRYPTION_KEY	32-byte hex string (64 hex chars) for AES-256-GCM API key encryption

Connector Settings (stored per-tenant)

Setting	Description
encryptedApiKey	AES-256-GCM encrypted Fathom API key

Authentication

Fathom uses Bearer token authentication. The API key is encrypted at rest using AES-256-GCM and validated against the Fathom user endpoint (https://api.fathom.video/v1/user). Keys do not expire.

Data Flow

Dual Storage Model

Each Fathom meeting produces two records stored in separate tables:

Record	Table	Contents
CanonicalActivity	activities	Lightweight metadata (ID, timestamp, participant count, duration)
FathomMeetingRecord	fathom_meetings	Full transcript, participant list, summary, sentiment score

This separation keeps the activities table lean for scoring queries while preserving rich meeting data for future ML analysis.

CanonicalActivity Fields

{
  externalId: "fathom_{meetingId}",
  type: "meeting_recorded",
  channel: "video",
  occurredAt: createdAt,
  personExternalId: firstParticipantEmail,
  properties: {
    source: "fathom",
    fathomMeetingId: "mtg_abc123",
    participantCount: 4,
    durationSeconds: 3600,
  }
}

FathomMeetingRecord Fields

Field	Type	Description
fathomMeetingId	string	Fathom's meeting identifier
title	string?	Meeting title
startedAt	Date?	Meeting start time
endedAt	Date?	Calculated from startedAt + durationSeconds
participantsJson	FathomParticipant[]?	Array of { name, email?, role? }
transcriptJson	FathomTranscriptSegment[]?	Array of { speaker, text, startTime, endTime }
summaryText	string?	AI-generated meeting summary
sentimentScore	string?	Null until Phase 5+ ML integration

Sync Pipeline

API Pull

Parameter	Value
Base URL	https://api.fathom.video/v1
Endpoint	/meetings?since={iso}&limit=50
Auth header	Authorization: Bearer {apiKey}
Page size	50 meetings per request
Pagination	Supports both next URL and next_cursor response fields
Backfill window	90 days on initial sync

Rate Limiting

Fathom enforces a strict 60 requests per minute rate limit. The connector implements robust rate limiting:

Mechanism	Detail
Request pacing	1,200ms minimum between requests (~50 req/min)
429 handling	Exponential backoff: 1s, 2s, 4s, 8s, 16s
Retry-After header	Respected when present (overrides backoff)
Max retries	5 consecutive 429s before failing

Conservative pacing

The connector targets 50 requests per minute to maintain a safety margin below the 60 req/min limit. This is deliberate -- exceeding the limit risks API key suspension.

Zod-Validated Responses

API responses are parsed through Zod schemas for resilience against API changes:

• FathomApiMeetingSchema -- validates meeting structure with .passthrough() for forward compatibility
• FathomApiParticipantSchema -- validates participant fields
• FathomApiTranscriptSegmentSchema -- validates transcript segments
• FathomMeetingsResponseSchema -- handles both meetings and data response shapes

Participant Extraction

The connector extracts participants from each meeting and stores them in the fathom_meetings table:

interface FathomParticipant {
  name: string;
  email?: string;
  role?: string;   // e.g., "host", "guest"
}

The first participant with an email address is used as the personExternalId on the CanonicalActivity record, linking the meeting to a person in the scoring database.

Default Field Mappings

Source Field	Target Field	Transform	Required
id	externalId	none	Yes
title	properties.title	none	No
created_at	occurredAt	none	Yes
duration_seconds	properties.durationSeconds	none	No
participants[0].email	personExternalId	lowercase	No
participants[0].name	properties.participantName	none	No
summary	properties.summary	none	No

Scoring Exclusion

The meeting_recorded type is deliberately excluded from the scoring engine's CHANNEL_MAP. This means:

• Fathom activities are stored in the database but produce zero engagement score
• No fit score impact from meeting data
• Scoring integration is deferred to Phase 5+ when ML propensity models can leverage transcript sentiment analysis

Future plans

Phase 5 will introduce ML-based sentiment analysis of meeting transcripts. The sentimentScore field on FathomMeetingRecord is already provisioned (currently null) for this purpose. Transcript data will be used to train propensity models rather than directly contribute to engagement scores.

Setup Steps

1. Generate an API key from the Fathom.video dashboard
2. Navigate to Settings > Connectors in the GTM Clarity dashboard
3. Click "Connect Fathom.video" and paste your API key (encrypted at rest)
4. Trigger initial sync to backfill 90 days of meeting recordings
5. Verify data by checking the fathom_meetings table for transcript content

Health Check

The health check validates the API key against the Fathom user endpoint (GET /v1/user). A 200 response confirms the connector is operational.

Limitations

Limitation	Detail
No scoring impact	meeting_recorded is not in CHANNEL_MAP -- data is ingest-only
Rate limits	60 req/min hard limit means large backlogs sync slowly
Participant emails	Not all participants have email addresses -- anonymous participants are stored but cannot be linked to persons
Transcript availability	Not all meetings have transcripts (depends on Fathom recording settings)
Sentiment analysis	sentimentScore is null until Phase 5+ ML pipeline

Troubleshooting

Issue	Cause	Resolution
Auth fails with 401	Invalid API key	Generate a new key from the Fathom dashboard
Rate limit errors (429)	Too many requests	The connector handles this automatically with backoff; persistent failures indicate a key-level rate limit
Empty transcripts	Recording not processed	Fathom may still be processing -- retry sync later
Missing participants	No attendee data in Fathom	Check Fathom recording settings for participant capture
No scoring impact	Expected behavior	meeting_recorded is excluded from scoring by design