Portings

The Porting resource

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
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
PREVIEW
Description
The code reason for the declined porting.
Example: "portingPhoneNumberPortProtected"
Name
declinedMessage
Type
nullable string
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
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"

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"
  },
  "birthday": "2017-07-21",
  "canceledAt": "2021-01-21T19:39:53Z",
  "completedAt": "2021-01-21T19:36:57Z",
  "createdAt": "2021-01-21T19:12:28Z",
  "declinedCode": "portingPhoneNumberPortProtected",
  "declinedMessage": "The phone number has port protection on the provider.",
  "donorProvider": {
    "object": "serviceProvider",
    "id": "svp_0SNlurA01K6GY5L0XJffY8",
    "name": "AT&T"
  },
  "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"
  },
  "required": [
    "accountNumber",
    "accountPin",
    "address",
    "birthday",
    "donorProvider",
    "donorProviderApproval",
    "firstName",
    "lastName"
  ],
  "status": "draft",
  "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
  "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
}

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

Cancel a porting

Cancels a porting. Only portings that have not yet been completed and are not currently being processed can be canceled.

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"

Response Schemas

Returns the canceled porting.

Name
object
Type
string
required
Description
Type of object is always porting.
Allowed values: porting
Name
id
Type
string
required
Description
Unique identifier for the porting.
Example: "prt_0SNlurA049MEWV39s2kSYqaat7ZS"
Name
accountNumber
Type
nullable string
required
Description
The account number on the donor service provider.
Example: "123456789"
Name
accountPinExists
Type
boolean
required
Description
Whether the account PIN has been provided.
Example: true
Name
address
Type
nullable object
required
Description
The address of the account holder on the donor service provider.
Name
birthday
Type
nullable string
required
Description
The birthday of the account holder on the donor service provider.
Example: "2017-07-21"
Name
canceledAt
Type
nullable string
required
Description
Time when the porting was canceled.
Example: "2021-01-21T19:39:53Z"
Name
completedAt
Type
nullable string
required
Description
Time when the porting was completed.
Example: "2021-01-21T19:36:57Z"
Name
createdAt
Type
string
required
Description
Time when the porting was created.
Example: "2021-01-21T19:12:28Z"
Name
declinedAttempts
Type
integer
required
Description
The number of declined porting attempts so far.
Example: 0
>= 0
Name
declinedCode
Type
nullable string
PREVIEW
required
Description
The code reason for the declined porting.
Example: "portingPhoneNumberPortProtected"
Name
declinedMessage
Type
nullable string
PREVIEW
required
Description
The reason description for the declined porting.
Example: "The phone number has port protection on the provider."
Name
donorProvider
Type
nullable object
required
Description
The service provider from whom the number is ported.
Name
donorProviderApproval
Type
nullable boolean
required
Description
Whether the donor provider has approved or not the porting.
Example: true
Name
expiredAt
Type
nullable string
required
Description
Time when the porting was expired.
Example: "2021-01-21T19:39:53Z"
Name
firstName
Type
nullable string
required
Description
The first name of the account holder on the donor service provider.
Example: "Jerry"
Name
lastDeclinedAt
Type
nullable string
required
Description
Time when the porting was last declined.
Example: "2021-01-21T19:31:13Z"
Name
lastName
Type
nullable string
required
Description
The last name of the account holder on the donor service provider.
Example: "Seinfeld"
Name
lastRequestedAt
Type
nullable string
required
Description
Time when the porting was last requested.
Example: "2021-01-21T19:22:31Z"
Name
phoneNumber
Type
string
required
Description
The phone number to port in E.164 format.
Example: "+19591234567"
Name
provider
Type
string
required
Description
The ID of the recipient network provider.
Example: "p9"
Name
recipientProvider
Type
object
required
Description
The service provider to whom the number is ported.
Name
required
Type
array
required
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
status
Type
string
required
Description
The current status of the porting.
Allowed values: draft, pending, informationRequired, requested, declined, completed, canceled, expired
Name
subscription
Type
nullable string
required
Description
Unique identifier for the porting subscription.
Example: "sub_0SNlurA049MEWV2gSfSxi00xlPIi"
Name
user
Type
string
required
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"
  },
  "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"
  ],
  "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"

Response Schemas

Returns the porting.

Name
object
Type
string
required
Description
Type of object is always porting.
Allowed values: porting
Name
id
Type
string
required
Description
Unique identifier for the porting.
Example: "prt_0SNlurA049MEWV39s2kSYqaat7ZS"
Name
accountNumber
Type
nullable string
required
Description
The account number on the donor service provider.
Example: "123456789"
Name
accountPinExists
Type
boolean
required
Description
Whether the account PIN has been provided.
Example: true
Name
address
Type
nullable object
required
Description
The address of the account holder on the donor service provider.
Name
birthday
Type
nullable string
required
Description
The birthday of the account holder on the donor service provider.
Example: "2017-07-21"
Name
canceledAt
Type
nullable string
required
Description
Time when the porting was canceled.
Example: "2021-01-21T19:39:53Z"
Name
completedAt
Type
nullable string
required
Description
Time when the porting was completed.
Example: "2021-01-21T19:36:57Z"
Name
createdAt
Type
string
required
Description
Time when the porting was created.
Example: "2021-01-21T19:12:28Z"
Name
declinedAttempts
Type
integer
required
Description
The number of declined porting attempts so far.
Example: 0
>= 0
Name
declinedCode
Type
nullable string
PREVIEW
required
Description
The code reason for the declined porting.
Example: "portingPhoneNumberPortProtected"
Name
declinedMessage
Type
nullable string
PREVIEW
required
Description
The reason description for the declined porting.
Example: "The phone number has port protection on the provider."
Name
donorProvider
Type
nullable object
required
Description
The service provider from whom the number is ported.
Name
donorProviderApproval
Type
nullable boolean
required
Description
Whether the donor provider has approved or not the porting.
Example: true
Name
expiredAt
Type
nullable string
required
Description
Time when the porting was expired.
Example: "2021-01-21T19:39:53Z"
Name
firstName
Type
nullable string
required
Description
The first name of the account holder on the donor service provider.
Example: "Jerry"
Name
lastDeclinedAt
Type
nullable string
required
Description
Time when the porting was last declined.
Example: "2021-01-21T19:31:13Z"
Name
lastName
Type
nullable string
required
Description
The last name of the account holder on the donor service provider.
Example: "Seinfeld"
Name
lastRequestedAt
Type
nullable string
required
Description
Time when the porting was last requested.
Example: "2021-01-21T19:22:31Z"
Name
phoneNumber
Type
string
required
Description
The phone number to port in E.164 format.
Example: "+19591234567"
Name
provider
Type
string
required
Description
The ID of the recipient network provider.
Example: "p9"
Name
recipientProvider
Type
object
required
Description
The service provider to whom the number is ported.
Name
required
Type
array
required
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
status
Type
string
required
Description
The current status of the porting.
Allowed values: draft, pending, informationRequired, requested, declined, completed, canceled, expired
Name
subscription
Type
nullable string
required
Description
Unique identifier for the porting subscription.
Example: "sub_0SNlurA049MEWV2gSfSxi00xlPIi"
Name
user
Type
string
required
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"
  },
  "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"
  ],
  "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
nullable object
Description
The address of the account holder on the donor service provider.
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
nullable 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"

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"

Response Schemas

Returns the updated porting.

Name
object
Type
string
required
Description
Type of object is always porting.
Allowed values: porting
Name
id
Type
string
required
Description
Unique identifier for the porting.
Example: "prt_0SNlurA049MEWV39s2kSYqaat7ZS"
Name
accountNumber
Type
nullable string
required
Description
The account number on the donor service provider.
Example: "123456789"
Name
accountPinExists
Type
boolean
required
Description
Whether the account PIN has been provided.
Example: true
Name
address
Type
nullable object
required
Description
The address of the account holder on the donor service provider.
Name
birthday
Type
nullable string
required
Description
The birthday of the account holder on the donor service provider.
Example: "2017-07-21"
Name
canceledAt
Type
nullable string
required
Description
Time when the porting was canceled.
Example: "2021-01-21T19:39:53Z"
Name
completedAt
Type
nullable string
required
Description
Time when the porting was completed.
Example: "2021-01-21T19:36:57Z"
Name
createdAt
Type
string
required
Description
Time when the porting was created.
Example: "2021-01-21T19:12:28Z"
Name
declinedAttempts
Type
integer
required
Description
The number of declined porting attempts so far.
Example: 0
>= 0
Name
declinedCode
Type
nullable string
PREVIEW
required
Description
The code reason for the declined porting.
Example: "portingPhoneNumberPortProtected"
Name
declinedMessage
Type
nullable string
PREVIEW
required
Description
The reason description for the declined porting.
Example: "The phone number has port protection on the provider."
Name
donorProvider
Type
nullable object
required
Description
The service provider from whom the number is ported.
Name
donorProviderApproval
Type
nullable boolean
required
Description
Whether the donor provider has approved or not the porting.
Example: true
Name
expiredAt
Type
nullable string
required
Description
Time when the porting was expired.
Example: "2021-01-21T19:39:53Z"
Name
firstName
Type
nullable string
required
Description
The first name of the account holder on the donor service provider.
Example: "Jerry"
Name
lastDeclinedAt
Type
nullable string
required
Description
Time when the porting was last declined.
Example: "2021-01-21T19:31:13Z"
Name
lastName
Type
nullable string
required
Description
The last name of the account holder on the donor service provider.
Example: "Seinfeld"
Name
lastRequestedAt
Type
nullable string
required
Description
Time when the porting was last requested.
Example: "2021-01-21T19:22:31Z"
Name
phoneNumber
Type
string
required
Description
The phone number to port in E.164 format.
Example: "+19591234567"
Name
provider
Type
string
required
Description
The ID of the recipient network provider.
Example: "p9"
Name
recipientProvider
Type
object
required
Description
The service provider to whom the number is ported.
Name
required
Type
array
required
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
status
Type
string
required
Description
The current status of the porting.
Allowed values: draft, pending, informationRequired, requested, declined, completed, canceled, expired
Name
subscription
Type
nullable string
required
Description
Unique identifier for the porting subscription.
Example: "sub_0SNlurA049MEWV2gSfSxi00xlPIi"
Name
user
Type
string
required
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\"},\"birthday\":\"2017-07-21\",\"donorProvider\":\"svp_0SNlurA01K6GY5L0XJffY8\",\"donorProviderApproval\":true,\"firstName\":\"Jerry\",\"lastName\":\"Seinfeld\",\"phoneNumber\":\"+19591234567\",\"provider\":\"p9\"}"

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"
  },
  "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"
  ],
  "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

Response Schemas

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

Name
object
Type
string
required
Description
Type of object is always list.
Allowed values: list
Name
items
Type
array
required
Description
List of objects of type `porting`.
Name
moreItemsAfter
Type
nullable string
required
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
required
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"
      },
      "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"
      ],
      "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
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
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"

Response Schemas

Returns the created porting.

Name
object
Type
string
required
Description
Type of object is always porting.
Allowed values: porting
Name
id
Type
string
required
Description
Unique identifier for the porting.
Example: "prt_0SNlurA049MEWV39s2kSYqaat7ZS"
Name
accountNumber
Type
nullable string
required
Description
The account number on the donor service provider.
Example: "123456789"
Name
accountPinExists
Type
boolean
required
Description
Whether the account PIN has been provided.
Example: true
Name
address
Type
nullable object
required
Description
The address of the account holder on the donor service provider.
Name
birthday
Type
nullable string
required
Description
The birthday of the account holder on the donor service provider.
Example: "2017-07-21"
Name
canceledAt
Type
nullable string
required
Description
Time when the porting was canceled.
Example: "2021-01-21T19:39:53Z"
Name
completedAt
Type
nullable string
required
Description
Time when the porting was completed.
Example: "2021-01-21T19:36:57Z"
Name
createdAt
Type
string
required
Description
Time when the porting was created.
Example: "2021-01-21T19:12:28Z"
Name
declinedAttempts
Type
integer
required
Description
The number of declined porting attempts so far.
Example: 0
>= 0
Name
declinedCode
Type
nullable string
PREVIEW
required
Description
The code reason for the declined porting.
Example: "portingPhoneNumberPortProtected"
Name
declinedMessage
Type
nullable string
PREVIEW
required
Description
The reason description for the declined porting.
Example: "The phone number has port protection on the provider."
Name
donorProvider
Type
nullable object
required
Description
The service provider from whom the number is ported.
Name
donorProviderApproval
Type
nullable boolean
required
Description
Whether the donor provider has approved or not the porting.
Example: true
Name
expiredAt
Type
nullable string
required
Description
Time when the porting was expired.
Example: "2021-01-21T19:39:53Z"
Name
firstName
Type
nullable string
required
Description
The first name of the account holder on the donor service provider.
Example: "Jerry"
Name
lastDeclinedAt
Type
nullable string
required
Description
Time when the porting was last declined.
Example: "2021-01-21T19:31:13Z"
Name
lastName
Type
nullable string
required
Description
The last name of the account holder on the donor service provider.
Example: "Seinfeld"
Name
lastRequestedAt
Type
nullable string
required
Description
Time when the porting was last requested.
Example: "2021-01-21T19:22:31Z"
Name
phoneNumber
Type
string
required
Description
The phone number to port in E.164 format.
Example: "+19591234567"
Name
provider
Type
string
required
Description
The ID of the recipient network provider.
Example: "p9"
Name
recipientProvider
Type
object
required
Description
The service provider to whom the number is ported.
Name
required
Type
array
required
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
status
Type
string
required
Description
The current status of the porting.
Allowed values: draft, pending, informationRequired, requested, declined, completed, canceled, expired
Name
subscription
Type
nullable string
required
Description
Unique identifier for the porting subscription.
Example: "sub_0SNlurA049MEWV2gSfSxi00xlPIi"
Name
user
Type
string
required
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\"},\"birthday\":\"2017-07-21\",\"donorProvider\":\"svp_0SNlurA01K6GY5L0XJffY8\",\"donorProviderApproval\":true,\"firstName\":\"Jerry\",\"lastName\":\"Seinfeld\",\"phoneNumber\":\"+19591234567\",\"provider\":\"p9\",\"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"
  },
  "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"
  ],
  "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"

Response Schemas

Returns the service provider object if it exists.

Name
object
Type
string
required
Description
Type of object is always serviceProvider.
Allowed values: serviceProvider
Name
id
Type
string
required
Description
Unique identifier for the service provider.
Example: "svp_0SNlurA01K6GY5L0XJffY8"
Name
name
Type
string
required
Description
The name of the service provider, usually a brand name.
Example: "AT&T"
Name
recipientProviders
Type
array
required
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"

Response Schemas

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

Name
object
Type
string
required
Description
Type of object is always list.
Allowed values: list
Name
items
Type
array
required
Description
List of objects of type `serviceProvider`.
Name
moreItemsAfter
Type
nullable string
required
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
required
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
}