Porting

Porting is required when a user wants to keep their phone number when changing their subscription. There are multiple steps involved between the user, their previous carrier, and the new subscriber

Name
object
Type
string
Description
Type of object is always porting.
Allowed values: porting
Name
id
Type
string
Description
Unique identifier for the porting.
Example: "prt_0SNlurA049MEWV39s2kSYqaat7ZS"
Name
accountNumber
Type
nullable string
Description
The account number on the donor service provider.
Example: "123456789"
Name
accountPinExists
Type
boolean
Description
Whether the account PIN has been provided.
Example: true
Name
address
Type
nullable object
Description
The address of the account holder on the donor service provider.
Name
behavior
Type
string
Description
The behavior of the porting.

A value of portIn indicates that this porting will transfer the phone number from the previous provider.

A porting with behavior cancelOnly will cancel the previous service without transferring the number. This behavior is currently only available for local plans in the United Kingdom.
Example: "portIn"
Allowed values: cancelOnly portIn
Name
billingPinExists
Type
boolean
Description
Whether the billing PIN has been provided.
Example: true
Name
birthday
Type
nullable string
Description
The birthday of the account holder on the donor service provider.
Example: "2017-07-21"
Name
canceledAt
Type
nullable string
Description
Time when the porting was canceled.
Example: "2021-01-21T19:39:53Z"
Name
completedAt
Type
nullable string
Description
Time when the porting was completed.
Example: "2021-01-21T19:36:57Z"
Name
createdAt
Type
string
Description
Time when the porting was created.
Example: "2021-01-21T19:12:28Z"
Name
declinedAttempts
Type
integer
Description
The number of declined porting attempts so far.
Example: 0
>= 0
Name
declinedCode
Type
nullable string
Description
The code reason for the declined porting.
Example: "portingPhoneNumberPortProtected"
Name
declinedMessage
Type
nullable string
Description
The reason description for the declined porting.
Example: "The phone number has port protection on the provider."
Name
donorProvider
Type
nullable ServiceProvider
Description
The service provider from whom the number is ported.
Name
donorProviderApproval
Type
nullable boolean
Description
Whether the donor provider has approved or not the porting.
Example: true
Name
expiredAt
Type
nullable string
Description
Time when the porting was expired.
Example: "2021-01-21T19:39:53Z"
Name
firstName
Type
nullable string
Description
The first name of the account holder on the donor service provider.
Example: "Jerry"
Name
lastDeclinedAt
Type
nullable string
Description
Time when the porting was last declined.
Example: "2021-01-21T19:31:13Z"
Name
lastName
Type
nullable string
Description
The last name of the account holder on the donor service provider.
Example: "Seinfeld"
Name
lastRequestedAt
Type
nullable string
Description
Time when the porting was last requested.
Example: "2021-01-21T19:22:31Z"
Name
phoneNumber
Type
string
Description
The phone number to port in E.164 string_format.
Example: "+19591234567"
Name
provider
Type
string
Description
The ID of the recipient network provider.
Example: "p9"
Name
recipientProvider
Type
ServiceProvider
Description
The service provider to whom the number is ported.
Name
required
Type
array
Description
List of fields required for the porting to be processable. The fields depend on the donor and recipient providers.
Example: ["accountNumber","accountPin","accountType","address","birthday","donorProvider","donorProviderApproval","firstName","lastName"]
Name
scheduledOn
Type
nullable string
Description
Date when the porting is scheduled to take effect.

This returns the provider-confirmed date when available, otherwise the user-requested date.

The ability to schedule portings is only available for local plans in the United Kingdom. Otherwise, this value will be null.
Example: "2021-01-21"
Name
status
Type
string
Description
The current status of the porting.
Allowed values: draft initiated pending informationRequired requested declined completed canceled expired
Name
subscription
Type
nullable string
Description
Unique identifier for the porting subscription.
Example: "sub_0SNlurA049MEWV2gSfSxi00xlPIi"
Name
user
Type
string
Description
Unique identifier for the user this porting is for.
Example: "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"

Example

{
  "object": "porting",
  "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS",
  "accountNumber": "123456789",
  "accountPinExists": true,
  "address": {
    "city": "New York City",
    "country": "US",
    "line1": "129 West 81st Street",
    "line2": "Apartment 5",
    "postalCode": "10024",
    "state": "NY"
  },
  "behavior": "portIn",
  "billingPinExists": true,
  "birthday": "2017-07-21",
  "canceledAt": "2021-01-21T19:39:53Z",
  "completedAt": "2021-01-21T19:36:57Z",
  "createdAt": "2021-01-21T19:12:28.0Z",
  "declinedAttempts": 0,
  "declinedCode": "portingPhoneNumberPortProtected",
  "declinedMessage": "The phone number has port protection on the provider.",
  "donorProvider": {
    "object": "serviceProvider",
    "id": "svp_0SNlurA01K6GY5L0XJffY8",
    "country": "US",
    "name": "AT&T",
    "recipientProviders": [
      {
        "0": "p",
        "1": "3"
      }
    ]
  },
  "donorProviderApproval": true,
  "expiredAt": "2021-01-21T19:39:53Z",
  "firstName": "Jerry",
  "lastDeclinedAt": "2021-01-21T19:31:13Z",
  "lastName": "Seinfeld",
  "lastRequestedAt": "2021-01-21T19:22:31Z",
  "phoneNumber": "+19591234567",
  "provider": "p9",
  "recipientProvider": {
    "object": "serviceProvider",
    "id": "svp_0SNlurA01K6GY5L0XJffY8",
    "country": "US",
    "name": "AT&T",
    "recipientProviders": [
      "p3"
    ]
  },
  "required": [
    "accountNumber",
    "accountPin",
    "accountType",
    "address",
    "birthday",
    "donorProvider",
    "donorProviderApproval",
    "firstName",
    "lastName"
  ],
  "scheduledOn": "2021-01-21",
  "status": "draft",
  "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
  "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
}