Porting in Ireland

Porting in Ireland refers to the process of transferring your existing phone number from one carrier to another. There are a few key concepts you should be aware of throughout the porting process:

• Donor provider: The carrier that currently owns the number and will lose it once the porting is completed (the user's current provider).
• Recipient provider: The carrier that will receive the number once the porting is completed (managed through Gigs).
• SMS OTP Verification: A one-time password sent via SMS to the phone number being ported, used to verify that the user physically possesses the device; Number ownership is verified via SMS OTP by the recipient provider through a Gigs-managed flow before submitting the port request.

In Ireland, ports are regulated and designed to be straightforward. The porting process is initiated by the end user, who must verify ownership of their number through SMS OTP and provide account details based on their account type with their current provider.

Contents:

• Porting lifecycle, including End User Flow
• Information Required for a Port
• SMS OTP Verification
• Account Types
• Implementation Options
• Timing considerations
• End user communications

Porting Lifecycle

End User Flow

Below is an overview of the porting process:

1. User wants to bring their phone number to their new phone plan.
2. You collect the required porting information based on the user's account type (see section Account Types).
3. Request the porting:
   • with a new subscription: You create a porting with the phone number and all required information (account type, account holder name, account number if applicable, and donor provider) and create a subscription through the API and reference the porting, or
   • with an existing active subscription: request a port for an existing subscription and reference the porting.
4. A consent request is automatically created and an SMS with a one-time password (OTP) is sent to the user's phone number to verify ownership. The porting status changes to initiated.
5. User receives the SMS OTP on their phone and provides it to you.
6. You call the approve consent request endpoint with the OTP code to confirm ownership.
7. Once the OTP is verified, the porting status moves from initiated to pending.
8. Gigs submits the port to the donor provider and the porting status moves from pending to requested.
9. The donor provider approves the port and releases the phone number.
10. The status of the porting moves to completed and Gigs activates the subscription with the ported phone number.
11. The user cancels their subscription with their donor provider if needed.

Lifecycle of the Porting Object

The porting process is modeled on the Gigs APIs through the porting object. For a detailed description of the porting object and its lifecycle, refer to the Porting Lifecycle section in How Porting in Works.

On the duration of the porting process:

The porting process duration in Ireland varies depending on the donor provider's processing time. Once all information is correctly submitted and the SMS OTP is verified, the port is submitted to the donor provider for processing.

SMS OTP Verification

Ireland requires verification that the user physically possesses the phone with the number being ported. This verification happens after the porting is added to a subscription and before the port-in request is submitted to the donor provider.

Once the user receives the OTP, call the approve consent request endpoint to verify it:

curl --request POST \
  --url "https://api.gigs.com/projects/${GIGS_PROJECT}/consentRequests/${CONSENT_REQUEST_ID}/approve" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer ${GIGS_TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "code": "123456"
  }'

Once the consent request is approved, the porting status will change from initiated to pending (assuming all required information was provided when creating the porting).

Account Types

Ireland requires information about the user's account type with their current provider. This information determines which additional fields are required.

Available Account Types

When creating or updating the porting, you must specify the accountType field with one of these values.

Multiline Accounts

If a user is on a multiline account (account type postpaidMulti), they can still port a single line to Gigs. The multiline flag is informational and passed to the provider for processing. No special handling is required on your end.

Information Required for a Port

Below is the information that is required to submit a port in Ireland. The exact attributes required for a porting are listed in the required attribute of the porting object.

Always Required:

• Phone number: Number that the user wants to bring to their new subscription
• Account type: One of prepaidUnregistered, prepaidRegistered, postpaidSingle, or postpaidMulti
• SMS OTP verification: Completed via consent request approval
• Account holder name: Name of the account holder for the user's current carrier
• Donor provider: User's current carrier
• Recipient provider: p32

Conditionally Required:

• Account number: Required for registered prepaid and all postpaid accounts (prepaidRegistered, postpaidSingle, postpaidMulti)

Implementation Options

There are two options when it comes to implementing porting: building a custom porting flow using the Gigs API, or leveraging the low-code Gigs' Connect Sessions completePorting Intent (recommended for most customers).

API

Using the API is an option for those that want the design to be native in their app. See below for what is required to successfully build out a porting flow:

API Endpoints to Use:

1. List all service providers (when calling this endpoint filter for Ireland only providers)
2. Create a porting with phone number, account type, account holder name, account number (if applicable), and donor provider
3. Create a subscription or request port-in for existing subscription - this triggers the consent request creation and SMS OTP
4. Monitor the automatically created consent request
5. Approve the consent request with the user-provided OTP
6. Cancel a porting (if needed)

Additional Information to Note:

We recommend surfacing instructions for how to retrieve the necessary credentials (account number) from key donor providers and embed them in your application.

If a user's service provider does not appear in the returned list of service providers, an option labeled "Other (unlisted provider)" is available in the response and can be used for such cases.

For additional information on how to implement the Porting API, refer to the section How Porting In Works.

Connect Sessions completePorting Intent

The completePorting Intent consists of a fully templated porting experience, hosted by Gigs. You can show the completePorting event in a webview in your application. With the Gigs completePorting Intent, the SMS OTP verification, account type selection, donor carrier list, and donor-specific port out instructions are handled automatically and kept up to date by Gigs.

After creating a draft porting, redirect the user to the Connect Session. The Connect Session will:

• Handle the SMS OTP verification flow automatically
• Present the account type selection
• Show the required input fields based on the selected account type
• Provide details about the donor provider

API Endpoints To Use:

1. Create a draft porting
2. Create a Connect Session with Intent: completePorting and redirect the user to the Connect Sessions URL
3. The Connect Session handles SMS OTP verification and information collection
4. Create a subscription once the porting information is complete

Additional Information to Note:

The completePorting intent handles the SMS OTP verification flow and most common decline codes automatically.

If a user's service provider does not appear in the returned list of service providers, an option labeled "Other (unlisted provider)" is available in the response and can be used for such cases.

To create consistency in styling between your application and the Connect Session completePorting intent, the button colors and logo are customizable.

For a more complete reference of the completePorting intent, please refer to Intent: completePorting in the Connect sessions documentation.

Timing Considerations

When should you collect information from the end user?

Ireland's porting process requires SMS OTP verification after the porting is added to a subscription, which impacts the collection flow:

When should the user be charged for the subscription?

When should the user be prompted to download their eSIM?

End-User Communications

Porting lifecycle communication: Status and Decline Codes

Based on the status and the decline code of the port, you should send specific communication with a Call-to-Action to the end user. This ensures your users know when to take which action, helping to expedite the porting process and reduce the need for customer support intervention.

We recommend communication for the following stages of the porting lifecycle:

• SMS OTP sent (prompt user to check their phone and verify quickly)
• SMS OTP expired or porting failed (user needs to restart the porting process with a new porting)
• Porting requested
• Porting status is informationRequired for 1 day
• Porting status is informationRequired for 2 days
• Porting status is informationRequired for 3 days
• Porting status is declined for 1 day
• Porting status is declined for 2 days
• Porting status is declined for 4 days
• Porting completed

We are happy to provide templated communication for the different steps in the porting lifecycle through your primary Gigs contact or support@gigs.com.

Using Gigs webhooks to send porting lifecycle communication

We proactively inform you of all status changes of a porting through our webhooks, so you can trigger communication to your end user. You can configure a webhook endpoint in the developers section of the Gigs Dashboard. Once there, you can add an endpoint and set the URL where the requests should be sent to. You can also select which events you'd like to receive on this endpoint.

The following event types are relevant for number porting:

• com.gigs.porting.canceled
• com.gigs.porting.completed
• com.gigs.porting.created
• com.gigs.porting.declined
• com.gigs.porting.deleted
• com.gigs.porting.expired
• com.gigs.porting.informationRequired
• com.gigs.porting.requested
• com.gigs.porting.updated

Additionally, consent request events are relevant for tracking SMS OTP verification:

• com.gigs.consentRequest.approved
• com.gigs.consentRequest.created
• com.gigs.consentRequest.declined
• com.gigs.consentRequest.expired