How to Manage the Blacklist

Viewing the Blacklist

Navigate to Setup System > Blacklist in the left
sidebar. The page lists
every Contact record in your company where
blocked = true. You must be a superuser with the
suppression_list permission to access it. Without that
permission the page returns a permission error.

The index displays columns for Created At, Blocked At,
Name, and Block / Unblock Logs. A fulltext search box
accepts phone numbers in the format +17191231234, and a
per-page selector controls how many rows are shown.

Five action links live at the top of the page:

• View Blacklist (/contacts/): the index you are already on.
• Upload Blacklist (/contact_imports/new): bulk import a CSV of numbers to block.
• Blacklist Files (/contact_imports/): the history of previous uploads and their processing status.
• Export Blacklist (/data_exports/new?data_type=contact): download the current blacklist as a file.
• Clear Blacklist (/unblock_contact_jobs/): create and manage jobs that unblock numbers in bulk.

Opening an individual Contact at /contacts/:id shows a
read-only detail view with the number, creation time,
blocked status, country, and time zone. Block and unblock
controls do not live on this page.

Adding a Number to the Blacklist

There is no direct "block this number" button on the
blacklist index itself. Blocks are applied through one of
the following paths:

1. From a call detail page. When editing any call, the call action buttons include a Block Caller icon (gated by the Call:block permission). Clicking it flips Contact.blocked for the caller's number via the JavaScript handler in trackdrive/contacts/actions.js. If the caller is already blocked, the same button reads Unblock Caller.
2. Through the API. POST /api/v1/contacts/:caller_id/caller_block blocks a caller by phone number; POST /api/v1/contacts/:caller_id/caller_unblock reverses it.
3. Through a bulk upload. In the Blacklist Tab use the Upload Blacklist Tab to import a CSV File or text of numbers. /contact_imports/new.
4. Automatically when a lead or call triggers a schedule action or manual action that applies a block.

Every block and unblock creates a block log entry
recording the user, the collaborator, the source call or
lead, and the request IP. This audit trail is permanent.

Removing a Number from the Blacklist

Unblocks use the same paths as blocks: the call detail
page toggle, the API, or a bulk Clear Blacklist job at
/unblock_contact_jobs/. An unblock sets
blocked = false and records a block log entry with
the blocked_cleared_at timestamp. The Contact record
itself is not deleted. Contact records are retained
indefinitely so that their counters, opt-out history, and
block history remain intact.

What the Blacklist Blocks

Once a Contact is blocked for your company, the platform
restricts to dial that number on outbound calls, restricts to
match it to offers on inbound calls, and restricts to send
SMS to it. The enforcement is cached briefly for
performance: Contact.blocked_by_company? wraps a
15 second Rails.cache.fetch, so unblocks take effect
within seconds rather than instantly.