CallRail - Trackers

📖 Overview

CallRail trackers are phone numbers that track and attribute incoming calls to marketing campaigns. There are two types: Session Trackers (dynamic number insertion for web visitors) and Source Trackers (static numbers for specific marketing channels). This module manages tracker CRUD operations, configuration, and phone number pool management.

Source Files:

Controller: external/Integrations/Callrail/Controllers/trackers.js
Provider: external/Integrations/Callrail/Providers/trackers-api.js
Routes: external/Integrations/Callrail/Routes/trackers.js

External APIs:

CallRail API v3 - /trackers

🗄️ Collections Used

`integrations.callrail.key`

Operations: Read
Usage: Retrieve API key for authentication
See Authentication for full schema

🔄 Data Flow

Tracker Listing Flow

sequenceDiagram
    participant Client as DashClicks Frontend
    participant Controller as Trackers Controller
    participant Provider as Trackers API Provider
    participant CallRail as CallRail API v3
    participant KeysDB as MongoDB (keys)

    Client->>Controller: GET /v1/e/callrail/trackers?company_id=com_abc123
    Controller->>KeysDB: Find API key for account
    KeysDB-->>Controller: Return api_key

    Controller->>Provider: getTrackerList(api_key, accountId, companyId, params)
    Provider->>CallRail: GET /v3/a/{account}/trackers.json
    CallRail-->>Provider: Tracker list with pagination

    Provider-->>Controller: Formatted tracker data
    Controller-->>Client: {trackers: [...], pagination: {...}}

Tracker Creation Flow

sequenceDiagram
    participant Client as DashClicks Frontend
    participant Controller as Trackers Controller
    participant Provider as Trackers API Provider
    participant CallRail as CallRail API v3
    participant KeysDB as MongoDB (keys)

    Client->>Controller: POST /v1/e/callrail/trackers {type, name, ...}
    Controller->>KeysDB: Find API key for account
    KeysDB-->>Controller: Return api_key

    Controller->>Provider: postTracker(api_key, accountId, body)
    Provider->>CallRail: POST /v3/a/{account}/trackers.json
    CallRail-->>Provider: Tracker created with phone number

    Provider-->>Controller: Tracker details
    Controller-->>Client: {success: true, data: tracker}

🔧 Business Logic & Functions

Tracker Listing Functions

`getTrackersList(req, res, next)`

Purpose: Retrieve paginated list of trackers for a company

Source: Controllers/trackers.js

External API: GET https://api.callrail.com/v3/a/{account_id}/trackers.json

Authentication: Token authentication (API key)

Parameters:

req.callrailAccountId (String, required) - CallRail account ID (from middleware)
req.callrailCompanyId (String, required) - CallRail company ID (from middleware)
req.query.page (Number, optional) - Page number (default: 1)
req.query.per_page (Number, optional) - Results per page (default: 10, max: 250)
req.query.sort (String, optional) - Sort field
req.query.fields (String, optional) - Field selection (comma-separated)
req.query.search (String, optional) - Search by tracker name
req.tokenId (ObjectId) - CallRail key document ID (from middleware)
req.auth.account_id (ObjectId) - DashClicks account ID

Returns: JSON response with trackers array and pagination

{
  "success": true,
  "message": "SUCCESS",
  "data": {
    "trackers": [
      {
        "id": "trk_12345",
        "name": "Google Ads Campaign",
        "type": "source",
        "tracking_number": "+15559876543",
        "status": "active",
        "company_id": "com_abc123"
      }
    ],
    "total_records": 25,
    "page": 1,
    "per_page": 10
  },
  "pagination": {
    "current_page": 1,
    "total_pages": 3,
    "per_page": 10,
    "total_items": 25
  }
}

Business Logic Flow:

Validate Account Access
- Call checkAccountAccess(req) to verify account permissions
- Return error if invalid account ID
Retrieve API Key
- Query callrail.key collection using tokenId and account_id
- Return 403 if key not found
Extract Request Parameters
- Get callrailAccountId and callrailCompanyId from request (set by middleware)
- Extract pagination parameters (page, per_page)
- Get optional filters (sort, fields, search)
Call CallRail API
- Provider makes GET request to /v3/a/{account}/trackers.json
- Pass company_id and all query parameters
- Supports CallRail pagination, sorting, filtering, field selection, searching
Format Response
- Extract trackers array and total_records
- Generate pagination metadata using utility function
- Return formatted data

Request Example:

GET /v1/e/callrail/trackers?page=1&per_page=20&sort=name&search=Google
Authorization: Bearer {jwt_token}
X-CallRail-Account-Id: 470306151
X-CallRail-Company-Id: com_abc123

Success Response:

{
  "success": true,
  "message": "SUCCESS",
  "data": {
    "trackers": [
      {
        "id": "trk_12345",
        "name": "Google Ads Campaign",
        "type": "source",
        "tracking_number": "+15559876543",
        "formatted_tracking_number": "(555) 987-6543",
        "status": "active",
        "company_id": "com_abc123",
        "created_at": "2023-09-15T10:00:00Z",
        "pool_size": 5,
        "whisper_message": null,
        "record_calls": true,
        "destination_number": "+15551234567"
      },
      {
        "id": "trk_67890",
        "name": "Facebook Ads",
        "type": "source",
        "tracking_number": "+15558765432",
        "formatted_tracking_number": "(555) 876-5432",
        "status": "active",
        "company_id": "com_abc123",
        "created_at": "2023-09-20T14:30:00Z",
        "pool_size": 1,
        "whisper_message": "Call from Facebook Ads",
        "record_calls": true,
        "destination_number": "+15551234567"
      }
    ],
    "total_records": 25,
    "page": 1,
    "per_page": 20
  },
  "pagination": {
    "current_page": 1,
    "total_pages": 2,
    "per_page": 20,
    "total_items": 25
  }
}

Error Response (Invalid Token):

{
  "success": false,
  "errno": 403,
  "message": "INVALID_TOKEN"
}

Query Parameters:

Parameter	Type	Description	Example
`page`	Number	Page number (1-based)	`1`
`per_page`	Number	Results per page (max 250)	`20`
`sort`	String	Sort field (prefix with `-` for desc)	`name`, `-created_at`
`fields`	String	Comma-separated field list	`id,name,tracking_number`
`search`	String	Search by tracker name	`Google`
`company_id`	String	Filter by company (auto-added)	`com_abc123`

Error Handling:

Invalid Account: Returns 400 with INVALID_ACCOUNT_ID
Invalid Token: Returns 403 with INVALID_TOKEN
CallRail API Error: Status code set to 400, propagated to error middleware
Missing company_id: Middleware should set this before controller

Example Usage:

// Fetch first page of trackers
const response = await fetch('/v1/e/callrail/trackers?page=1&per_page=20', {
  headers: {
    Authorization: `Bearer ${token}`,
    'X-CallRail-Account-Id': '470306151',
    'X-CallRail-Company-Id': 'com_abc123',
  },
});

const { trackers, pagination } = await response.json();

// Search for specific tracker
const searchResults = await fetch('/v1/e/callrail/trackers?search=Google&per_page=10', {
  headers: {
    Authorization: `Bearer ${token}`,
    'X-CallRail-Account-Id': '470306151',
    'X-CallRail-Company-Id': 'com_abc123',
  },
});

Side Effects:

ℹ️ Database Read: Queries API key from callrail.key
ℹ️ External API Call: CallRail API usage

`getTracker(req, res, next)`

Purpose: Retrieve details of a specific tracker by ID

Source: Controllers/trackers.js

External API: GET https://api.callrail.com/v3/a/{account_id}/trackers/{tracker_id}.json

Authentication: Token authentication (API key)

Parameters:

req.params.trackerId (String, required) - Tracker ID
req.callrailAccountId (String, required) - CallRail account ID
req.tokenId (ObjectId) - CallRail key document ID
req.auth.account_id (ObjectId) - DashClicks account ID

Returns: JSON response with tracker details

{
  "success": true,
  "message": "SUCCESS",
  "data": {
    "id": "trk_12345",
    "name": "Google Ads Campaign",
    "type": "source",
    "tracking_number": "+15559876543",
    "formatted_tracking_number": "(555) 987-6543",
    "status": "active",
    "company_id": "com_abc123",
    "destination_number": "+15551234567",
    "pool_size": 5,
    "record_calls": true,
    "whisper_message": null
  }
}

Business Logic Flow:

Validate Account Access
- Verify account permissions
Retrieve API Key
- Query database for CallRail API key
- Return 403 if not found
Extract Parameters
- Get trackerId from URL parameters
- Get callrailAccountId from request
Call CallRail API
- Provider makes GET request to /v3/a/{account}/trackers/{tracker_id}.json
Return Tracker Details
- Include all tracker configuration and metadata

Request Example:

GET /v1/e/callrail/trackers/trk_12345
Authorization: Bearer {jwt_token}
X-CallRail-Account-Id: 470306151

Success Response:

{
  "success": true,
  "message": "SUCCESS",
  "data": {
    "id": "trk_12345",
    "name": "Google Ads Campaign",
    "type": "source",
    "tracking_number": "+15559876543",
    "formatted_tracking_number": "(555) 987-6543",
    "status": "active",
    "company_id": "com_abc123",
    "destination_number": "+15551234567",
    "formatted_destination_number": "(555) 123-4567",
    "pool_size": 5,
    "record_calls": true,
    "whisper_message": null,
    "created_at": "2023-09-15T10:00:00Z",
    "updated_at": "2023-10-01T14:30:00Z",
    "sms_enabled": false,
    "tracking_type": "source",
    "call_flow": {
      "type": "direct",
      "destination": "+15551234567"
    }
  }
}

Error Response (Not Found):

{
  "success": false,
  "errno": 404,
  "message": "Tracker not found"
}

Error Handling:

Invalid Account: Returns 400 with INVALID_ACCOUNT_ID
Invalid Token: Returns 403 with INVALID_TOKEN
Tracker Not Found: CallRail returns 404 error
CallRail API Error: Status code set to 400

Example Usage:

// Get tracker details
const response = await fetch('/v1/e/callrail/trackers/trk_12345', {
  headers: {
    Authorization: `Bearer ${token}`,
    'X-CallRail-Account-Id': '470306151',
  },
});

const { data: tracker } = await response.json();
console.log(tracker.tracking_number); // "+15559876543"

Side Effects:

ℹ️ Database Read: Queries API key
ℹ️ External API Call: CallRail API usage

Tracker Creation Functions

`postTracker(req, res, next)`

Purpose: Create a new tracker (session or source tracker)

Source: Controllers/trackers.js

External API: POST https://api.callrail.com/v3/a/{account_id}/trackers.json

Authentication: Token authentication (API key)

Parameters:

req.body (Object) - Tracker configuration (see CallRail API docs)
- type (String, required) - "session" or "source"
- name (String, required) - Tracker name
- destination_number (String, required) - Forwarding number
- pool_size (Number, optional) - Number pool size (session trackers)
- whisper_message (String, optional) - Message played to agent
- record_calls (Boolean, optional) - Enable call recording
req.callrailAccountId (String, required) - CallRail account ID
req.callrailCompanyId (String, required) - CallRail company ID
req.tokenId (ObjectId) - CallRail key document ID
req.auth.account_id (ObjectId) - DashClicks account ID

Returns: JSON response with created tracker

{
  "success": true,
  "message": "SUCCESS",
  "data": {
    "id": "trk_new123",
    "name": "New Campaign Tracker",
    "type": "source",
    "tracking_number": "+15551112222",
    "status": "active",
    "company_id": "com_abc123"
  }
}

Business Logic Flow:

Validate Account Access
- Verify account permissions
Retrieve API Key
- Query database for CallRail API key
- Return 403 if not found
Build Request Body
- Copy all fields from req.body
- Add company_id from callrailCompanyId (middleware)
- Validate required fields per tracker type
Call CallRail API
- Provider makes POST request to /v3/a/{account}/trackers.json
- Pass complete tracker configuration
Return Created Tracker
- Include generated tracking_number
- Include all configuration details

Request Example (Source Tracker):

POST /v1/e/callrail/trackers
Authorization: Bearer {jwt_token}
X-CallRail-Account-Id: 470306151
X-CallRail-Company-Id: com_abc123
Content-Type: application/json

{
  "type": "source",
  "name": "LinkedIn Ads Campaign",
  "destination_number": "+15551234567",
  "whisper_message": "Call from LinkedIn",
  "record_calls": true
}

Request Example (Session Tracker):

POST /v1/e/callrail/trackers
Authorization: Bearer {jwt_token}
X-CallRail-Account-Id: 470306151
X-CallRail-Company-Id: com_abc123
Content-Type: application/json

{
  "type": "session",
  "name": "Website Dynamic Tracker",
  "destination_number": "+15551234567",
  "pool_size": 10,
  "record_calls": true,
  "swap_targets": [
    {
      "target": "+15551234567",
      "match_type": "exact"
    }
  ]
}

Success Response:

{
  "success": true,
  "message": "SUCCESS",
  "data": {
    "id": "trk_new123",
    "name": "LinkedIn Ads Campaign",
    "type": "source",
    "tracking_number": "+15551112222",
    "formatted_tracking_number": "(555) 111-2222",
    "status": "active",
    "company_id": "com_abc123",
    "destination_number": "+15551234567",
    "whisper_message": "Call from LinkedIn",
    "record_calls": true,
    "pool_size": 1,
    "created_at": "2023-10-10T15:45:00Z"
  }
}

Tracker Types:

Source Tracker:

Static phone number for specific marketing channel
One number per tracker (pool_size: 1)
Used for: Print ads, billboards, email campaigns, social media

Session Tracker:

Dynamic number insertion for website visitors
Requires number pool (pool_size: 5-100+)
Tracks visitor session with unique number
Used for: Website tracking, visitor attribution

Required Fields by Type:

Field	Source Tracker	Session Tracker
`type`	✅ Required	✅ Required
`name`	✅ Required	✅ Required
`destination_number`	✅ Required	✅ Required
`pool_size`	Optional (default: 1)	✅ Required (min: 5)
`swap_targets`	N/A	✅ Required

Error Response (Validation Error):

{
  "success": false,
  "errno": 400,
  "message": "Pool size must be at least 5 for session trackers"
}

Error Handling:

Invalid Account: Returns 400 with INVALID_ACCOUNT_ID
Invalid Token: Returns 403 with INVALID_TOKEN
Missing Required Fields: CallRail returns validation error
Invalid Phone Number: CallRail returns validation error
Insufficient Pool Numbers: CallRail returns error if numbers unavailable

Example Usage:

// Create source tracker for Facebook Ads
await fetch('/v1/e/callrail/trackers', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${token}`,
    'X-CallRail-Account-Id': '470306151',
    'X-CallRail-Company-Id': 'com_abc123',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    type: 'source',
    name: 'Facebook Ads Q4',
    destination_number: '+15551234567',
    record_calls: true,
  }),
});

// Create session tracker for website
await fetch('/v1/e/callrail/trackers', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${token}`,
    'X-CallRail-Account-Id': '470306151',
    'X-CallRail-Company-Id': 'com_abc123',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    type: 'session',
    name: 'Website DNI',
    destination_number: '+15551234567',
    pool_size: 20,
    record_calls: true,
    swap_targets: [{ target: '+15551234567', match_type: 'exact' }],
  }),
});

Side Effects:

⚠️ Tracker Creation: Creates new tracker in CallRail
⚠️ Phone Number Allocation: Allocates tracking number(s) from pool
⚠️ Call Routing: Configures call forwarding to destination
ℹ️ External API Call: Modifies CallRail configuration

Tracker Update Functions

`putTracker(req, res, next)`

Purpose: Update existing tracker configuration

Source: Controllers/trackers.js

External API: PUT https://api.callrail.com/v3/a/{account_id}/trackers/{tracker_id}.json

Authentication: Token authentication (API key)

Parameters:

req.params.trackerId (String, required) - Tracker ID to update
req.body (Object) - Fields to update
- name (String, optional) - New tracker name
- destination_number (String, optional) - New forwarding number
- whisper_message (String, optional) - New whisper message
- record_calls (Boolean, optional) - Enable/disable recording
- status (String, optional) - "active" or "disabled"
req.callrailAccountId (String, required) - CallRail account ID
req.tokenId (ObjectId) - CallRail key document ID
req.auth.account_id (ObjectId) - DashClicks account ID

Returns: JSON response with updated tracker

{
  "success": true,
  "message": "SUCCESS",
  "data": {
    "id": "trk_12345",
    "name": "Updated Campaign Name",
    "status": "active",
    "destination_number": "+15559999999"
  }
}

Business Logic Flow:

Validate Account Access
- Verify account permissions
Retrieve API Key
- Query database for CallRail API key
- Return 403 if not found
Extract Parameters
- Get trackerId from URL parameters
- Get callrailAccountId from request
- Copy update fields from req.body
Call CallRail API
- Provider makes PUT request to /v3/a/{account}/trackers/{tracker_id}.json
- Pass update fields in request body
Return Updated Tracker
- Include all updated fields

Request Example:

PUT /v1/e/callrail/trackers/trk_12345
Authorization: Bearer {jwt_token}
X-CallRail-Account-Id: 470306151
Content-Type: application/json

{
  "name": "Updated LinkedIn Campaign",
  "destination_number": "+15559999999",
  "whisper_message": "Updated message"
}

Success Response:

{
  "success": true,
  "message": "SUCCESS",
  "data": {
    "id": "trk_12345",
    "name": "Updated LinkedIn Campaign",
    "type": "source",
    "tracking_number": "+15551112222",
    "status": "active",
    "company_id": "com_abc123",
    "destination_number": "+15559999999",
    "formatted_destination_number": "(555) 999-9999",
    "whisper_message": "Updated message",
    "record_calls": true,
    "updated_at": "2023-10-10T16:00:00Z"
  }
}

Updatable Fields:

Field	Description	Example
`name`	Tracker name	"Q4 Campaign"
`destination_number`	Call forwarding number	"+15551234567"
`whisper_message`	Message played to agent	"Call from LinkedIn"
`record_calls`	Enable/disable recording	`true`, `false`
`status`	Tracker status	"active", "disabled"
`pool_size`	Number pool size (session only)	`20`

Error Response (Not Found):

{
  "success": false,
  "errno": 404,
  "message": "Tracker not found"
}

Error Handling:

Invalid Account: Returns 400 with INVALID_ACCOUNT_ID
Invalid Token: Returns 403 with INVALID_TOKEN
Tracker Not Found: CallRail returns 404 error
Invalid Phone Number: CallRail returns validation error
CallRail API Error: Status code set to 400

Example Usage:

// Update tracker name and destination
await fetch('/v1/e/callrail/trackers/trk_12345', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${token}`,
    'X-CallRail-Account-Id': '470306151',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Updated Campaign',
    destination_number: '+15559999999',
  }),
});

// Disable tracker
await fetch('/v1/e/callrail/trackers/trk_12345', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${token}`,
    'X-CallRail-Account-Id': '470306151',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    status: 'disabled',
  }),
});

Side Effects:

⚠️ Tracker Update: Modifies tracker configuration
⚠️ Call Routing: Changes call forwarding if destination updated
⚠️ Status Change: Disabling stops call tracking
ℹ️ External API Call: Updates CallRail configuration

Tracker Deletion Functions

`deleteTracker(req, res, next)`

Purpose: Delete a tracker and release tracking number

Source: Controllers/trackers.js

External API: DELETE https://api.callrail.com/v3/a/{account_id}/trackers/{tracker_id}.json

Authentication: Token authentication (API key)

Parameters:

req.params.trackerId (String, required) - Tracker ID to delete
req.callrailAccountId (String, required) - CallRail account ID
req.tokenId (ObjectId) - CallRail key document ID
req.auth.account_id (ObjectId) - DashClicks account ID

Returns: JSON response confirming deletion

{
  "success": true,
  "message": "SUCCESS",
  "data": {}
}

Business Logic Flow:

Validate Account Access
- Verify account permissions
Retrieve API Key
- Query database for CallRail API key
- Return 403 if not found
Extract Parameters
- Get trackerId from URL parameters
- Get callrailAccountId from request
Call CallRail API
- Provider makes DELETE request to /v3/a/{account}/trackers/{tracker_id}.json
Return Success Response
- Confirm deletion completed

Request Example:

DELETE /v1/e/callrail/trackers/trk_12345
Authorization: Bearer {jwt_token}
X-CallRail-Account-Id: 470306151

Success Response:

{
  "success": true,
  "message": "SUCCESS",
  "data": {}
}

Error Response (Not Found):

{
  "success": false,
  "errno": 404,
  "message": "Tracker not found"
}

Error Handling:

Invalid Account: Returns 400 with INVALID_ACCOUNT_ID
Invalid Token: Returns 403 with INVALID_TOKEN
Tracker Not Found: CallRail returns 404 error
Active Calls: May require confirmation if calls active
CallRail API Error: Status code set to 400

Example Usage:

// Delete tracker
await fetch('/v1/e/callrail/trackers/trk_12345', {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${token}`,
    'X-CallRail-Account-Id': '470306151',
  },
});

Side Effects:

⚠️ Tracker Deletion: Permanently removes tracker
⚠️ Number Release: Releases tracking number back to pool
⚠️ Call History: Historical call data preserved
⚠️ Active Calls: May impact active call routing
ℹ️ External API Call: Modifies CallRail configuration

Provider Functions

`getTrackerList(apiKey, callrailAccountId, callrailCompanyId, query)`

Purpose: Call CallRail API to retrieve tracker list

Source: Providers/trackers-api.js

External API: GET https://api.callrail.com/v3/a/{account_id}/trackers.json

Authentication: Token authentication (Token token={api_key})

Parameters:

apiKey (String) - CallRail API key
callrailAccountId (String) - CallRail account ID
callrailCompanyId (String) - CallRail company ID
query (Object) - Query parameters

Returns: Promise<Object> - API response data

HTTP Request:

GET /v3/a/470306151/trackers.json?company_id=com_abc123&page=1&per_page=20
Host: api.callrail.com
Authorization: Token token={api_key}

Example Usage:

const trackers = await trackersApi.getTrackerList(apiKey, '470306151', 'com_abc123', {
  page: 1,
  per_page: 20,
  sort: 'name',
});

Side Effects:

ℹ️ External API Call: CallRail API request

`getTracker(apiKey, callrailAccountId, trackerId)`

Purpose: Call CallRail API to retrieve specific tracker

Source: Providers/trackers-api.js

External API: GET https://api.callrail.com/v3/a/{account_id}/trackers/{tracker_id}.json

Parameters:

apiKey (String) - CallRail API key
callrailAccountId (String) - CallRail account ID
trackerId (String) - Tracker ID

Returns: Promise<Object> - Tracker details

Example Usage:

const tracker = await trackersApi.getTracker(apiKey, '470306151', 'trk_12345');

Side Effects:

ℹ️ External API Call: CallRail API request

`postTracker(apiKey, callrailAccountId, requestBody)`

Purpose: Call CallRail API to create tracker

Source: Providers/trackers-api.js

External API: POST https://api.callrail.com/v3/a/{account_id}/trackers.json

Parameters:

apiKey (String) - CallRail API key
callrailAccountId (String) - CallRail account ID
requestBody (Object) - Tracker configuration

Returns: Promise<Object> - Created tracker

Example Usage:

const newTracker = await trackersApi.postTracker(apiKey, '470306151', {
  type: 'source',
  name: 'New Campaign',
  destination_number: '+15551234567',
  company_id: 'com_abc123',
});

Side Effects:

⚠️ Tracker Creation: Creates tracker in CallRail
ℹ️ External API Call: Modifies CallRail configuration

`updateTracker(apiKey, callrailAccountId, trackerId, requestBody)`

Purpose: Call CallRail API to update tracker

Source: Providers/trackers-api.js

External API: PUT https://api.callrail.com/v3/a/{account_id}/trackers/{tracker_id}.json

Parameters:

apiKey (String) - CallRail API key
callrailAccountId (String) - CallRail account ID
trackerId (String) - Tracker ID
requestBody (Object) - Update fields

Returns: Promise<Object> - Updated tracker

Example Usage:

const updated = await trackersApi.updateTracker(apiKey, '470306151', 'trk_12345', {
  name: 'Updated Name',
  destination_number: '+15559999999',
});

Side Effects:

⚠️ Tracker Update: Modifies tracker configuration
ℹ️ External API Call: Updates CallRail configuration

`deleteTracker(apiKey, callrailAccountId, trackerId)`

Purpose: Call CallRail API to delete tracker

Source: Providers/trackers-api.js

External API: DELETE https://api.callrail.com/v3/a/{account_id}/trackers/{tracker_id}.json

Parameters:

apiKey (String) - CallRail API key
callrailAccountId (String) - CallRail account ID
trackerId (String) - Tracker ID

Returns: Promise<Object> - Deletion confirmation

Example Usage:

await trackersApi.deleteTracker(apiKey, '470306151', 'trk_12345');

Side Effects:

⚠️ Tracker Deletion: Removes tracker from CallRail
⚠️ Number Release: Releases tracking number
ℹ️ External API Call: Modifies CallRail configuration

🔀 Integration Points

Dynamic Number Insertion (DNI)

Session Tracker Integration:

JavaScript swap code on website swaps displayed numbers
Unique tracking number per visitor session
Attributes calls to specific visitor and traffic source

Implementation:

<!-- Add to website <head> -->
<script src="https://cdn.callrail.com/companies/123456/abc123/12/swap.js"></script>

Campaign Attribution

Source Tracker Usage:

Use different tracker for each marketing channel
Track ROI for print ads, email campaigns, social media
Compare performance across channels

Call Routing

Destination Number Configuration:

Calls forwarded to destination_number
Can route to different numbers based on time of day
Whisper message identifies call source to agent

🧪 Edge Cases & Special Handling

Number Pool Management

Issue: Session trackers require sufficient number pool

Handling:

Minimum pool_size: 5 for session trackers
Recommended: 1 number per 100 monthly visitors
CallRail returns error if insufficient numbers available

Tracker Deletion with Active Calls

Issue: Deleting tracker while calls active

Handling:

CallRail may require confirmation for deletion
Historical call data preserved
Tracking number released back to pool

Number Portability

Issue: Customer wants to port existing number

Handling:

CallRail supports number porting
Requires separate porting request process
Not handled through API

Geographic Number Selection

Issue: Need local numbers for specific areas

Handling:

CallRail auto-selects numbers based on company location
Can request specific area codes through support
Limited API control over number selection

⚠️ Important Notes

📞 Tracker Types: Source (static) vs Session (dynamic) trackers
🔢 Number Pools: Session trackers require pool_size ≥ 5
🎯 Call Routing: Calls forwarded to destination_number
🎙️ Whisper Messages: Optional message played to agent
📊 Call Tracking: All calls attributed to tracker
🔐 Authentication: Token-based authentication (not Bearer)
📝 Field Selection: Use fields parameter to optimize response size
🔍 Search: Search by tracker name for quick lookup
⚠️ Deletion: Permanently removes tracker and releases number
🌐 DNI: Session trackers enable dynamic number insertion on websites

Integration Overview: CallRail Integration
Authentication: API Key Management
Accounts & Companies: Organization Hierarchy
Calls: Call Tracking & Analytics
CallRail API: Trackers Documentation

📖 Overview​

🗄️ Collections Used​

integrations.callrail.key​

🔄 Data Flow​

Tracker Listing Flow​

Tracker Creation Flow​

🔧 Business Logic & Functions​

Tracker Listing Functions​

getTrackersList(req, res, next)​

getTracker(req, res, next)​

Tracker Creation Functions​

postTracker(req, res, next)​

Tracker Update Functions​

putTracker(req, res, next)​

Tracker Deletion Functions​

deleteTracker(req, res, next)​

Provider Functions​

getTrackerList(apiKey, callrailAccountId, callrailCompanyId, query)​

getTracker(apiKey, callrailAccountId, trackerId)​

postTracker(apiKey, callrailAccountId, requestBody)​

updateTracker(apiKey, callrailAccountId, trackerId, requestBody)​

deleteTracker(apiKey, callrailAccountId, trackerId)​

🔀 Integration Points​

Dynamic Number Insertion (DNI)​

Campaign Attribution​

Call Routing​

🧪 Edge Cases & Special Handling​

Number Pool Management​

Tracker Deletion with Active Calls​

Number Portability​

Geographic Number Selection​

⚠️ Important Notes​

🔗 Related Documentation​

Documentation Assistant

📖 Overview

🗄️ Collections Used

`integrations.callrail.key`

🔄 Data Flow

Tracker Listing Flow

Tracker Creation Flow

🔧 Business Logic & Functions

Tracker Listing Functions

`getTrackersList(req, res, next)`

`getTracker(req, res, next)`

Tracker Creation Functions

`postTracker(req, res, next)`

Tracker Update Functions

`putTracker(req, res, next)`

Tracker Deletion Functions

`deleteTracker(req, res, next)`

Provider Functions

`getTrackerList(apiKey, callrailAccountId, callrailCompanyId, query)`

`getTracker(apiKey, callrailAccountId, trackerId)`

`postTracker(apiKey, callrailAccountId, requestBody)`

`updateTracker(apiKey, callrailAccountId, trackerId, requestBody)`

`deleteTracker(apiKey, callrailAccountId, trackerId)`

🔀 Integration Points

Dynamic Number Insertion (DNI)

Campaign Attribution

Call Routing

🧪 Edge Cases & Special Handling

Number Pool Management

Tracker Deletion with Active Calls

Number Portability

Geographic Number Selection

⚠️ Important Notes

🔗 Related Documentation