Outbound Whitelist
The Outbound Whitelist controls which external numbers PBX users can dial. Entries define country and prefix rules with associated outbound trunks.
Purpose
Use this module to:
- Restrict outbound dialing by destination country and prefix
- Assign outbound trunks to specific destinations
- Assign a default outbound caller ID for destinations matching a rule
- Enable or disable rules per destination
For a full explanation of how OPBX authorizes outbound calls and decides which caller ID to present, see the Outbound Calling Overview.
Matching Algorithm
The OutboundRoutingService uses a scoring system to select the best matching rule:
- Country match:
+10 - Full international prefix match:
+length of prefix - Local prefix match:
+length of prefix
The entry with the highest score wins. A prefix that does not match rejects the call entirely.
Permissions
| Action | Owner | PBX Admin | PBX User | Reporter |
|---|---|---|---|---|
| View whitelist | Yes | Yes | Yes | Yes |
| Create whitelist entries | Yes | Yes | No | No |
| Update whitelist entries | Yes | Yes | No | No |
| Delete whitelist entries | Yes | Yes | No | No |
UI Workflow
Add a Whitelist Entry
- Navigate to Outbound Whitelist in the sidebar
- Click Add Rule
- Enter a name
- Select the destination country
- Enter the destination prefix (optional)
- Select the outbound trunk name
- Optionally select a Default Caller ID — an active DID owned by your organization to present on calls matching this rule
- Save
The destination country must be unique within your organization — you cannot create two rules for the same country.
Default Caller ID
When set, the rule's Default Caller ID is presented on outbound calls matching this rule unless the calling extension has its own caller ID, which takes precedence. See the Outbound Calling Overview for the full precedence order.
Toggle Status
Use the status toggle to enable or disable a rule. Disabled rules are not used for outbound routing.
Key Data Fields
outbound_whitelists Table
| Column | Type | Notes |
|---|---|---|
id | bigint | Primary key |
organization_id | FK | Tenant scope |
name | string | |
destination_country | string | |
destination_prefix | string | |
outbound_trunk_name | string | |
default_caller_id_did_id | FK nullable | DID presented as caller ID for matching calls |
status | enum | active, inactive |
The API also returns a nested default_caller_id object (id, phone_number, friendly_name) when the relationship is loaded.
Related API Endpoints
| Method | Endpoint | Purpose |
|---|---|---|
| GET/POST/PUT/DELETE | /v1/outbound-whitelist[/{outboundWhitelist}] | Standard CRUD |
| PATCH | /v1/outbound-whitelist/{outboundWhitelist}/toggle-status | Toggle active status |
See the OPBX REST API reference for full schemas.
Related Modules
- Auto Dialer Campaigns — Outbound trunk selection for campaigns
- Phone Numbers (DIDs) — DIDs used as the default caller ID
- Auto Dialer Campaigns — Outbound trunk selection for campaigns
- Voice Routing Engine — OutboundRoutingService is used during call routing