Implementing Global Number Porting Workflows with Carrier Coordination and Cutover Planning

How-To-Articles
1

Implementing Global Number Porting Workflows with Carrier Coordination and Cutover Planning

What This Guide Covers

This guide details the architectural configuration required to execute a global number port from legacy carriers to Genesys Cloud CX while maintaining service continuity. You will configure port requests via the Admin UI or REST API, validate regulatory data integrity, and implement routing logic that handles the transition period without dropped calls. Upon completion, you will possess a standardized workflow for managing LNP (Local Number Portability) that minimizes downtime and ensures compliance with FCC Title 47 regulations across multiple jurisdictions.

Prerequisites, Roles & Licensing

Licensing Requirements

  • Genesys Cloud CX Subscription: Enterprise or Premium license tier is required to access the Porting tab in Admin settings. Standard Basic licenses do not support inbound number porting workflows.
  • Telephony Add-on: The specific Cloud Contact Center telephony module must be active for the target region (e.g., US, UK, Canada).

Granular Permissions

  • Role: Admin or Telephony Administrator.
  • Specific Scopes:
    • telephony:porting:request:create
    • telephony:porting:read
    • routing:plans:update
    • users:e911:edit (Required for E911 data migration)

External Dependencies

  • Letter of Authorization (LOA): Signed digital copy required from the current service provider.
  • Carrier Support Portal: Access to the legacy carrier’s porting dashboard to retrieve Account Numbers and PINs.
  • STIR/SHAKEN Compliance: Verification that the new routing plan supports attestation levels for the target region (e.g., AT&T or T-Mobile requirements).

External Integrations

  • CRM Integration: Ensure contact records associated with ported numbers are flagged for data migration to avoid legacy account confusion.

The Implementation Deep-Dive

1. Pre-Port Audit and Data Integrity Validation

Before initiating any carrier interaction, you must validate the metadata of the numbers to be ported. This step prevents rejection during the Request For Porting (RFP) phase. Regulatory bodies require exact matching of subscriber data between the requesting entity and the legacy carrier records.

Configuration Steps:

  1. Navigate to Admin > Telephony > Numbers.
  2. Export the current inventory list for the target region.
  3. Cross-reference the Subscriber Name, Billing Address, and E911 Location ID against the legacy carrier account statement.
  4. Verify LNP Status: Ensure numbers are not currently in a “Port Pending” state with another provider.

The Trap: The most common failure occurs during address validation. If the billing street address on the LOA does not match the legacy carrier’s database character-for-character, the port request will be rejected by the Central Office (CO).

  • Catastrophic Downstream Effect: A rejected port delays service migration by 4 to 6 weeks, forcing the organization to maintain dual infrastructure and incurring unnecessary cost.
  • Mitigation: Do not use abbreviations on LOAs that differ from the legacy carrier record (e.g., ensure “Street” is spelled out as “St.” or vice versa). Use a standard address normalization script before signing the LOA.

Architectural Reasoning:
We perform this audit locally because the porting API returns errors only after submission. The carrier validation logic happens asynchronously during the porting window. By validating data upfront, you reduce the risk of “Partial Ports” where some numbers arrive and others are rejected mid-transition.

2. Initiating the Port Request via REST API

While the Admin UI allows manual entry, automation is required for global deployments involving hundreds or thousands of numbers. The Genesys Cloud Porting API allows programmatic submission of port requests. This ensures a consistent data structure across all regions and creates an immutable audit trail.

API Endpoint: POST /api/v2/porting/requests
HTTP Method: POST
Content-Type: application/json

Production-Ready Payload:

{
  "name": "Port_Request_EMEA_Q3_2024",
  "status": "PENDING",
  "phoneNumbers": [
    {
      "phoneNumber": "+14155550100",
      "portDate": "2024-10-15T00:00:00Z",
      "accountNumber": "987654321",
      "billingAddress": {
        "addressLine1": "123 Market Street",
        "city": "San Francisco",
        "stateProvince": "CA",
        "postalCode": "94105",
        "country": "US"
      },
      "subscriberName": "ACME Corp Holdings LLC",
      "serviceType": "BUSINESS_LINE"
    }
  ],
  "carrierDetails": {
    "currentCarrierId": "legacy_carrier_us_east_01",
    "carrierAccountNumber": "987654321",
    "pin": "****-****-****"
  },
  "routingPlanId": "rp_porting_migration_v1",
  "metadata": {
    "projectCode": "INFRA_2024_MIGRATION",
    "complianceVerified": true
  }
}

Implementation Logic:
The phoneNumbers array must contain the full E.164 formatted numbers. The portDate should be scheduled during a low-traffic window, typically Sunday between 02:00 and 05:00 local time. The carrierDetails section is critical; the system validates the PIN against the legacy carrier’s API before accepting the request.

The Trap: Failing to include the routingPlanId in the payload.

  • Catastrophic Downstream Effect: The numbers are ported successfully but land on the default routing plan, which may lack specific skill-based routing or time-of-day rules required for business continuity. This results in immediate misrouted calls post-cutover.
  • Mitigation: Always map the routingPlanId explicitly to a pre-configured staging plan that mirrors the legacy routing logic but points to Genesys Cloud queues.

Architectural Reasoning:
We use the API rather than UI for bulk operations because the UI enforces a sequential processing model that is slower and prone to session timeouts during large batches. The API supports batched requests up to 100 numbers per call, reducing total transaction time significantly. Furthermore, the API response provides a unique portRequestId which serves as the correlation ID for all subsequent status polling operations.

3. Cutover Execution and Routing Logic

Once the porting request is approved by the legacy carrier, the actual number transfer occurs at the designated Port Date. The critical architectural decision here involves how you handle call routing during the transition window. You cannot simply flip a switch; you must implement a “Soft Cut-over” strategy to absorb signaling latency.

Configuration Steps:

  1. Create a Staging Routing Plan: This plan routes ported numbers to Genesys Cloud queues but includes a fallback branch.
  2. Configure Time-of-Day Rules: Set the cutover window within the routing plan.
  3. Enable Failover Logic: If Genesys Cloud returns a 503 Service Unavailable error during the porting process, route calls to a secondary destination (e.g., voicemail or legacy carrier).

Architectural Reasoning:
We implement this logic because number porting is not instantaneous at the signaling level. Even after the Porting API confirms completion, the SS7/Diameter signaling networks may take up to 24 hours to fully propagate globally. During this propagation window, calls may hit the old carrier or fail entirely. The routing plan acts as a buffer.

The Trap: Assuming immediate DNS or SIP registration synchronization upon port confirmation.

  • Catastrophic Downstream Effect: Calls arrive at the legacy carrier (which has already released the number) and fail with a “Number Not In Service” message, while the Genesys Cloud system believes it owns the number and routes calls to its own queues. This creates a black hole for inbound traffic.
  • Mitigation: Maintain a temporary parallel routing plan that points to the legacy carrier’s voice gateway for 48 hours post-port date. Monitor call volume; once traffic stabilizes on Genesys, remove the legacy fallback.

Fallback Routing Snippet (Genesys Cloud Architect):

<!-- Fallback Logic for Ported Number Range -->
<CallCondition>
    <TargetType>Queue</TargetType>
    <TargetId>queue_ported_numbers_main</TargetId>
    <Condition>
        <Expression>call.duration == 0 OR call.status == 'FAILED'</Expression>
    </Condition>
    <FallbackTarget>
        <TargetType>Number</TargetType>
        <TargetId>+14155559999</TargetId> <!-- Legacy Fallback Gateway -->
    </FallbackTarget>
</CallCondition>

Architectural Reasoning:
The call.duration == 0 check detects calls that are dropped immediately upon entry, indicating a signaling mismatch. Routing these to the legacy fallback allows you to verify if the number has fully cleared the old network before permanently severing ties.

Validation, Edge Cases & Troubleshooting

Edge Case 1: Partial Port Failures

The Failure Condition: A batch of 50 numbers is submitted for porting. 47 are successfully transferred to Genesys Cloud. 3 remain on the legacy carrier despite the port date passing.
The Root Cause: The 3 numbers were flagged as “Reserved” or “Port Blocked” due to outstanding billing disputes or fraud checks by the legacy carrier that were not visible in the initial data export.
The Solution: Do not attempt to force a port on these specific numbers. Isolate them in a separate routing plan. Contact the legacy carrier’s number porting department specifically for those account numbers. Update the portRequestId metadata in Genesys Cloud to mark these as “Blocked” so the system does not attempt to route live traffic to them during the cutover window.

Edge Case 2: E911 Data Drift During Porting

The Failure Condition: After porting, emergency services dispatchers receive an incorrect location address for calls placed from the new numbers.
The Root Cause: The E911 location data was not updated in Genesys Cloud before the cutover. While the number moves, the associated Location ID (LIDB) database updates lag behind. In some jurisdictions, this creates a mismatch where the caller is identified as being at the old address.
The Solution: Execute a PATCH request to update E911 location data immediately after port completion but before the cutover goes live. Ensure the locationId in Genesys Cloud matches the FCC LIDB record for the physical office location.

{
  "id": "e911_location_id_12345",
  "name": "New HQ Location",
  "address": {
    "streetAddress": "100 Main Street",
    "city": "Austin",
    "stateProvince": "TX",
    "postalCode": "78701"
  },
  "phoneNumbers": [
    "+15125550199"
  ]
}

Edge Case 3: STIR/SHAKEN Attestation Loss

The Failure Condition: Calls to customers are flagged as “Spam Likely” or blocked by recipient carriers after porting.
The Root Cause: The new carrier (Genesys) may not inherit the attestation level of the legacy carrier immediately. If the legacy carrier had a high SHAKEN attestation (Full Attestation), and the new routing plan does not support it, call trust scores drop.
The Solution: Verify the attestationLevel in the Genesys Cloud Telephony settings for the target region. Ensure that the STIR/SHAKEN signing keys are rotated properly during the porting process. If the legacy carrier signed calls with a specific certificate authority, ensure Genesys is configured to honor or re-sign these calls with the appropriate compliance level for the destination network.

Official References