# 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][porting-lifecycle], including End User Flow
- [Information Required for a Port][information-required-for-a-port]
- [SMS OTP Verification][sms-otp-verification]
- [Account Types][account-types]
- [Implementation Options][implementation-options]
- [Timing considerations][timing-considerations]
- [End user communications][end-user-communications]

[porting-lifecycle]: #porting-lifecycle
[information-required-for-a-port]: #information-required-for-a-port
[sms-otp-verification]: #sms-otp-verification
[account-types]: #account-types
[implementation-options]: #implementation-options
[timing-considerations]: #timing-considerations
[end-user-communications]: #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][account-types]).
3. Request the porting:
    - with a new subscription: You [create a porting][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][create-a-subscription] through the API and reference the porting, or
    - with an existing active subscription: [request a port for an existing subscription][port-in-a-subscription] and reference the porting.
5. A [consent request][consent-requests] 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`.
6. User receives the SMS OTP on their phone and provides it to you.
7. You call the [approve consent request][approve-consent-request] endpoint with the OTP code to confirm ownership.
8. Once the OTP is verified, the porting status moves from `initiated` to `pending`.
9. Gigs submits the port to the donor provider and the porting status moves from `pending` to `requested`.
10. The *donor provider* approves the port and releases the phone number.
11. The `status` of the porting moves to `completed` and Gigs activates the subscription with the ported phone number.
12. The user cancels their subscription with their *donor provider* if needed.

[create-a-porting]: /core/portings#create-a-porting
[create-a-subscription]: /core/subscriptions#create-a-subscription
[port-in-a-subscription]: /core/subscriptions#port-a-phone-number-into-a-subscription
[consent-requests]: /core/consent-requests
[approve-consent-request]: /core/consent-requests#approve-a-consent-request

### Lifecycle of the Porting Object

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

[porting-in-lifecycle]: /docs/porting/how-porting-in-works#porting-lifecycle
[porting]: /core/portings
[porting-in]: /docs/porting/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][approve-consent-request] endpoint to verify it:

<CodeGroup title="Approve a consent request with OTP">

```shell
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"
  }'
```

</CodeGroup>

<Note type="warning">
  The OTP expires after 15 minutes. If the OTP expires and is not approved, the porting will fail. You must create a new porting to restart the process and receive a new OTP.
</Note>

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

| Account Type | Description | Account Number Required? |
| --- | --- | --- |
| `prepaidUnregistered` | Prepay (Unregistered) - An unregistered pay-as-you-go account | No |
| `prepaidRegistered` | Prepay (Registered) - A registered pay-as-you-go account | Yes |
| `postpaidSingle` | Bill Pay (Single User) - A postpaid contract for a single line | Yes |
| `postpaidMulti` | Bill Pay (Multi User) - A postpaid contract with multiple lines | Yes |

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

<Note type="warning">
  The `accountNumber` field is only required when the account type is `prepaidRegistered`, `postpaidSingle`, or `postpaidMulti`. For `prepaidUnregistered` accounts, no account number is needed.
</Note>

### 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`)

<Note type="warning">
  Unlike the UK and US, Ireland does **not** require a transfer PIN (PAC/STAC or account PIN). Do not collect or submit PIN information for Ireland port-ins.
</Note>

## Implementation Options

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

[option-api]: #api
[option-intent]: #connect-sessions-complete-porting-intent

### 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][service-providers] (when calling this endpoint filter for Ireland only providers)
2. [Create a porting][create-a-porting] with phone number, account type, account holder name, account number (if applicable), and donor provider
3. [Create a subscription][create-a-subscription] or [request port-in for existing subscription][port-in-a-subscription] - this triggers the consent request creation and SMS OTP
4. Monitor the automatically created [consent request][consent-requests]
5. [Approve the consent request][approve-consent-request] with the user-provided OTP
6. [Cancel a porting][cancel-a-porting] (if needed)

<Note type="info">
  Alternatively, you can [create a draft porting][create-a-porting] with minimal information, then [update the porting][update-a-porting] later with additional details before creating the subscription.
</Note>

[service-providers]: /core/portings#list-all-service-providers
[cancel-a-porting]: /core/portings#cancel-a-porting
[update-a-porting]: /core/portings#update-a-porting

**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][porting-in].

### 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.

<Note type="info">
  We recommend the majority of customers to use the Connect Sessions `completePorting` Intent, especially for Ireland where the SMS OTP flow is automatically managed.
</Note>

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][create-a-porting]
2. [Create a Connect Session][creating-connect-sessions] with [Intent: completePorting][complete-porting] and redirect the user to the Connect Sessions URL
3. The Connect Session handles SMS OTP verification and information collection
4. [Create a subscription][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.

<Note type="info">
  If a Connect Session is created with a non-applicable declinedCode, Connect will immediately redirect the user back to the callbackUrl with the `bad_configuration` status code. If no `callbackUrl` is provided, Connect will display an error screen.
</Note>

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][complete-porting] in the [Connect sessions documentation][connect-sessions].

[complete-porting]: /docs/connect/connect-sessions/intent-completeporting
[creating-connect-sessions]: /docs/connect/connect-sessions/creating-connect-sessions
[connect-sessions]: /docs/connect/connect-sessions/about

## 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:

| User information to collect *before* payment | User information to collect *after* payment |
|-----------------------------------|-----------------------------------|
| Phone number: Number that the user wants to bring to their new subscription | SMS OTP verification: User must verify they control the number (after subscription is created) |
| Donor provider: User's current carrier | |
| Account type: The type of account the user has with their current provider | |
| Account holder name: Name of the account holder for the user's current carrier | |
| Account number: Required for registered accounts (user may need to obtain from current carrier) | |

<Note type="info">
  You can collect account type and account number before payment, but the SMS OTP verification can only happen after the porting is added to a subscription (either a new subscription or an existing one).
</Note>

**When should the user be charged for the subscription?**

|         | Pros                              | Cons                              |
|---------------|-----------------------------------|-----------------------------------|
| Before the subscription is created, after collecting basic porting information. You could take the payment or authorize (hold) the funds. (*recommended*) | This ensures a higher likelihood that the user will follow through to complete the SMS OTP verification and port since they have already committed money to the new subscription. | If the port cannot be completed, the payment will require a refund or cancellation. |
| After the port has successfully completed. | The user will not be paying for the new subscription for a period of time where they do not have connectivity. | There is less incentive for the user to follow through with their purchase and complete the SMS OTP verification. |

**When should the user be prompted to download their eSIM?**

|         | Pros                              | Cons                              |
|---------------|-----------------------------------|-----------------------------------|
| Once the port has been successfully processed and is complete (*recommended*) | Least confusing flow for the end user. It also ensures that the end user swiftly resolves any issues that may arise during the porting process. | The user needs to be connected to WiFi to download their eSIM and might experience a period of no service if they are not. |
| Right after submission of the port info, and before the port is complete | The user will not have any connectivity downtime, as their eSIM will automatically start working once the port is complete. | It may cause confusion and loss of connectivity, as the user may try to use this SIM before it is active and deactivate their old SIM. |

<Note type="info">
  For information on handling porting declines and testing portings, refer to the [How Porting in Works][porting-in] guide. Ireland uses the same decline codes and testing approach as other countries.
</Note>

## 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][support@gigs.com].

[support@gigs.com]: mailto: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][developers]. 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.

<Note type="info">
  Detailed information about how to set up webhooks can be found in our documentation on [Events and Webhooks][events-and-webhooks].
</Note>

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`]

[events-and-webhooks]: /docs/core/events/events-webhooks
[developers]: https://dashboard.gigs.com/developers
[`com.gigs.porting.canceled`]: /events/schemas/com.gigs.porting.canceled
[`com.gigs.porting.completed`]: /events/schemas/com.gigs.porting.completed
[`com.gigs.porting.created`]: /events/schemas/com.gigs.porting.created
[`com.gigs.porting.declined`]: /events/schemas/com.gigs.porting.declined
[`com.gigs.porting.deleted`]: /events/schemas/com.gigs.porting.deleted
[`com.gigs.porting.expired`]: /events/schemas/com.gigs.porting.expired
[`com.gigs.porting.informationRequired`]: /events/schemas/com.gigs.porting.informationRequired
[`com.gigs.porting.requested`]: /events/schemas/com.gigs.porting.requested
[`com.gigs.porting.updated`]: /events/schemas/com.gigs.porting.updated
[`com.gigs.consentRequest.approved`]: /events/schemas/com.gigs.consentRequest.approved
[`com.gigs.consentRequest.created`]: /events/schemas/com.gigs.consentRequest.created
[`com.gigs.consentRequest.declined`]: /events/schemas/com.gigs.consentRequest.declined
[`com.gigs.consentRequest.expired`]: /events/schemas/com.gigs.consentRequest.expired