Portings

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

Properties

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
Status
PREVIEW
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
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
Status
PREVIEW
Description
The code reason for the declined porting.
Example: "portingPhoneNumberPortProtected"
Name
declinedMessage
Type
nullable string
Status
PREVIEW
Description
The reason description for the declined porting.
Example: "The phone number has port protection on the provider."
Name
donorProvider
Type
nullable object
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 format.
Example: "+19591234567"
Name
provider
Type
string
Description
The ID of the recipient network provider.
Example: "p9"
Name
recipientProvider
Type
object
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","address","birthday","donorProvider","donorProviderApproval","firstName","lastName"]
Name
scheduledOn
Type
nullable string
Status
PREVIEW
Description
Date when the porting is scheduled to take effect.

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 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 5A",
    "postalCode": "10024",
    "state": "NY"
  },
  "behavior": "portIn",
  "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",
    "name": "AT&T",
    "recipientProviders": [
      "p3"
    ]
  },
  "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",
    "name": "AT&T",
    "recipientProviders": [
      "p3"
    ]
  },
  "required": [
    "accountNumber",
    "accountPin",
    "address",
    "birthday",
    "donorProvider",
    "donorProviderApproval",
    "firstName",
    "lastName"
  ],
  "scheduledOn": "2021-01-21",
  "status": "draft",
  "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
  "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
}

POST/projects/{project}/portings/{porting}/cancel

Cancel a porting

Cancels a porting. A porting can be cancelled in the following situations:

it is in the pending, declined or informationRequired state,
it is in the requested state and it is scheduled for a future date.

Canceling a porting will result in the activation of the subscription with a new number. To cancel the whole process, end the subscription instead.

Preview

This endpoint is currently in preview and might change in the future.

We’re excited to hear your feedback and ideas. Please send an email to support@gigs.com to share your thoughts.

Path Parameters

Name
project
Type
string
required
Description
The unique identifier for the project.
Example: "gigs"
Name
porting
Type
string
required
Description
The unique identifier for the porting.
Example: "prt_0SNlurA049MEWV39s2kSYqaat7ZS"

Responses

Returns the canceled porting.

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
Status
PREVIEW
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
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
Status
PREVIEW
Description
The code reason for the declined porting.
Example: "portingPhoneNumberPortProtected"
Name
declinedMessage
Type
nullable string
Status
PREVIEW
Description
The reason description for the declined porting.
Example: "The phone number has port protection on the provider."
Name
donorProvider
Type
nullable object
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 format.
Example: "+19591234567"
Name
provider
Type
string
Description
The ID of the recipient network provider.
Example: "p9"
Name
recipientProvider
Type
object
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","address","birthday","donorProvider","donorProviderApproval","firstName","lastName"]
Name
scheduledOn
Type
nullable string
Status
PREVIEW
Description
Date when the porting is scheduled to take effect.

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 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"

Request

POST

/projects/{project}/portings/{porting}/cancel

curl https://api.gigs.com/projects/{project}/portings/{porting}/cancel \
-X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {token}" \
-H "Accept: application/json"

Response

{
  "object": "porting",
  "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS",
  "accountNumber": "123456789",
  "accountPinExists": true,
  "address": {
    "city": "New York City",
    "country": "US",
    "line1": "129 West 81st Street",
    "line2": "Apartment 5A",
    "postalCode": "10024",
    "state": "NY"
  },
  "behavior": "portIn",
  "birthday": "2017-07-21",
  "canceledAt": "2021-01-21T19:39:53Z",
  "completedAt": "2021-01-21T19:36:57Z",
  "createdAt": "2021-01-21T19:12:28Z",
  "declinedAttempts": 0,
  "declinedCode": "portingPhoneNumberPortProtected",
  "declinedMessage": "The phone number has port protection on the provider.",
  "donorProvider": {
    "object": "serviceProvider",
    "id": "svp_0SNlurA01K6GY5L0XJffY8",
    "name": "AT&T",
    "recipientProviders": [
      "p3"
    ]
  },
  "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",
    "name": "AT&T",
    "recipientProviders": [
      "p3"
    ]
  },
  "required": [
    "accountNumber",
    "accountPin",
    "address",
    "birthday",
    "donorProvider",
    "donorProviderApproval",
    "firstName",
    "lastName"
  ],
  "scheduledOn": "2021-01-21",
  "status": "draft",
  "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
  "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
}

GET/projects/{project}/portings/{porting}

Retrieve a Porting

Retrieves the details of an existing porting.

Path Parameters

Name
project
Type
string
required
Description
The unique identifier for the project.
Example: "gigs"
Name
porting
Type
string
required
Description
The unique identifier for the porting.
Example: "prt_0SNlurA049MEWV39s2kSYqaat7ZS"

Responses

Returns the porting.

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
Status
PREVIEW
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
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
Status
PREVIEW
Description
The code reason for the declined porting.
Example: "portingPhoneNumberPortProtected"
Name
declinedMessage
Type
nullable string
Status
PREVIEW
Description
The reason description for the declined porting.
Example: "The phone number has port protection on the provider."
Name
donorProvider
Type
nullable object
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 format.
Example: "+19591234567"
Name
provider
Type
string
Description
The ID of the recipient network provider.
Example: "p9"
Name
recipientProvider
Type
object
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","address","birthday","donorProvider","donorProviderApproval","firstName","lastName"]
Name
scheduledOn
Type
nullable string
Status
PREVIEW
Description
Date when the porting is scheduled to take effect.

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 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"

Request

GET

/projects/{project}/portings/{porting}

curl https://api.gigs.com/projects/{project}/portings/{porting} \
-X GET \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {token}" \
-H "Accept: application/json"

Response

{
  "object": "porting",
  "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS",
  "accountNumber": "123456789",
  "accountPinExists": true,
  "address": {
    "city": "New York City",
    "country": "US",
    "line1": "129 West 81st Street",
    "line2": "Apartment 5A",
    "postalCode": "10024",
    "state": "NY"
  },
  "behavior": "portIn",
  "birthday": "2017-07-21",
  "canceledAt": "2021-01-21T19:39:53Z",
  "completedAt": "2021-01-21T19:36:57Z",
  "createdAt": "2021-01-21T19:12:28Z",
  "declinedAttempts": 0,
  "declinedCode": "portingPhoneNumberPortProtected",
  "declinedMessage": "The phone number has port protection on the provider.",
  "donorProvider": {
    "object": "serviceProvider",
    "id": "svp_0SNlurA01K6GY5L0XJffY8",
    "name": "AT&T",
    "recipientProviders": [
      "p3"
    ]
  },
  "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",
    "name": "AT&T",
    "recipientProviders": [
      "p3"
    ]
  },
  "required": [
    "accountNumber",
    "accountPin",
    "address",
    "birthday",
    "donorProvider",
    "donorProviderApproval",
    "firstName",
    "lastName"
  ],
  "scheduledOn": "2021-01-21",
  "status": "draft",
  "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
  "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
}

PATCH/projects/{project}/portings/{porting}

Update a porting

Updates a porting with the given parameters.

Depending on the status of the porting, some fields may not be updated anymore. When all the required information is provided, the porting will be requested. If the porting is declined, it will be retried. To retry a porting without providing any new information, simply update the porting with an empty request.

Related guide: How Porting Works

Body

Name
accountNumber
Type
string
Description
The account number on the donor service provider.
Example: "123456789"
Name
accountPin
Type
string
Description
The pin for the account on the donor service provider. This will be used only for the porting.
Example: "1234"
Name
address
Type
object
Description
The address of the account holder on the donor service provider.
Name
behavior
Type
string
Status
PREVIEW
Description
The behavior of the porting.

Use portIn to transfer the phone number from the previous provider.

Use cancelOnly to cancel the previous service without transferring the number. This behavior is currently only available for local plans in the United Kingdom.

This property is only updatable when the porting's status is draft.
Example: "portIn"
Allowed values: cancelOnly portIn
Name
birthday
Type
string
Description
The birthday of the account holder on the donor service provider.
Example: "2017-07-21"
Name
donorProvider
Type
string
Description
The unique identifier of the donor service provider.
Example: "svp_0SNlurA01K6GY5L0XJffY8"
Name
donorProviderApproval
Type
boolean
Description
Whether the donor provider has approved or not the porting.
Example: true
Name
firstName
Type
string
Description
The first name of the account holder.
Example: "Jerry"
Name
lastName
Type
string
Description
The last name of the account holder.
Example: "Seinfeld"
Name
phoneNumber
Type
string
Description
The phone number to port in E.164 format. This is only updatable when the porting is in a status of: draft
Example: "+19591234567"
Name
provider
Type
string
Description
The ID of the recipient network provider. This is only updatable when the porting is in a status of: draft
Example: "p9"
Name
scheduledOn
Type
nullable string
Status
PREVIEW
Description
Date when the porting is scheduled to take effect.

The ability to schedule portings is only available for local plans in the United Kingdom. Attempting to schedule a porting for a provider in any other country will result in an error.

Use null to indicate that the porting should be scheduled as soon as possible. Otherwise, the date provided must be in the future.
Example: "2021-01-21"

Path Parameters

Name
project
Type
string
required
Description
The unique identifier for the project.
Example: "gigs"
Name
porting
Type
string
required
Description
The unique identifier for the porting.
Example: "prt_0SNlurA049MEWV39s2kSYqaat7ZS"

Responses

Returns the updated porting.

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
Status
PREVIEW
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
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
Status
PREVIEW
Description
The code reason for the declined porting.
Example: "portingPhoneNumberPortProtected"
Name
declinedMessage
Type
nullable string
Status
PREVIEW
Description
The reason description for the declined porting.
Example: "The phone number has port protection on the provider."
Name
donorProvider
Type
nullable object
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 format.
Example: "+19591234567"
Name
provider
Type
string
Description
The ID of the recipient network provider.
Example: "p9"
Name
recipientProvider
Type
object
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","address","birthday","donorProvider","donorProviderApproval","firstName","lastName"]
Name
scheduledOn
Type
nullable string
Status
PREVIEW
Description
Date when the porting is scheduled to take effect.

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 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"

Request

PATCH

/projects/{project}/portings/{porting}

curl https://api.gigs.com/projects/{project}/portings/{porting} \
-X PATCH \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {token}" \
-H "Accept: application/json" \
-d "{\"accountNumber\":\"123456789\",\"accountPin\":\"1234\",\"address\":{\"city\":\"New York City\",\"country\":\"US\",\"line1\":\"129 West 81st Street\",\"line2\":\"Apartment 5A\",\"postalCode\":\"10024\",\"state\":\"NY\"},\"behavior\":\"portIn\",\"birthday\":\"2017-07-21\",\"donorProvider\":\"svp_0SNlurA01K6GY5L0XJffY8\",\"donorProviderApproval\":true,\"firstName\":\"Jerry\",\"lastName\":\"Seinfeld\",\"phoneNumber\":\"+19591234567\",\"provider\":\"p9\",\"scheduledOn\":\"2021-01-21\"}"

Response

{
  "object": "porting",
  "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS",
  "accountNumber": "123456789",
  "accountPinExists": true,
  "address": {
    "city": "New York City",
    "country": "US",
    "line1": "129 West 81st Street",
    "line2": "Apartment 5A",
    "postalCode": "10024",
    "state": "NY"
  },
  "behavior": "portIn",
  "birthday": "2017-07-21",
  "canceledAt": "2021-01-21T19:39:53Z",
  "completedAt": "2021-01-21T19:36:57Z",
  "createdAt": "2021-01-21T19:12:28Z",
  "declinedAttempts": 0,
  "declinedCode": "portingPhoneNumberPortProtected",
  "declinedMessage": "The phone number has port protection on the provider.",
  "donorProvider": {
    "object": "serviceProvider",
    "id": "svp_0SNlurA01K6GY5L0XJffY8",
    "name": "AT&T",
    "recipientProviders": [
      "p3"
    ]
  },
  "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",
    "name": "AT&T",
    "recipientProviders": [
      "p3"
    ]
  },
  "required": [
    "accountNumber",
    "accountPin",
    "address",
    "birthday",
    "donorProvider",
    "donorProviderApproval",
    "firstName",
    "lastName"
  ],
  "scheduledOn": "2021-01-21",
  "status": "draft",
  "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
  "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
}

GET/projects/{project}/portings

List all portings

Returns a list of portings. The portings returned are sorted by creation date, with the most recently created portings appearing first.

Path Parameters

Name
project
Type
string
required
Description
The unique identifier for the project.
Example: "gigs"

Query Parameters

Name
status
Type
array
Description
The status to filter the portings by.
Name
subscription
Type
string
Description
The unique identifier of the subscription to be filtered by.
Example: "sub_0SNlurA049MEWV2gSfSxi00xlPIi"
Name
after
Type
string
Description
A cursor for use in pagination. The after parameter takes an object ID that defines the position in the list, only items immediately following the item with that ID will be returned.
Name
before
Type
string
Description
A cursor for use in pagination. The before parameter takes an object ID that defines the position in the list, only items immediately preceding the item with that ID will be returned.
Name
limit
Type
integer
Description
The limit of items to be returned in the list, between 0 and 200.
Default: 10
>= 0
<= 200

Responses

Returns a dictionary with an items property that contains an array of portings.

Name
object
Type
string
Description
Type of object is always list.
Allowed values: list
Name
items
Type
array
Description
List of objects of type `porting`.
Name
moreItemsAfter
Type
nullable string
Description
A unique identifier to be used as after pagination parameter if more items are available sorted after the current batch of items.
Name
moreItemsBefore
Type
nullable string
Description
A unique identifier to be used as before pagination parameter if more items are available sorted before the current batch of items.

Request

GET

/projects/{project}/portings

curl https://api.gigs.com/projects/{project}/portings \
-X GET \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {token}" \
-H "Accept: application/json"

Response

{
  "object": "list",
  "items": [
    {
      "object": "porting",
      "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS",
      "accountNumber": "123456789",
      "accountPinExists": true,
      "address": {
        "city": "New York City",
        "country": "US",
        "line1": "129 West 81st Street",
        "line2": "Apartment 5A",
        "postalCode": "10024",
        "state": "NY"
      },
      "behavior": "portIn",
      "birthday": "2017-07-21",
      "canceledAt": "2021-01-21T19:39:53Z",
      "completedAt": "2021-01-21T19:36:57Z",
      "createdAt": "2021-01-21T19:12:28Z",
      "declinedAttempts": 0,
      "declinedCode": "portingPhoneNumberPortProtected",
      "declinedMessage": "The phone number has port protection on the provider.",
      "donorProvider": {
        "object": "serviceProvider",
        "id": "svp_0SNlurA01K6GY5L0XJffY8",
        "name": "AT&T",
        "recipientProviders": [
          "p3"
        ]
      },
      "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",
        "name": "AT&T",
        "recipientProviders": [
          "p3"
        ]
      },
      "required": [
        "accountNumber",
        "accountPin",
        "address",
        "birthday",
        "donorProvider",
        "donorProviderApproval",
        "firstName",
        "lastName"
      ],
      "scheduledOn": "2021-01-21",
      "status": "draft",
      "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
      "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
    }
  ],
  "moreItemsAfter": null,
  "moreItemsBefore": null
}

POST/projects/{project}/portings

Create a porting

Creates a new porting. It will be created in draft status and can be later used to create an order or subscription for the same provider.

Only some of the fields are required during creation. Some providers require additional fields which are listed in the required array property of the porting. It will remain in informationRequired status and will not be requested until all required information has been collected.

Related guide: How Porting Works

Body

Name
accountNumber
Type
nullable string
Description
The account number on the donor service provider.
Example: "123456789"
Name
accountPin
Type
nullable string
Description
The pin for the account on the donor service provider. This will be used only for the porting.
Example: "1234"
Name
address
Type
nullable object
Description
The address of the account holder on the donor service provider.
Name
behavior
Type
nullable string
Status
PREVIEW
Description
The behavior of the porting.

Use portIn to transfer the phone number from the previous provider.

Use cancelOnly to cancel the previous service without transferring the number. This behavior is currently only available for local plans in the United Kingdom.

Defaults to portIn if no value is provided.
Example: "portIn"
Default: portIn
Allowed values: cancelOnly portIn
Name
birthday
Type
nullable string
Description
The birthday of the account holder on the donor service provider.
Example: "2017-07-21"
Name
donorProvider
Type
nullable string
Description
The unique identifier of the donor service provider.
Example: "svp_0SNlurA01K6GY5L0XJffY8"
Name
donorProviderApproval
Type
nullable boolean
Description
Whether the donor provider has approved or not the porting.
Example: true
Name
firstName
Type
nullable string
Description
The first name of the account holder.
Example: "Jerry"
Name
lastName
Type
nullable string
Description
The last name of the account holder.
Example: "Seinfeld"
Name
phoneNumber
Type
string
required
Description
The phone number to port in E.164 format.
Example: "+19591234567"
Name
provider
Type
string
required
Description
The name of the receiving network provider.
Example: "p9"
Name
scheduledOn
Type
nullable string
Status
PREVIEW
Description
The date that the porting is scheduled to take effect.

This functionality is only available for local plans in the United Kingdom. Attempting to schedule a porting for a provider in any other country will result in an error.

Use null to indicate that the porting should be scheduled as soon as possible. Otherwise, the date provided must be in the future.

If, by the time the porting is used to create a subscription, the scheduled date has already passed, then the porting will instead occur as soon as possible.
Example: "2021-01-21"
Name
user
Type
string
required
Description
The unique identifier for an existing user the porting should be created for.
Example: "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"

Path Parameters

Name
project
Type
string
required
Description
The unique identifier for the project.
Example: "gigs"

Responses

Returns the created porting.

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
Status
PREVIEW
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
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
Status
PREVIEW
Description
The code reason for the declined porting.
Example: "portingPhoneNumberPortProtected"
Name
declinedMessage
Type
nullable string
Status
PREVIEW
Description
The reason description for the declined porting.
Example: "The phone number has port protection on the provider."
Name
donorProvider
Type
nullable object
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 format.
Example: "+19591234567"
Name
provider
Type
string
Description
The ID of the recipient network provider.
Example: "p9"
Name
recipientProvider
Type
object
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","address","birthday","donorProvider","donorProviderApproval","firstName","lastName"]
Name
scheduledOn
Type
nullable string
Status
PREVIEW
Description
Date when the porting is scheduled to take effect.

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 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"

Request

POST

/projects/{project}/portings

curl https://api.gigs.com/projects/{project}/portings \
-X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {token}" \
-H "Accept: application/json" \
-d "{\"accountNumber\":\"123456789\",\"accountPin\":\"1234\",\"address\":{\"city\":\"New York City\",\"country\":\"US\",\"line1\":\"129 West 81st Street\",\"line2\":\"Apartment 5A\",\"postalCode\":\"10024\",\"state\":\"NY\"},\"behavior\":\"portIn\",\"birthday\":\"2017-07-21\",\"donorProvider\":\"svp_0SNlurA01K6GY5L0XJffY8\",\"donorProviderApproval\":true,\"firstName\":\"Jerry\",\"lastName\":\"Seinfeld\",\"phoneNumber\":\"+19591234567\",\"provider\":\"p9\",\"scheduledOn\":\"2021-01-21\",\"user\":\"usr_0SNlurA049MEWV4OpCwsNyC9Kn2d\"}"

Response

{
  "object": "porting",
  "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS",
  "accountNumber": "123456789",
  "accountPinExists": true,
  "address": {
    "city": "New York City",
    "country": "US",
    "line1": "129 West 81st Street",
    "line2": "Apartment 5A",
    "postalCode": "10024",
    "state": "NY"
  },
  "behavior": "portIn",
  "birthday": "2017-07-21",
  "canceledAt": "2021-01-21T19:39:53Z",
  "completedAt": "2021-01-21T19:36:57Z",
  "createdAt": "2021-01-21T19:12:28Z",
  "declinedAttempts": 0,
  "declinedCode": "portingPhoneNumberPortProtected",
  "declinedMessage": "The phone number has port protection on the provider.",
  "donorProvider": {
    "object": "serviceProvider",
    "id": "svp_0SNlurA01K6GY5L0XJffY8",
    "name": "AT&T",
    "recipientProviders": [
      "p3"
    ]
  },
  "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",
    "name": "AT&T",
    "recipientProviders": [
      "p3"
    ]
  },
  "required": [
    "accountNumber",
    "accountPin",
    "address",
    "birthday",
    "donorProvider",
    "donorProviderApproval",
    "firstName",
    "lastName"
  ],
  "scheduledOn": "2021-01-21",
  "status": "draft",
  "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
  "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
}

GET/serviceProviders/{serviceProvider}

Retrieve a service provider

Retrieves the details of a service provider.

Preview

This endpoint is currently in preview and might change in the future.

We’re excited to hear your feedback and ideas. Please send an email to support@gigs.com to share your thoughts.

Path Parameters

Name
serviceProvider
Type
string
required
Description
The unique identifier for the service provider.
Example: "svp_0SNlurA01K6GY5L0XJffY8"

Responses

Returns the service provider object if it exists.

Name
object
Type
string
Description
Type of object is always serviceProvider.
Allowed values: serviceProvider
Name
id
Type
string
Description
Unique identifier for the service provider.
Example: "svp_0SNlurA01K6GY5L0XJffY8"
Name
name
Type
string
Description
The name of the service provider, usually a brand name.
Example: "AT&T"
Name
recipientProviders
Type
array
Description
List of network providers IDs that can receive portings from the service provider.
Default: p3

Request

GET

/serviceProviders/{serviceProvider}

curl https://api.gigs.com/serviceProviders/{serviceProvider} \
-X GET \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {token}" \
-H "Accept: application/json"

Response

{
  "object": "serviceProvider",
  "id": "svp_0SNlurA01K6GY5L0XJffY8",
  "name": "AT&T",
  "recipientProviders": [
    "p3"
  ]
}

GET/serviceProviders

List all service providers

Returns a list of service providers.

Preview

This endpoint is currently in preview and might change in the future.

We’re excited to hear your feedback and ideas. Please send an email to support@gigs.com to share your thoughts.

Query Parameters

Name
recipientProvider
Type
string
Description
Only return service providers that have the given network provider as supported porting recipient.
Example: "p7"

Responses

Returns a dictionary with an items property that contains an array of service providers.

Name
object
Type
string
Description
Type of object is always list.
Allowed values: list
Name
items
Type
array
Description
List of objects of type `serviceProvider`.
Name
moreItemsAfter
Type
nullable string
Description
A unique identifier to be used as after pagination parameter if more items are available sorted after the current batch of items.
Name
moreItemsBefore
Type
nullable string
Description
A unique identifier to be used as before pagination parameter if more items are available sorted before the current batch of items.

Request

GET

/serviceProviders

curl https://api.gigs.com/serviceProviders \
-X GET \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {token}" \
-H "Accept: application/json"

Response

{
  "object": "list",
  "items": [
    {
      "object": "serviceProvider",
      "id": "svp_0SNlurA01K6GY5L0XJffY8",
      "name": "AT&T",
      "recipientProviders": [
        "p3"
      ]
    }
  ],
  "moreItemsAfter": null,
  "moreItemsBefore": null
}