Implementing Number Migration Coordination Workflows with Carrier and Platform Timing

How-To-Articles
1

Implementing Number Migration Coordination Workflows with Carrier and Platform Timing

What This Guide Covers

This guide details the exact workflow for synchronizing carrier port requests with Genesys Cloud CX and NICE CXone telephony provisioning to execute zero-downtime DID migrations. By the end, you will have a validated orchestration process that aligns carrier activation windows with platform routing updates, ensures failover readiness, and prevents call drops during cutover.

Prerequisites, Roles & Licensing

  • Licensing Tier: Genesys Cloud CX 1+ (Core Telephony), CX 3+ (Advanced Routing, Architect Flow Management), CXone CX 1+ (Telephony & Number Management)
  • Platform Permissions:
    • Telephony > Trunk > Edit
    • Telephony > DID > Manage
    • Telephony > Porting > Manage (Genesys), Telephony > Number Management > Configure (NICE)
    • Architect > Flow > Edit / Routing > Queue > Edit
  • OAuth Scopes: telephony:manage, telephony:porting:write, routing:flow:edit, admin:manage, telephony:phonenumbers:write
  • External Dependencies: Carrier LOA/LOC XML/JSON schema templates, SS7/SIP trunk provider API access, DNS SRV record propagation verification tool, WFM integration endpoint (optional for skill/group synchronization)

The Implementation Deep-Dive

1. Pre-Port Validation & LOA/LOC Generation Automation

Before submitting a port request, you must validate number eligibility and generate carrier-compliant Letters of Authorization (LOA) and Letters of Consent (LOC). Manual generation introduces formatting errors that cause losing carriers to reject requests, delaying migration by three to five business days. The platform must enforce schema validation against the specific carrier template before any external submission occurs.

You configure a validation pipeline that cross-references the target DID ranges against the platform’s existing number inventory. The pipeline checks for overlapping assignments, verifies that numbers are not currently bound to active SIP registrations, and confirms that the account name and address on file match the subscriber records exactly. Mismatched address fields are the most frequent cause of LOA rejection. You must normalize address data to match the FCC LATA/NPA-NXX registry format before injecting it into the carrier template.

The Trap: Assuming generic LOA templates satisfy all losing carriers. Each carrier enforces distinct XML namespaces, digital signature algorithms, and attachment requirements. Submitting a generic template to a carrier that requires SHA-256 signed PDFs with embedded XML metadata results in automatic rejection. The downstream effect is a cascading delay that forces you to run parallel routing trees for weeks, increasing operational cost and agent confusion.

Architectural Reasoning: We automate LOA generation through a serverless function or middleware service that pulls subscriber data from the platform via API, maps it to the carrier-specific schema, and applies cryptographic signing before storage. This approach ensures auditability and eliminates human transcription errors. You store the validated LOA in a versioned object storage bucket with an immutable retention policy to satisfy compliance requirements (PCI-DSS, HIPAA, or SOC 2 depending on your vertical).

POST /api/v2/telephony/porting/portrequests
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "losingCarrier": {
    "name": "LegacyTelco",
    "code": "LT-9942",
    "templateVersion": "v3.1"
  },
  "accountInfo": {
    "accountId": "ACCT-8847291",
    "legalName": "Enterprise Holdings Inc.",
    "billingAddress": {
      "street": "1200 Commerce Drive Suite 400",
      "city": "Austin",
      "state": "TX",
      "postalCode": "78701",
      "country": "US"
    }
  },
  "numbers": [
    "+15125550100",
    "+15125550101",
    "+15125550102"
  ],
  "requestedActivationDate": "2024-03-15T14:00:00Z",
  "contactInfo": {
    "name": "Network Operations Center",
    "email": "noc@enterprise.com",
    "phone": "+15125550999"
  }
}

The payload above initiates a port request draft within Genesys Cloud. You must verify the response contains a portRequestId and a status of DRAFT. You then attach the cryptographically signed LOA document via the platform’s attachment endpoint before transitioning the request to SUBMITTED. In NICE CXone, the equivalent workflow uses the POST /api/v2/telephony/number/porting endpoint with a nearly identical structure, though NICE requires the losingCarrierCode to match their internal carrier registry exactly.

2. Carrier Port Request Submission & Activation Window Alignment

Once the LOA is validated, you submit the port request to the losing carrier. The carrier responds with a scheduled activation window, typically spanning twenty-four to forty-eight hours. This window is not a suggestion. It is a hard dependency that dictates when the platform routing configuration must change. You must treat the activation window as a synchronized lock step between external telephony infrastructure and internal routing logic.

You configure a polling mechanism or webhook listener that monitors the port request status. The platform returns status codes such as PENDING_CARRIER, ACCEPTED_BY_CARRIER, SCHEDULED, and ACTIVATED. You map these statuses to internal workflow states. When the status transitions to SCHEDULED, you extract the activationWindowStart and activationWindowEnd timestamps. You then calculate the exact cutover time by subtracting a fifteen-minute buffer from the activationWindowEnd timestamp. This buffer accounts for carrier signaling latency and DNS propagation delays.

The Trap: Scheduling platform routing changes before the carrier activation window closes. Carriers often delay activation by up to four hours within the window. If you toggle platform routing at the start of the window, incoming calls route to the new platform while the carrier still points to the legacy infrastructure. This creates a routing loop where the carrier rejects the call with a SIP 403 Forbidden, and the platform drops the media stream. The result is a complete service outage for the ported range.

Architectural Reasoning: We implement a conditional routing toggle that remains inactive until the carrier confirms activation. You build a parallel routing tree in Architect that mirrors the legacy flow but points to the new trunk and queue configuration. The toggle uses a time-based switch node combined with a status check against the porting API. The flow evaluates the carrier status and the current timestamp. Only when both conditions match does the flow route to the new infrastructure. This approach guarantees atomic cutover and eliminates the risk of premature routing changes.

GET /api/v2/telephony/porting/portrequests/{portRequestId}
Authorization: Bearer <access_token>

// Response fragment
{
  "id": "pr-8847291-001",
  "status": "SCHEDULED",
  "activationWindow": {
    "start": "2024-03-15T12:00:00Z",
    "end": "2024-03-16T12:00:00Z"
  },
  "estimatedActivationTime": "2024-03-15T18:30:00Z",
  "carrierConfirmationCode": "LT-CONF-99281"
}

You store the estimatedActivationTime in a configuration store accessible to the Architect flow. In the flow, you use a Condition node with the expression {{ currentTime >= scheduledCutoverTime && portStatus == "ACTIVATED" }}. This expression ensures the flow only switches when the carrier has confirmed activation and the platform clock has reached the calculated cutover time. You must synchronize platform NTP servers to within fifty milliseconds of UTC to prevent timestamp drift from triggering premature cutover.

3. Platform DID Provisioning & Routing Pre-Staging

Before the carrier activates the port, you provision the DIDs within the platform as reserved numbers. You assign these DIDs to a staging trunk and configure them to route to a temporary queue or voicemail bucket. This step validates SIP signaling paths, TLS certificates, and codec negotiation without impacting live traffic. You verify that the platform can register, authenticate, and establish media streams for each number in the ported range.

You configure the staging trunk with identical SRTP settings, DTMF relay methods, and codec preferences as the production trunk. You disable call forwarding and hunt group routing on the staging DIDs. You then execute a batch SIP OPTIONS test against each number to verify registration stability. You log any SIP 408 Request Timeout or 488 Not Acceptable Here responses. These errors indicate trunk misconfiguration or firewall rule conflicts that must be resolved before cutover.

The Trap: Assigning ported DIDs to active production queues before activation. When the carrier has not yet transferred routing, incoming calls still arrive at the legacy infrastructure. If the platform claims ownership of the DIDs prematurely, it attempts to register them on the new trunk. The carrier rejects the registration because the numbers are not yet ported. This generates SIP registration storms that saturate the trunk capacity and trigger carrier-level rate limiting. The downstream effect is degraded performance for unrelated traffic sharing the same trunk.

Architectural Reasoning: We isolate ported DIDs in a dedicated staging environment until activation confirms ownership transfer. You create a separate Trunk object labeled STAGING-MIGRATION-{PORT_ID} with a distinct IP address range and credential set. You assign the reserved DIDs to this trunk and configure them to route to a Queue named MIGRATION-VALIDATION-{PORT_ID}. This queue contains no agents. It only records calls to a secure storage bucket for audit purposes. This architecture allows you to validate end-to-end signaling while maintaining strict isolation from production traffic.

POST /api/v2/telephony/phone-number-configs
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "numbers": [
    "+15125550100",
    "+15125550101",
    "+15125550102"
  ],
  "trunkId": "trunk-staging-migration-8847",
  "routingType": "QUEUE",
  "queueId": "queue-validation-8847",
  "isPorted": true,
  "portRequestId": "pr-8847291-001",
  "metadata": {
    "environment": "STAGING",
    "migrationPhase": "PRE_ACTIVATION",
    "validationTimestamp": "2024-03-14T10:00:00Z"
  }
}

The payload above reserves the DIDs and binds them to the staging trunk. You must verify the response returns a 201 Created status with matching phoneNumberConfigId values. In NICE CXone, you use the POST /api/v2/telephony/number/configurations endpoint with the routingProfileId parameter instead of queueId. The architectural principle remains identical: isolate, validate, then promote. You run SIP OPTIONS tests against the staging DIDs using a script that iterates through the number list and logs response codes. Any number returning a non-2xx status requires immediate trunk or firewall investigation before proceeding.

4. Cutover Execution & Synchronization Orchestration

When the carrier confirms activation, you execute the cutover sequence. The sequence consists of three atomic steps: update DNS SRV records or trunk failover priorities, toggle the Architect flow switch, and verify call routing. You must execute these steps in strict order. Parallel execution causes routing inconsistencies and call drops. You schedule the cutover during a low-traffic window to minimize blast radius if rollback becomes necessary.

You begin by updating the trunk failover configuration. You set the production trunk priority to 1 and the staging trunk priority to 2. You configure failover thresholds to trigger after three consecutive SIP 408 timeouts. This configuration ensures that if the production trunk experiences signaling degradation during cutover, traffic automatically routes to the validated staging environment. You then update the DNS SRV records for the SIP domain to point to the new platform edge IP addresses. You verify propagation using a DNS lookup tool that queries multiple global resolvers.

The Trap: Executing routing changes without a staggered activation. Updating all routing rules simultaneously causes a SIP registration storm where every agent endpoint attempts to re-register to the new trunk. The trunk capacity saturates, causing legitimate incoming calls to receive SIP 503 Service Unavailable responses. The downstream effect is a complete inbound service outage lasting fifteen to thirty minutes until registration storms subside.

Architectural Reasoning: We implement a staggered rollout that updates routing configuration in incremental batches. You divide the ported DIDs into groups of fifty. You update the routing configuration for the first group, wait for SIP registrations to stabilize, then proceed to the next group. You monitor trunk capacity metrics and agent registration status in real time. If capacity exceeds eighty percent or registration failures exceed five percent, you pause the rollout and allow the platform to absorb the load. This approach prevents trunk saturation and maintains service continuity.

PATCH /api/v2/telephony/phone-number-configs/batch
Authorization: Bearer <access_token>
Content-Type: application/json

[
  {
    "phoneNumberConfigId": "pnc-001",
    "trunkId": "trunk-prod-primary",
    "routingType": "QUEUE",
    "queueId": "queue-prod-main",
    "isPorted": true,
    "portRequestId": "pr-8847291-001"
  },
  {
    "phoneNumberConfigId": "pnc-002",
    "trunkId": "trunk-prod-primary",
    "routingType": "QUEUE",
    "queueId": "queue-prod-main",
    "isPorted": true,
    "portRequestId": "pr-8847291-001"
  }
]

The batch update payload promotes the DIDs from staging to production routing. You execute this payload in increments, monitoring the Telephony > Trunk > Metrics dashboard for call volume spikes and registration latency. You verify each batch by placing a test call to a number in the group and confirming it routes to the correct queue. You document the verification results in a migration log. If any number fails routing, you isolate it, revert its configuration to the staging trunk, and investigate the root cause before proceeding. In NICE CXone, you use the PATCH /api/v2/telephony/number/configurations endpoint with the same batch structure, substituting trunkId with connectionId where applicable.

Validation, Edge Cases & Troubleshooting

Edge Case 1: Partial Port Failure & Split Number Ranges

The failure condition: The losing carrier activates only a subset of the requested DIDs. The remaining numbers stay on the legacy infrastructure due to regulatory holds or ownership disputes.
The root cause: Carriers frequently split port requests when they detect conflicting ownership records, active contracts, or regulatory compliance flags. The platform receives an ACTIVATED status for the batch but only processes the successful numbers. The failed numbers remain bound to the legacy trunk.
The solution: You configure the porting workflow to parse the activation response at the individual number level. You extract the activatedNumbers array and compare it against the original request. You automatically route successfully ported numbers to the production configuration. You leave failed numbers on the staging trunk and generate a remediation ticket for the telecom operations team. You update the routing flow to check number status before switching, ensuring partial failures do not impact the successful subset.

Edge Case 2: Carrier Activation Delay & Platform Routing Timeout

The failure condition: The carrier delays activation beyond the scheduled window. The platform cutover timer expires, but the carrier has not transferred routing. Incoming calls continue to fail.
The root cause: Carrier provisioning teams often miss internal deadlines due to staffing shortages or legacy switching equipment maintenance. The platform’s time-based switch node evaluates to false, leaving traffic in a limbo state.
The solution: You implement an extension handler that automatically requests a new activation window from the carrier API when the original window expires. You update the platform cutover timestamp to match the new window. You configure a fallback routing path that answers calls with a recorded message explaining the migration delay and provides alternative contact methods. This approach prevents call drops and maintains customer communication during extended delays.

Edge Case 3: SIP TLS Certificate Mismatch During Cutover Window

The failure condition: Calls fail with SIP 493 Unacceptable Here or media drops immediately after cutover. The platform logs certificate validation errors.
The root cause: The staging trunk and production trunk use different TLS certificates or cipher suites. When DIDs migrate, the platform attempts to negotiate media using the production certificate. The carrier edge rejects the handshake because the certificate does not match the registered CN/SAN values.
The solution: You enforce identical TLS configurations across staging and production trunks. You deploy the same certificate chain to both environments before cutover. You validate cipher suite compatibility using an OpenSSL s_client test against the carrier edge IP. You configure the platform to accept the carrier’s intermediate CA during the migration window to prevent strict validation failures. After cutover completes, you revert to strict validation mode.

Official References