Reviewers (YT:PMD-3632):

  • PM  
  • Dev  
  • QA  
  • PO  
  • TW  

User Story

As a CSP operating in South Africa, I want PortaSwitch to perform a CLI ownership check and reject calls if the check fails on both:

  • Outgoing calls from my customers and resellers, since ICASA requires licensed operators to use only numbers allocated to or authorized for use by them and to prohibit the transmission of inaccurate CLI. My resellers can misconfigure customer accounts with invalid CLIs, and I cannot control the correctness of CLIs sent from all accounts across all resellers. This way, I can ensure compliance with the ICASA Numbering Plan Regulations, and prevent regulatory sanctions, including fines, barring or withdrawal of affected numbering resources.
  • Incoming calls from operators to my customers and resellers to comply with the ICASA Numbering Plan Regulations by preventing inaccurate or unauthorized CLIs from being transmitted through my network.

Example of use

Outgoing call

Account 27875501000 of a reseller's customer "Acme Logistics" is allowed to use CLI 27875501000, but the reseller misconfigured the customer's account to present another CLI 27825559911, which does not belong to the CSP.
When "Acme Logistics" makes an outgoing call presenting CLI 27825559911, PortaSwitch performs the CLI ownership check, detects that 27825559911 is not allowed to be used by the CSP, and rejects the call.

Incoming call

PortaSwitch receives an incoming call from MTN operator with CLI 27825559900 to account 27875501000 of the customer "Acme Logistics", PortaSwitch performs the number ownership check, detects that CLI 27825559900 is not allowed to be used by MTN, and rejects the call instead of delivering it to "Acme Logistics".

Business model

VoIP and Mobile

Technology

  • Billing
  • SIP 
  • Number Portability

Current Solution

PortaSwitch currently provides partial CLI validation through the following mechanisms:

1. Outbound (Customer → Vendor) via SIP Identity / Override Identity feature

  • If "Override Identity" feature is disabled - a customer may present any CLI
  • If "Override Identity" feature is enabled, Admin defines in what case CLI should be overriden: 
    • If different from all customer accounts
    • If different from account ID and aliases
    • If different from all accounts in the specified batch
    • If different from all accounts in the specified hunt group
    • If different from all accounts in the specified site
    • Always
  • Invalid CLI is overriden either by the "Identity" value, or account ID (if "Identity" value is not defined)
  • Limitations: 
    • Validation is static, based on numbers explicitly assigned in PortaBilling. 
    • The “Override Identity” feature requires manual configuration on a per-customer/account basis. For CSPs managing hundreds of resellers and thousands of customers, it is operationally challenging to verify the correctness of the CLI  presentation configuration on each account.

2. Outbound Format Validation per Vendor Connection — CLI Validation Engine + 'Route Calls with Valid CLI Only'

  • Enabled via CallerIdValidation.Enable on the Configuration Server.

  • CLI is checked against configurable rules (allow/deny patterns); unmatched CLIs are validated by Google's libphonenumber library for E.164 compliance.

  • Per vendor connection, 'Route calls with valid CLI only' toggle blocks calls with invalid-format CLI.

  • Limitations:

    • Validates format and number validity only — not authorisation or ownership. A spoofed but well-formed E.164 number passes validation.

    • Available only for "To Vendor" connections. No CLI validation on incoming calls.

3. Number Portability Lookups

  • Used to identify whether the destination number has been ported to ensure that calls are routed to the correct operator and charged at the correct rate.
  • Limitations: 
    • PortaBilling checks only CLD against the configured number portability lookup rules. There is an exception for zone rating: CLI is currently being looked up if  [ChargingZone]UsePortedNumberHome option is enabled.

South African VoIP providers using PortaSwitch could potentially perform CLI ownership validation using 3rd party solutions — an SBC with ENUM/LNP lookup capability, but it is not affordable for many providers and requires dedicated infrastructure. 

4. Origin-Based Routing/Rating — Forbidden CLI Origins

  • Allows tariffs to match the CLI against configurable prefix code groups and apply different prices, routing decisions, or a Forbidden flag per origination group. By marking specific CLI prefix ranges as Forbidden in a tariff assigned to a vendor connection, calls where the CLI matches a non-permitted prefix range can be rejected on both inbound and outbound calls.
  • Limitations:
    • Matches CLI against static prefix code groups only — no awareness of the number portability. A ported number retains its original prefix and would be incorrectly blocked or allowed based on that prefix rather than its current network ownership.
    • Requires the CSP to manually maintain complete and up-to-date prefix code group and any change in number range allocations — new prefixes issued by ICASA, ranges transferred between operators — requires a manual tariff update, carrying the risk of stale data causing false rejections or missed spoofing.
    • Does not provide a descriptive header identifying the specific CLI validation failure — the rejection reason is not self-explanatory in call traces.
    • Requires migration from regular tariffs to new tariffs with code groups.

The current solution doesn't support:

  • CLI ownership check on outgoing and incoming calls using number portability check

Stakeholders and their benefits

Who are the users / whom we bring value to?

Benefit /
Stakeholders		More
Comfort		Increased
Efficiency		Saves
Time		Tighter
Control		Regulatory
Requirement
CSP✓
✓✓✓
Sales/marketing of CSP



✓
Resellers / distributors

✓✓✓
Network operations /
Support of CSP		✓✓✓✓
Vendors



✓
End user✓

✓

Use Cases

Use case #1: CLI ownership check on outgoing calls from customer

Roles: PortaSwitch, Operators, CSP Admin, Reseller, End users

Preconditions: 

  • CSP "Start Telecom" in SA partners with operators MTN, Vodacom and Cell C for sending call from CSP's Portawitch to these operators and receiving calls from them to PortaSwitch.
  • CLI validation to be in E.164 format is enabled for each operator for both outgoing and incoming calls. (new feature; currently supported only for outgoing calls)
  • CSP Admin has defined the number ownership on their PortaBilling environment identifying what number prefixes belong to what operator: (new feature)
    PrefixOperator
    2783MTN
    2782Vodacom
    2784Cell C
    2787Star Telecom
  • CSP stores the information about ported numbers in PortaSwitch and the information is updated daily from the SA LNP authority and contains information about all South African ported numbers.
  • CSP Admin has enabled CLI ownership check for each operator for both outgoing and incoming calls. (new feature)
  • CSP lease a range of numbers from MTN and a range of numbers from Vodacom, so CSP Admin has configured PortaSwitch to allow outgoing calls from leased numbers to the corresponding operators (MTN's CLI to MTN, Vodacom's CLIs to Vodacom) even though they are not owner by CSP. (new feature)
  • CSP has configured dedicated routing plans for all accounts that use leased numbers, so that calls from MTN numbers are always routed to MTN, and calls from Vodacom numbers are always routed to Vodacom.
  • Reseller "OneCall" of the CSP has a PBX customer "Acme Logistics" with account ID 27875501000 and its aliases 27872004001, 27872004002, and account with MTN leased number 27831122334 with a routing plan allowing calls only via MTN.  "Acme Logistics" is allowed to present only these four numbers as CLI. If customer is making a call with a different CLI, it is replaced with account ID 27875501000.

Use scenario #1.1 Customer sends a CLI belonging to CSP (successful)

  1. "Acme Logistics" makes an outgoing call with CLI 27872004001 to MTN subscriber 27834009900.
  2. PortaSwitch verifies that CLI is a valid number in E.164 format.
    1. If CLI format validation fails, the call is rejected.
  3. PortaSwitch perfoms the number ownership check, identifies that the number 27872004001 belongs to the CSP, it has not been ported, and is allowed to be used by "Acme Logistics".
  4. The call is successfully authorized with CLI 27872004001.

Use scenario #1.2 Customer sends CLI belonging to another operator (rejected)

  1. "Acme Logistics" makes an outgoing call with CLI 27825559900.
  2. PortaSwitch verifies that CLI is a valid number in E.164 format.
  3. PortaSwitch perfoms the number ownership check, identifies that the number neither belongs  nor has been ported to the CSP.
  4. The call is rejected with the reason "CLI 27825559900 does not match CSP network — LNP validation failed".
  5. Reseller can identify that they have misconfigured "Acme Logistics" settings to present the wrong CLI directly from the rejection reason without escalating to CSP support.

Use scenario #1.3 Customer sends CLI ported to CSP (successful)

  1. "Acme Logistics" makes an outgoing call with CLI 27848835500.
  2. PortaSwitch verifies that CLI is a valid number in E.164 format.
  3. PortaSwitch perfoms the number ownership check and identifies that the number has been ported to the CSP.
  4. CLI 27848835500 differs from numbers allowed to be used by "Acme Logistics", so PortaSwitch replaces the current CLI with account ID 27875501000.
  5. PortaSwitch validates that this number belongs to the CSP and is allowed to be used by "Acme Logistics", and the call is successfully authorized with CLI 27875501000.

Use scenario #1.4 Customer sends CLI ported to CSP (reject on the customer level)

  1. Continues after US#1.3 step 3.
  2. CLI 27848835500 differs from numbers allowed to be used by "Acme Logistics", so PortaSwitch replaces the current CLI with another CLI 27821005500 that was misatakenly configured for the account by reseller.
  3. PortaSwitch perfoms the number ownership check, identifies that the number 27821005500 neither belongs nor has been ported to the CSP.
  4. The call is rejected with the reason "SIP 603 Declined to Acme Logistics' PBX with reason: 'CLI 27821005500 does not match CSP network — LNP validation failed".

Use scenario #1.5 Customer sends CLI ported to CSP (alternative to #1.4: No customer level validation)

  1. Reseller requests CSP temporarily not to verify whether CLIs sent from "Acme Logistics" account 27875501000 are allowed to be used by this customer, while they are configuring and testing a new PBX setup for the customer.
  2. CSP Admin configures the account 27875501000 to skip verification whether CLIs sent from this account are allowed to be used by "Acme Logistics".
  3. "Acme Logistics" makes an outgoing call with CLI 27848835500.
  4. PortaSwitch verifies that CLI is a valid number in E.164 format.
  5. PortaSwitch perfoms the number ownership check and identifies that the number has been ported to the CSP.
  6. The call is successfully authorized with CLI 27848835500.

Use scenario #1.6 Customer makes an outgoing call which is forwarded back to PortaSwitch (successful)

  1. Starts with Use scenario #1.1 (successful CLI validation on outbound call with CLI 27872004001 to MTN number 27834009900).
  2. MTN's subscriber 27834009900 has a call forward configured to redirect to 27844567890 (a Cell C number).
  3. MTN redirects the call and sends it back to PortaSwitch, now destined for 27844567890, carrying the original CLI 27872004001 and a Diversion header referencing 27834009900.
  4. PortaSwitch verifies that incoming CLI 27872004001 is a valid number in E.164 format.
  5. PortaSwitch detects the Diversion header referencing 27834009900 and the number ownership check shows that it is a valid MTN number. Since the call is identified as a forwarded call from MTN, PortaSwitch allows the original CLI 27872004001 to bypass the incoming CLI ownership check.
  6. PortaSwitch routes the call onward to Cell C with CLI 27872004001 preserved.

Use scenario #1.7 Customer makes an outgoing call which is forwarded back to PortaSwitch (rejected, alternative to US#1.6)

  1. Starts with Use scenario #1.1 (successful CLI validation on outbound call with CLI 27872004001 to MTN number 27834009900).
  2. MTN's subscriber 27834009900 has a call forward configured to redirect to 27844567890 (a Cell C number).
  3. MTN redirects the call and sends it back to PortaSwitch, now destined for 27844567890, carrying the original CLI 27872004001 and a Diversion header referencing 27821002200. The Diversion header contains a wrong number — 27821002200 belongs to Vodacom, not MTN.
  4. PortaSwitch verifies that incoming CLI 27872004001 is a valid number in E.164 format.
  5. PortaSwitch detects the Diversion header referencing 27834009900, and the number ownership check shows that 27834009900 does not belong to MTN and it was not ported to MTN. 
  6. The call is rejected with the reason "Diversion header references a number not belonging to MTN South Africa network — call forward validation failed".

Use scenario #1.8 Customer makes an outgoing call using a leased CLI

  1. "Acme Logistics" makes an outgoing call with CLI 27831122334 (the number that CSP lease from MTN) to Vodacom subscriber 27821234567.
  2. PortaSwitch verifies that CLI is a valid number in E.164 format.
  3. PortaSwitch identifies that 27831122334 is a leased number allowed to be used by the CSP, even though it does not belong to the CSP, and it is allowed to be used by "Acme Logistics". 
  4. The call is successfully authorized with CLI 27831122334 and is routed only to MTN as defined in the account's routing plan.

Use case #2: CLI ownership check on incoming calls from operator

Roles: PortaSwitch, Operators, CSP Admin, Reseller, End users

Preconditions:

  • Same as in Use case 1, and additionally:
    • MTN has a transit agreement to carry another operator's "Lil SA" traffic to the CSP network, so CSP Admin has configured PortaSwitch to allow incoming calls from MTN with CLI belonging to Lil SA (2789). (new feature)

Use scenario #2.1 Operator sends CLI belonging to them (successful)

  1. MTN sends a calll with CLI 27834112233 to "Acme Logistics" account 27875501000.
  2. PortaSwitch verifies that CLI is a valid number in E.164 format.
    1. If CLI format validation fails, the call is rejected.
  3. PortaSwitch perfoms the number ownership check, identifies that the number 27875501000 belongs to MTN and has not been ported.
  4. The call with CLI 27875501000 is successfully authorized and is sent to the destination account 27875501000.

Use scenario #2.2 Operator sends CLI belonging to another operator (rejected)

  1. MTN sends a call with CLI 27824112233 to "Acme Logistics" account 27875501000.
  2. PortaSwitch verifies that CLI is a valid number in E.164 format.
  3. PortaSwitch perfoms the number ownership check, identifies that the number 27875501000 neither belongs to MTN not has not been ported.
  4. The call is rejected with the reason "CLI 27834112234 does not match MTN network — LNP validation failed".

Use scenario #2.3 Operator sends CLI ported to their network (successful)

  1. MTN sends a call with CLI 27849876543 to "Acme Logistics" account 27875501000.
  2. PortaSwitch verifies that CLI is a valid number in E.164 format.
  3. PortaSwitch perfoms the number ownership check, identifies that the number has been ported to MTN.
  4. The call with CLI 27849876543 is successfully authorized and is sent to the destination account 27875501000.

Use scenario #2.4 Operator sends CLI belonging to their authorized transit partner (successful)

  1. MTN sends a call with CLI 27891234567 to "Acme Logistics" account 27875501000.
  2. PortaSwitch verifies that CLI is a valid number in E.164 format.
  3. PortaSwitch perfoms the number ownership check, identifies that the number 27891234567 neither belongs nor has beed ported to MTN, but MTN is allowed to send it by the transit agreement.
  4. The call with CLI 27891234567 is successfully authorized and is sent to the destination account 27875501000.

Use scenario #2.5 Operator sends CLI belonging to unauthorized transit partner (rejected)

  1. MTN sends a call with CLI 27821009900 to "Acme Logistics" account 27875501000.
  2. PortaSwitch verifies that CLI is a valid number in E.164 format.
  3. PortaSwitch perfoms the number ownership check, identifies that the number 27821009900 neither belongs nor has beed ported to MTN. MTN is not allowed to send it.
  4. The call is rejected with the reason "CLI 27821009900 does not match MTN network or transit operator network — LNP validation failed".

Use scenario #2.6 Operator sends CLI ported to their authorized transit partner (successful)

  1. MTN sends a call with CLI 27821005500 to "Acme Logistics" account 27875501000.
  2. PortaSwitch verifies that CLI is a valid number in E.164 format.
  3. PortaSwitch perfoms the number ownership check, identifies that the number has been ported to Lil SA, and MTN is allowed to send Lil SA's numbers by the transit agreement.
  4. The call with CLI 27821005500 is successfully authorized and is sent to the destination account 27875501000.

Use scenario #2.7 Operator sends CLI belonging to unauthorized transit partner (rejected)

  1. MTN sends a call with CLI 27891009900 to "Acme Logistics" account 27875501000.
  2. PortaSwitch verifies that CLI is a valid number in E.164 format.
  3. PortaSwitch perfoms the number ownership check, identifies that the number 27891009900 doesn't belong to MTN, it was ported from Lil SA to Vodacom. MTN is not allowed to send it.
  4. The call is rejected with the reason "CLI 27891009900 does not match MTN network or transit operator network — LNP validation failed".

Use scenario #2.8 Incoming call from operator which is forwarded by customer (successful)

  1. Starts with Use scenario #2.1 (successful CLI validation on inbound call with CLI 27834112233 to 27875501000).
  2. Account 27875501000 is configured to forward calls to 27844567890 (a Cell C number) with displaying original caller number, meaning the call to Cell C will carry the original caller's CLI (27834112233) and a Diversion header: 27875501000. 
  3. PortaSwitch verifies that CLI 27834112233 is a valid number in E.164 format and performs a successful number ownership check.

  4. PortaSwitch detects the Diversion header (27875501000) and verifies that this number is a valid CSP account with configured call forwarding. 

  5. Because this is an authorized forwarded call, PortaSwitch applies the forwarded calls exception, which allows the original CLI belonging to a different operator (27834112233) to bypass the outbound number ownership check, confirming only its E.164 format.
  6. The call with CLI 27834112233 is successfully authorized and is sent to the destination account 27875501000.

Wireframes

N/A

Non-functional requirements

  1. The system must record the following data for every outbound call processed through CLI ownership check:

    • original CLI as received from the customer
    • result of CLI ownership check before applying customer's CLI modification settings
    • result of CLI ownership check after applying customer's CLI modification settings

    This information must be stored in the system for auditing and troubleshooting purposes.

Peculiarities

  1. CSP requests the number ownership check to be enabled at the operator connection level.
  2. CSP requests defining what number prefixes belong to what operator on the PortaBilling environment level and globally for the whole system, because evns are rented out to other operators with their own carriers; if no number ownership list is set up for an env, it should use the global list. The list should be updatable without system downtime or service interruption, as allocations may change on a monthly or even weekly basis.
  3. CSP must be able to add or remove allowed transit number prefixes easily for each operator. These changes should take effect without requiring maintenance, a service restart or any downtime.

  4. On CLI validation failure, PortaSWitch should return SIP 603 Declined with a Reason header that includes: the CLI that failed, the operator connection name, and the reason. The Reason text must use the operator connection's name (e.g. MTN) so that the rejection is self-explanatory in call traces. SIP 607 and 608 are under evaluation by CSP's technical team (Teuns Moolman) and may be added as configurable alternatives in a future iteration. Additional info about SIP headers provided by the CSP: 

    1. https://calleridreputation.com/blog/call-blocking-notifications-what-are-sip-codes-603-607-and-608/ 

    2. https://www.bandwidth.com/support/en/articles/13778049-sip-603-faq
  5. Number ownership check should be bypassed for calls to emergency numbers.
  6. Enabling/disabling number ownership check at any level must be configurable by the CSP administrator and cannot be modified by the reseller to prevent them from CLI manipulation.
  7. Authorized forwarded calls must bypass the strict outbound CLI ownership validation. If a call includes a valid Diversion header, and PortaBilling successfully verifies that the number in the Diversion header belongs to the CSP network and is authorized to forward calls, the original third-party CLI is allowed to pass.
  8. For outgoing calls where the routing list contains multiple connections, the behavior should be the same as for the existing "Route calls with valid CLI only" feature: if the CLI is identified as invalid, vendor connections that have this option enabled will be excluded from the routing list for this call.
  9. While calls from carriers like MTN, Vodacom, Cell C are expected to be made using an account under a wholesale Customer, some CSPs have these carriers configured as Vendors with VfV (VoIP from Vendor) connections. So they require the feature in VfV connections.
  10. Leased numbers: The CSP operates as a fixed-line operator under an ICASA licence and does not hold an independent mobile licence. CSP leases mobile numbers from MTN under a specific interconnect agreement. This agreement prohibits the CSP from routing calls presenting MTN-leased numbers as CLI directly through non-MTN vendor connections, such as Vodacom. To comply with the agreement, the CSP must route these calls through MTN, which handles onward transit and termination to other networks.
    The CSP’s PortaSwitch is already configured with a dedicated outgoing MTN connection for these calls. Accounts using MTN-leased numbers are assigned a routing plan that routes all outbound calls exclusively through this connection, regardless of the destination. The CSP needs CLI validation to recognise these leased numbers as authorised for use and allow the calls, even though the numbers are not owned by the CSP.

Performance / Clustering, Geo Redundancy/ Dual-Version, Porter / Call Control API / ESPF / Monitoring

N/A