Activate with Number Porting
Keep the customer's existing phone number while launching a new subscription through Connect.
This flow combines customer setup, order creation, number porting, async events, and final activation into a single guided journey.
Best for: Use this flow when you want to activate a new subscription but preserve the customer's current number through a port-in process.
What you will do
Before implementing this flow, complete the Quickstart, review Idempotency for safe retries on write operations, and read Mobile Number Portability for country-specific rules.
How the on-hold flow works
When you create an activation order with on_hold_condition: porting, Connect creates the subscription immediately but keeps the order in an on-hold state until the port-in completes. This gives your integration full control over when to initiate and finalize the porting process.
You are notified through the order.on_hold webhook that the subscription is ready. From there you can manually resume the order at any time via POST /orders/{order-id}/resume:
- If the port-in has completed, the subscription activates with the ported MSISDN.
- If the port-in has not completed, the subscription activates with a temporary MSISDN as a fallback.
Implementation steps
| Step | API call | Why it matters |
|---|---|---|
| 1. Choose the offer | List Product Offerings | Shows the plans and add-ons available to your tenant. |
| 2. Prepare the customer context | Create Account or reuse an existing account | Groups the customer relationship. |
| 3. Prepare the end user | Create Subscriber or reuse an existing subscriber | Represents the end user who will receive connectivity. |
| 4. Start activation on hold | Create Order with on_hold_condition: porting | Creates the subscription and keeps the order on hold. |
| 5. Initiate the port-in | Create Porting | Kicks off the port-in workflow with the donor operator. |
| 6. Track port-in progress | Webhooks — listen for porting.completed, porting.rejected, or porting.canceled | Confirms whether the number was ported successfully. |
| 7. Resume the order | Resume Order | Activates the subscription with the ported MSISDN, or falls back to a temporary MSISDN. |
Activation with porting
Activation with porting, step by step
Follow the exact partner journey from product selection to final activation. This view is designed to make the paused activation model easy to understand at a glance.
Fetch the product offering or reuse a locally cached version. Partners can cache product offerings for up to 24 hours to reduce API calls and improve performance, refreshing them periodically to stay up to date.
Generate the pre-contract summary that can be presented to the customer before service activation continues.
Create an account, or reuse an existing one if already created. This entity is required before placing any order.
Create a subscriber, or reuse an existing one if already created. This entity is required before placing any order.
Create the activation order with on_hold_condition=porting so Connect can prepare the subscription while pausing final activation.
Submit the number transfer request and track its lifecycle until the existing number is successfully ported.
Once porting completes, explicitly resume the order so Connect can continue the activation journey.
Connect delivers the final activation events confirming the product and subscription are now active.