Caller ID Suppression Using "Bid Received" Webhook Events

Caller ID suppression is a critical compliance and quality control feature that allows you to automatically block or reject calls from specific phone numbers before they reach your buyers. Using CallGrid's "Bid Received" webhook event, you can integrate with suppression services or custom databases to screen incoming calls in real-time and prevent unwanted traffic from consuming your buyers' capacity.

What is Caller ID Suppression?#

Caller ID suppression involves checking incoming phone numbers against various databases to determine if the call should be blocked. Common suppression categories include:

• Do Not Call (DNC) Lists - Federally registered numbers that have opted out
• Internal Suppression Lists - Numbers you've manually flagged for blocking
• Spam/Fraud Numbers - Known robocall or fraudulent phone numbers
• Competitive Suppression - Numbers from competitors or unwanted sources
• Previous Conversions - Numbers that have already converted to prevent duplicates

Why Suppression is Important#

Compliance Protection: Avoid TCPA violations and regulatory fines by respecting DNC registrations Quality Control: Block low-quality or spam traffic before it reaches buyers Cost Savings: Prevent wasted spend on calls that won't convert Buyer Relationships: Maintain trust by delivering only compliant, high-quality leads Brand Protection: Avoid associations with fraudulent or spam calling patterns

Setting Up Caller ID Suppression#

Step 1: Navigate to Webhook Configuration#

1. Go to Integrations → Webhooks in your CallGrid dashboard
2. Click New Webhook to create a new suppression webhook
3. Enable Template Mode for pre-configured suppression services

Step 2: Choose Your Suppression Provider#

Using Blacklist Alliance (Template Mode):

1. Select Blacklist Alliance from the template dropdown
2. This provides comprehensive DNC and suppression list checking
3. Template automatically configures the proper API endpoints and formatting

Using a Custom Suppression Endpoint:

1. Disable Template Mode
2. Enter your custom suppression service URL
3. Configure the request format to match your service's API

Step 3: Configure the Bid Received Event#

1. In the Event dropdown, select "Bid Received"
2. Name your webhook descriptively (e.g., "DNC Suppression Check")
3. The webhook fires when a bid is received, allowing real-time suppression before call routing

Step 4: Authentication Setup#

For Blacklist Alliance:

1. Enter your Blacklist Alliance API key in the Bearer Authentication Token field
2. Obtain your API key from your Blacklist Alliance account dashboard
3. Refer to Blacklist Alliance documentation for specific authentication requirements

For Custom Endpoints:

1. Add required authentication headers using Add Header
2. Common authentication methods include:
3. • API keys in headers (X-API-Key, Authorization)
   • Bearer tokens (Authorization: Bearer your-token)
   • Basic authentication credentials

Step 5: Configure Request Payload#

The webhook will send caller information to your suppression service:

Standard Variables Available:

• tagPhoneNumber - The caller's phone number (primary suppression field)
• tagCallId - Unique call identifier for tracking
• tagCampaignId - Campaign identifier for campaign-specific suppression
• tagSourceId - Traffic source for source-based filtering

Example JSON Payload:

{

  "phoneNumber": "{{tagPhoneNumber}}",

  "callId": "{{tagCallId}}",

  "campaignId": "{{tagCampaignId}}",

  "checkTypes": ["DNC", "SPAM", "INTERNAL"]

}

Step 6: Configure Suppression Response Handling#

Acceptance Parsing#

Set up rules to determine when a call should be allowed:

Example Acceptance Rules:

• Response contains "status": "CLEAN"
• Response contains "suppressed": false
• HTTP status code is 200 and response includes "allowed": true

Rejection Logic#

Configure when calls should be blocked:

Automatic Rejection Scenarios:

• Response contains "suppressed": true
• Response includes "reason": "DNC_LISTED"
• Service returns specific error codes indicating suppression

Step 7: Test Your Suppression Setup#

1. Use Webhook Testing to test with known suppressed numbers
2. Test with clean numbers to ensure they pass through correctly
3. Verify response parsing is working as expected
4. Check suppression logs for proper blocking behavior

Blacklist Alliance Integration Example#

Configuration Steps#

1. Template Selection: Choose "Blacklist Alliance" template
2. Authentication: Enter your Blacklist Alliance API key
3. Event Trigger: Set to "Bid Received"
4. Response Handling: Template automatically configures suppression logic

Expected Response Format#

Blacklist Alliance returns standardized responses:

{

  "phoneNumber": "+15551234567",

  "suppressed": false,

  "lists": ["DNC", "INTERNAL"],

  "status": "CLEAN",

  "reason": null

}

Suppression Actions#

• suppressed: true → Call is blocked and not routed to buyers
• suppressed: false → Call continues normal routing process
• API Error → Call continues routing (fail-open for reliability)

Custom Suppression Integration#

Building Your Own Suppression Service#

If you need custom suppression logic, you can build your own endpoint:

Required Endpoint Capabilities:

1. Accept POST requests with caller phone number
2. Query your suppression databases/lists
3. Return standardized response indicating suppression status
4. Handle high request volumes with low latency

Sample Custom Endpoint Response:

{

  "phoneNumber": "+15551234567",

  "shouldSuppress": true,

  "reason": "INTERNAL_BLACKLIST",

  "listMatches": ["internal_dnc", "previous_conversion"],

  "timestamp": "2025-10-21T10:30:00Z"

}

Integration Configuration#

1. Webhook URL: Point to your custom suppression endpoint
2. Method: Set to POST
3. Headers: Add any required authentication or content-type headers
4. JSON Body: Configure payload with necessary caller data
5. Acceptance Parsing: Define rules based on your response format

Advanced Suppression Strategies#

Multi-Level Suppression#

Combine multiple suppression checks:

1. Primary Check: DNC and federal compliance lists
2. Secondary Check: Internal suppression and previous conversions
3. Tertiary Check: Quality scoring and fraud detection

Campaign-Specific Suppression#

Configure different suppression rules per campaign:

• High-Value Campaigns: Stricter suppression for premium traffic
• Volume Campaigns: Basic DNC checking only
• Test Campaigns: Minimal suppression for data collection

Time-Based Suppression#

Implement suppression rules based on timing:

• Recent Contact Suppression: Block numbers contacted within X days
• Time-of-Day Rules: Different suppression during business hours
• Frequency Capping: Limit calls per number per time period

Response Handling Best Practices#

Fail-Open vs Fail-Closed#

Fail-Open (Recommended):

• If suppression service is unavailable, allow calls through
• Prevents lost revenue from service outages
• Maintains call flow reliability

Fail-Closed:

• If suppression service fails, block all calls
• Maximum compliance protection
• Risk of losing legitimate traffic

Error Handling#

Configure appropriate responses for common scenarios:

• Service Timeout: Continue routing after 2-3 second timeout
• Invalid Response: Log error and allow call through
• Rate Limiting: Implement backoff and retry logic

Monitoring and Optimization#

Key Metrics to Track#

• Suppression Rate: Percentage of calls blocked
• Response Times: Average suppression check duration
• Error Rates: Failed suppression API calls
• False Positives: Legitimate calls incorrectly suppressed

Performance Optimization#

• Caching: Cache suppression results for recent lookups
• Batch Processing: Group multiple number checks when possible
• Regional Services: Use geographically distributed suppression APIs
• Timeout Tuning: Balance compliance checking with call latency

Compliance Considerations#

Legal Requirements#

• TCPA Compliance: Honor federal Do Not Call registry
• State Regulations: Check state-specific DNC requirements
• Industry Standards: Follow vertical-specific suppression rules
• Documentation: Maintain logs of suppression actions for audits

Data Privacy#

• Minimal Data: Only send necessary information for suppression checks
• Secure Transmission: Use HTTPS for all suppression API calls
• Data Retention: Follow provider guidelines for data storage
• Consent Management: Respect user opt-out preferences

Troubleshooting Common Issues#

High Suppression Rates#

Possible Causes:

• Overly aggressive suppression rules
• Outdated or incorrect suppression lists
• API configuration errors

Solutions:

• Review suppression logic and acceptance criteria
• Audit suppression list sources and update frequency
• Test with known clean numbers

Suppression Failures#

Common Issues:

• Authentication token expired or invalid
• Network connectivity problems
• API rate limiting or quota exceeded
• Malformed request payload

Debugging Steps:

1. Check webhook logs for specific error messages
2. Test authentication credentials independently
3. Verify API endpoint URLs and request format
4. Monitor API response times and success rates

Performance Impact#

Symptoms:

• Increased call connection times
• Buyer complaints about delayed calls
• Higher call abandonment rates

Optimization:

• Reduce suppression API timeout values
• Implement local caching for frequent numbers
• Consider asynchronous suppression for non-critical checks

Next Steps#

After implementing caller ID suppression:

1. Monitor Performance: Track suppression rates and system impact
2. Audit Regularly: Review suppressed calls to ensure accuracy
3. Update Lists: Keep suppression databases current and accurate
4. Expand Coverage: Consider additional suppression data sources
5. Optimize Rules: Fine-tune suppression logic based on performance data

For technical support with suppression integrations or questions about specific provider APIs, contact our support team or refer to your suppression provider's documentation.