CallRail Integration

🎯 Overview

CallRail integration enables DashClicks to track marketing campaign phone calls, access call recordings, and manage tracking phone numbers. This integration provides multi-channel call attribution to measure advertising campaign performance and optimize marketing spend.

Provider: CallRail (https://www.callrail.com)
API Version: v3
Integration Type: REST API with API Key authentication

📁 Directory Structure

Documentation Structure:

callrail/
├── 📄 index.md - Integration overview and setup
├── 📄 authentication.md - API key management and token storage
├── 📄 accounts-companies.md - Account and company management
├── 📄 calls.md - Call tracking, recordings, and analytics
└── 📄 trackers.md - Phone number tracker management

Source Code Location:

Base Path: external/Integrations/Callrail/
Controllers: Controllers/auth.js, Controllers/accounts.js, Controllers/companies.js, Controllers/calls.js, Controllers/trackers.js
Providers: Providers/account-api.js, Providers/companies-api.js, Providers/calls-api.js, Providers/trackers-api.js
Models: Models/keys.js
Routes: Routes/auth.js, Routes/accounts.js, Routes/companies.js, Routes/calls.js, Routes/trackers.js

🗄️ MongoDB Collections

📚 Detailed Schema: See Database Collections Documentation

`integrations.callrail.key`

Purpose: Store CallRail API keys per account
Model: shared/models/callrail-key.js
Primary Use: Store API authentication credentials

Document Structure:

{
  "_id": ObjectId,
  "account_id": ObjectId,
  "api_key": "dfc7f89eaa8a9b4f0acbcd850a60a444",
  "nickname": "Production CallRail Key",
  "token_invalidated": false,  // Set to true when API key becomes invalid
  "deleted": ISODate,  // Soft delete timestamp
  "createdAt": ISODate,
  "updatedAt": ISODate
}

`analytics.callrail.userconfig`

Purpose: Store user-specific CallRail configuration for analytics
Model: shared/models/analytics-callrail-userconfig.js
Primary Use: Link CallRail account/company to DashClicks account for campaign tracking

Document Structure:

{
  "_id": ObjectId,
  "account_id": ObjectId,
  "token": "callrail_key_doc_id",
  "callrail_acountid": "470306151",    // CallRail account ID
  "callrail_companyid": "com_abc123", // CallRail company ID
  "createdAt": ISODate,
  "updatedAt": ISODate
}

🔐 Authentication & Configuration

Authentication Method: API Key (Bearer Token)

Required Environment Variables:

Variable	Description	Required
None	API keys stored in database per account	N/A

API Key Structure:

Format: 32-character hexadecimal string
Example: dfc7f89eaa8a9b4f0acbcd850a60a444
Header: Authorization: Token token="YOUR_API_KEY"

Obtaining API Keys:

Sign up at CallRail Dashboard
Navigate to Settings → API Keys
Generate new API key
Store key in DashClicks via /v1/e/callrail/auth endpoint

🏗️ Architecture Overview

Key Responsibilities:

API key management and storage
Account and company listing
Call tracking and analytics
Call recording access
Phone number tracker management (session and source trackers)
Webhook integration for real-time call events

API Communication Pattern:

REST API with JSON responses
Token-based authentication (Bearer header)
Supports pagination, sorting, filtering, searching
All requests proxied through DashClicks API with token lookup

Token Invalidation Handling:

Automatic detection of 401 errors
Sets token_invalidated: true on API key documents
Requires re-authentication via dashboard

🔗 Features & Capabilities

Core Features

📘 Authentication - API key storage and management
📗 Accounts & Companies - Account/company listing and management
📙 Call Tracking - Call history, recordings, and analytics
📕 Trackers - Phone number tracker management

🔄 Integration Data Flow

API Key Flow

sequenceDiagram
    participant Client as DashClicks Frontend
    participant API as CallRail Controller
    participant DB as MongoDB (callrail.key)
    participant CallRail as CallRail API

    Client->>API: POST /v1/e/callrail/auth {api_key, nickname}
    API->>DB: Check existing key for account

    alt Key exists and valid
        DB-->>API: Return existing key
        API-->>Client: Return key document
    else Key invalidated
        API->>DB: Delete invalidated key
        API->>DB: Save new key
        DB-->>API: New key document
        API-->>Client: Return new key
    else No key
        API->>DB: Save new key
        DB-->>API: Key document
        API-->>Client: Return key
    end

Call Data Request Flow

sequenceDiagram
    participant Client as API Consumer
    participant API as CallRail Controller
    participant KeysDB as MongoDB (callrail.key)
    participant Provider as CallRail Provider
    participant CallRail as CallRail API

    Client->>API: GET /v1/e/callrail/{tokenId}/accounts/{accountId}/companies/{companyId}/calls
    API->>KeysDB: Find API key by tokenId
    KeysDB-->>API: Return API key document

    API->>Provider: callList(apiKey, accountId, companyId, query)
    Provider->>CallRail: GET /v3/a/{accountId}/calls.json
    CallRail-->>Provider: Call data + pagination
    Provider-->>API: Formatted response

    API-->>Client: {data, pagination}

🔗 API Endpoints

Authentication

Endpoint	Method	Description
`/v1/e/callrail/auth`	POST	Save API key
`/v1/e/callrail/auth`	DELETE	Delete API key (soft delete)
`/v1/e/callrail/auth/config`	POST	Save user analytics config

Accounts

Endpoint	Method	Description
`/v1/e/callrail/{tokenId}/accounts`	GET	List all accounts
`/v1/e/callrail/{tokenId}/accounts/{accountId}`	GET	Get account by ID

Companies

Endpoint	Method	Description
`/v1/e/callrail/{tokenId}/accounts/{accountId}/companies`	GET	List companies
`/v1/e/callrail/{tokenId}/accounts/{accountId}/companies/{companyId}`	GET	Get company by ID
`/v1/e/callrail/{tokenId}/accounts/{accountId}/companies`	POST	Create company
`/v1/e/callrail/{tokenId}/accounts/{accountId}/companies/{companyId}`	PUT	Update company
`/v1/e/callrail/{tokenId}/accounts/{accountId}/companies/{companyId}`	DELETE	Delete/disable company
`/v1/e/callrail/{tokenId}/accounts/{accountId}/companies/{companyId}/webhook`	POST	Create webhook

Calls

Endpoint	Method	Description	Query Parameters
`/v1/e/callrail/{tokenId}/accounts/{accountId}/companies/{companyId}/calls`	GET	List calls	`page`, `limit`, filters
`/v1/e/callrail/{tokenId}/accounts/{accountId}/companies/{companyId}/calls/summary`	GET	Calls summary	`group_by`, filters
`/v1/e/callrail/{tokenId}/accounts/{accountId}/companies/{companyId}/calls/timeline`	GET	Calls timeline	`group_by`, filters
`/v1/e/callrail/{tokenId}/accounts/{accountId}/calls/{callId}/recording`	GET	Get recording URL	None

Trackers

Endpoint	Method	Description
`/v1/e/callrail/{tokenId}/accounts/{accountId}/companies/{companyId}/trackers`	GET	List trackers
`/v1/e/callrail/{tokenId}/accounts/{accountId}/companies/{companyId}/trackers/{trackerId}`	GET	Get tracker by ID
`/v1/e/callrail/{tokenId}/accounts/{accountId}/companies/{companyId}/trackers`	POST	Create tracker
`/v1/e/callrail/{tokenId}/accounts/{accountId}/companies/{companyId}/trackers/{trackerId}`	PUT	Update tracker
`/v1/e/callrail/{tokenId}/accounts/{accountId}/companies/{companyId}/trackers/{trackerId}`	DELETE	Delete tracker

🚨 Error Handling

Common Error Scenarios:

Invalid API Key (401 Unauthorized):
- Automatically sets token_invalidated: true
- Returns error message: TOKEN_INVALIDATED
- User must re-authenticate
Missing Token ID (403 Forbidden):
- Returns INVALID_TOKEN when token not found in database
Invalid Account ID:
- Returns 400 with INVALID_ACCOUNT_ID message
CallRail API Errors:
- Proxied from CallRail with original status code
- Error details from CallRail response data

Error Response Format:

{
  "success": false,
  "errno": 400,
  "message": "Error description"
}

📊 Monitoring & Logging

Token Invalidation Tracking:

401 errors automatically update token_invalidated flag
Logged with initiator: external/callrail
All account keys marked invalid simultaneously

Campaign Integration:

Soft delete preserves keys if campaigns exist
Hard delete only when no active campaigns
Notifications sent on disconnect (email, bell, browser)

Provider API Docs: CallRail API v3 Documentation
Authentication: ./authentication.md
Accounts & Companies: ./accounts-companies.md
Call Tracking: ./calls.md
Trackers: ./trackers.md

⚠️ Important Notes

🔐 API Key Storage: Keys stored per account in MongoDB, not environment variables
🔄 Token Invalidation: Automatic detection on 401 errors
🗑️ Soft Delete: Keys marked as deleted but not removed if campaigns exist
📞 Company Scoped: Most operations require company ID
📊 Campaign Integration: CallRail integrated with DashClicks campaign analytics
🔔 Notifications: Email and in-app notifications on integration connect/disconnect
🎯 Pagination Support: All list endpoints support pagination, sorting, filtering
🪝 Webhooks: Real-time call event notifications via webhook integration

🎛️ CallRail Concepts

Account Hierarchy

Top-level entity in CallRail hierarchy
One account can have multiple companies
Account ID format: 470306151 (numeric string)

Company Structure

Sub-entity under accounts
Represents a business or client
Company ID format: com_abc123
Contains call trackers and call data

Tracking Numbers

Phone numbers for call tracking
Two types:
- Session Trackers: Dynamic number insertion based on visitor session
- Source Trackers: Static numbers for specific marketing channels
Track marketing source attribution

Call Records

Individual phone call records
Contains caller ID, duration, recording URL, source attribution
Supports filtering by date range, source, keywords
Summary and timeline analytics available

🎯 Overview​

📁 Directory Structure​

🗄️ MongoDB Collections​

integrations.callrail.key​

analytics.callrail.userconfig​

🔐 Authentication & Configuration​

🏗️ Architecture Overview​

🔗 Features & Capabilities​

Core Features​

🔄 Integration Data Flow​

API Key Flow​

Call Data Request Flow​

🔗 API Endpoints​

Authentication​

Accounts​

Companies​

Calls​

Trackers​

🚨 Error Handling​

📊 Monitoring & Logging​

🔗 Related Documentation​

⚠️ Important Notes​

🎛️ CallRail Concepts​

Account Hierarchy​

Company Structure​

Tracking Numbers​

Call Records​

Documentation Assistant