Auto-Suppression and Auto-Acceptance with Caller Lists

This is ideal when you want to:

• Prevent repeat callers from reaching the same buyer
• Enforce cooling-off periods
• Reduce wasted calls and buyer frustration
• Control routing behavior, not just conversion logic

General Use Cases

Auto-Suppression is useful when you want to:

• Prevent repeat callers from reaching the same buyer
• Enforce cooling-off periods after key call events
• Reduce wasted buyer time and operational costs
• Block calls at the routing layer, not just at conversion
• Automatically recycle callers after a defined timeframe
• Apply dynamic suppression logic based on call behavior

What are caller lists

Caller Lists give you precise control over which caller numbers can and cannot be accepted in a campaign and reach specific buyers. Caller phone numbers could be automatically added to one or more Caller Lists based on different conditions and remain on a list for a certain amount of hours or days.

There are two types of Caller Lists based on their name:

• Suppressed lists (name starts with "suppressed") block matching callers. If a caller's number is found on a suppressed list, the target or campaign is excluded from routing.
• Accepted lists (name starts with "accepted") act as allowlists. When present, only callers whose number appears on the list can reach that target or campaign. Creating an accepted list requires explicit confirmation.

Caller Lists can live on both Campaigns and Buyers. Campaign-level lists are evaluated early in the call flow to determine whether a call is acceptable at all. Buyer-level lists are evaluated during buyer resolution, filtering individual buyers before routing.

Numbers on a list can be set to automatically expire after a configurable duration (hours or days), useful for time-limited suppression like de-duplication windows. Expired numbers are treated as if they don't exist on the list.

Caller Lists can be managed through the UI, via bulk CSV upload, or programmatically through the API using postback keys with granular permissions for creating, reading, and deleting individual numbers.

Understanding Call Flow: Deduplication vs. Suppression

In the world of call routing and lead management, "cleaning" your data is the difference between a high-performing campaign and a wasted budget. Two terms often get used interchangeably, but they serve completely different functions in your call flow: Deduplication and Suppression.

The easiest way to remember the difference is by looking at when the action happens. Does the call reach your campaign before it's flagged, or is it blocked from entering the campaign entirely?

Deduplication: The Post-Call Audit

Deduplication is the process of identifying a caller who has already reached out to you within a specific timeframe.

In this scenario, the call is allowed to happen. The caller dials the number, Retreaver identifies the Caller ID, and then cross-references it against previous calls. If that number has called recently, Retreaver could mark that specific call as a "De-duped by UUID." where UUID is the identifier of the previously occurred call.

• How it works: Call received -> Database check -> Match found -> Status updated to "De-duped by."
• The Result: You have a record of the call in your logs, but because it is marked as a duplicate, it typically isn't a receivable or payable and might lack a revenue or payout.
• Key Insight: Deduplication happens after the call has occurred.

Suppression: The Pre-Call Gatekeeper

Suppression is a proactive shield. It uses a "Suppression/Acceptance List" to ensure that certain callers never enter your campaign or never reach a specific buyer in the first place.

With suppression, the call is prevented from happening within the context of your campaign or buyer routing. If a phone number is on a caller list, Retreaver recognizes this at the start of the call and makes routing decisions based on this.

• How it works: Incoming call -> Caller list check -> Match found -> Call Suppressed/Accepted.
• The Result: The call never reaches the campaign or the buyer. It is stopped at the gate.
• Key Insight: Suppression/Acceptance through the Caller Lists prevents the call from ever reaching its destination.

Deduplication vs Suppression Summary

To put it simply: Deduplication is an accounting tool that tells you a call was a duplicate of a previous call. Suppression/Acceptance is a security/routing/optimization tool that ensures the call is never allowed to go through to a campaign or buyer.

Both are essential for maintaining "clean" traffic, but knowing when to use which will save you significant time in your reporting and significantly more money in your routing.

How Auto-Suppression Works

At the end of the call Retreaver evaluates the call and can add the caller number to one or more lists of the Campaign or the Buyer that accepted the call.

Creating Caller Lists

Caller Lists are created directly on the Buyer Profile or the Campaign.

To create a Caller List:

1. Open the Buyer Profile
2. Scroll to the Caller Lists section
3. Click Add Caller List
4. Select or enter a name for the list
   • Use default suppressed or accepted
   • In case of special use cases you can choose your own name. There are not many use cases in which you will need a name different than "suppressed" or "accepted". Avoid names like "suppressed_30_days", "suppressed_sales" and others that are based on conditions.
5. Choose a Remove number after option
   • Example: 30 days, 60 days, or Never remove
6. Choose when caller numbers should be added to the list
7. Save the list

Each list can automatically release numbers after the selected timeframe.

Managing Callers Lists from outside of Retreaver

In some advanced use cases the Caller List could be managed from outside Retreaver through the Caller List API. It is useful for adding numbers to a caller list from other companies on Retreaver or from external systems.

Creating a Caller List Management Key

To manage Caller Lists programmatically, you must create a Caller List Management Postback Key.

1. On the Buyer Profile, scroll to Postback Keys
2. Click Add Key
3. Select Caller List Management
4. Give the key a descriptive name (example: Auto Suppression Key)
5. Enable the following permissions:
   • Caller list number show
   • Caller list number create
   • Caller list number delete
   • Caller list upload create
   • Caller list show
   • Caller list create
   • Caller list delete
6. Save the key

After saving, you will receive:

• A Postback Key Value (used in the webhook URL)
• A Secret Key (used as the Authorization bearer token)

These credentials are required for the webhook setup.

Setting Up the Auto-Suppression Webhook

Next, create a webhook that adds caller numbers to the Caller List automatically.

1. Go to Webhooks
2. Create a new webhook
3. Choose the trigger that should cause suppression
   • Example: If call converted
4. Configure the webhook using the template below

Webhook Configuration

Ping URL

https://api.retreaver.com/api/v2/targets/[buyer_id]/caller_lists/[caller_list_name]/caller_list_numbers.json?key=[caller_lists_key]

Ping method

POST

Ping headers

{"Content-Type":"application/json","Authorization":"Bearer [secret_key]"}

Ping data

{"caller_list_number":{"number":"[caller_number]"}}

Ping output map

{"PingOutputMap":{}}

Replace:

• [buyer_id] with the Buyer ID
• [caller_list_name] with the exact Caller List name
• [caller_lists_key] with the postback key value
• [secret_key] with the postback secret key value

Save the webhook once configured.

Blocking Calls with Buyer Tags

To enforce suppression during routing, you must add a tag to the buyer profile. This tag prevents calls from being routed when the caller's phone number exists on a specified Caller List.

Add the Buyer Tag

1. Edit the Buyer Profile
2. Navigate to Tags
3. Click Wizard
4. Select Text Tag

Tag Configuration

Key caller_number

Operator not-in

Value [caller_list_name] Example: suppressed_30_days

You can create multiple caller lists and separate each based on suppression trigger or release period.

What Happens After Setup

Once everything is configured:

• Calls that trigger the webhook are added to the Caller List
• Future calls from the same number are blocked from routing
• Numbers are automatically released based on the list's retention setting
• Routing resumes once the number is no longer on the list

This works alongside conversion dedupe, but adds call-level enforcement before routing occurs.