How Porting Out Works
Occasionally, a user might want to end their subscription, but keep their existing number by porting it to a new provider. In this case, the user will require credentials to authenticate the porting with the recipient provider.
In the Gigs API, this is managed using the port out resource.
Porting Out Process
1. Create a port out
To initiate the port out process, create a new port out for the subscription. The port out needs to be created before a subscription has ended.
Create a port out
curl --request "POST" \
--url "https://api.gigs.com/projects/${GIGS_PROJECT}/portOuts" \
--header "Accept: application/json" \
--header "Authorization: Bearer ${GIGS_TOKEN}" \
--header "Content-Type: application/json" \
--data '{
"subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi"
}'
Port outs are created in a processing state.
A processing port out
{
"object": "portOut",
"id": "pto_0SNlurA049MEWV4DWEaT4SaeDI8s",
"status": "processing",
...
}
If your project requires user consent, the port out will be created in an initiated state, and the user will need to give consent before the port out will transition to processing. See the User Consent section below for more details.
2. Wait for the port out to be issued
After the port out has been created, our system will process it, and issue credentials on the provider.
Once the credentials have been issued, you will receive a portOut.issued event.
An issued port out
{
"object": "portOut",
"id": "pto_0SNlurA049MEWV4DWEaT4SaeDI8s",
"status": "issued",
...
}
It is also possible to check the status of the port out using the Gigs API. A port out can be retrieved using the /projects/{project}/portOuts/{portOut} endpoint, or port outs can be listed using /projects/{project}/portOuts (with an optional filter using the subscription query parameter).
3. Retrieve & share the port out credentials with the user
Once the port out has been issued, you can retrieve the credentials and share them with the user.
Retrieve port out credentials
curl --request GET \
--url "https://api.gigs.com/projects/${GIGS_PROJECT}/portOuts/${PORT_OUT_ID}/credentials" \
--header "Accept: application/json" \
--header "Authorization: Bearer ${GIGS_TOKEN}"
Port out credentials
{
"object": "portOutCredentials",
"accountNumber": "123456789",
"accountPin": "1234",
"portOut": "pto_0SNlurA049MEWV4DWEaT4SaeDI8s"
}
Port out credentials expire after a given time, as indicated by the expiredAt time on the port out. If the credentials have expired and the user still wants to port out, a new port out must be created.
User Consent
Depending on the settings of your project, the user might need to explicitly give consent before the port out credentials will be issued. Whether or not this is required depends on the region in which the subscription is sold, among other factors. Please reach out to support@gigs.com for assistance or more details on the configuration of your project.
If user consent is required, the port out will be created with a status of initiated, and the user will receive a consent request via email or SMS. Email consent requests include a magic link that the user must follow to give consent. Users must respond with "yes" to an SMS consent request to approve it.
If the user accepts this request, the port out status will be updated to processing, and the Porting Out Process will proceed as documented above.
If the user does not accept the request in 5 hours, it expires and the port out status will be updated to failed. Once a port out is in the failed state, it can no longer be issued and, if needed, a new port out must be created to restart the process.
Port Out Lifecycle
Initiated
Indicates that the port out requires further input (e.g. user consent) before it can be processed.
Failed
Indicates that the port out credentials could not be issued.
Processing
Indicates that the port out is being processed by our system and the provider. Usually, this only takes a few seconds.
Issued
Indicates that the port out credentials have been issued by the provider, and can be retrieved and used.
Expired
Indicates that the port out credentials have expired and can no longer be used.