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. Visit our how porting works guide for more information.

Properties

Name
object
Type
string
Description
Type of object is always 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
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
firstName
Type
nullable string
Description
The first name of the account holder on the donor service provider.
Example: Jerry
Name
lastName
Type
nullable string
Description
The last name of the account holder on the donor service provider.
Example: Seinfeld
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
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
expiredAt
Type
nullable string
Description
Time when the porting was expired.
Example: 2021-01-21T19:39:53Z
Name
lastDeclinedAt
Type
nullable string
Description
Time when the porting was last declined.
Example: 2021-01-21T19:31:13Z
Name
lastRequestedAt
Type
nullable string
Description
Time when the porting was last requested.
Example: 2021-01-21T19:22:31Z

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",
  "declinedCode": "portingPhoneNumberPortProtected",
  "declinedMessage": "The phone number has port protection on the provider.",
  "donorProvider": {
    "object": "serviceProvider",
    "id": "svp_0SNlurA01K6GY5L0XJffY8",
    "name": "AT&T"
  },
  "donorProviderApproval": true,
  "firstName": "Jerry",
  "lastName": "Seinfeld",
  "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",
  "canceledAt": "2021-01-21T19:39:53Z",
  "completedAt": "2021-01-21T19:36:57Z",
  "createdAt": "2021-01-21T19:12:28Z",
  "expiredAt": "2021-01-21T19:39:53Z",
  "lastDeclinedAt": "2021-01-21T19:31:13Z",
  "lastRequestedAt": "2021-01-21T19:22:31Z"
}

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

Name
object
Type
string
required
Description
Type of object is always 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
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
firstName
Type
nullable string
required
Description
The first name of the account holder on the donor service provider.
Example: Jerry
Name
lastName
Type
nullable string
required
Description
The last name of the account holder on the donor service provider.
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 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
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
expiredAt
Type
nullable string
required
Description
Time when the porting was expired.
Example: 2021-01-21T19:39:53Z
Name
lastDeclinedAt
Type
nullable string
required
Description
Time when the porting was last declined.
Example: 2021-01-21T19:31:13Z
Name
lastRequestedAt
Type
nullable string
required
Description
Time when the porting was last requested.
Example: 2021-01-21T19:22:31Z

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",
  "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,
  "firstName": "Jerry",
  "lastName": "Seinfeld",
  "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",
  "canceledAt": "2021-01-21T19:39:53Z",
  "completedAt": "2021-01-21T19:36:57Z",
  "createdAt": "2021-01-21T19:12:28Z",
  "expiredAt": "2021-01-21T19:39:53Z",
  "lastDeclinedAt": "2021-01-21T19:31:13Z",
  "lastRequestedAt": "2021-01-21T19:22:31Z"
}

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

Name
object
Type
string
required
Description
Type of object is always 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
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
firstName
Type
nullable string
required
Description
The first name of the account holder on the donor service provider.
Example: Jerry
Name
lastName
Type
nullable string
required
Description
The last name of the account holder on the donor service provider.
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 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
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
expiredAt
Type
nullable string
required
Description
Time when the porting was expired.
Example: 2021-01-21T19:39:53Z
Name
lastDeclinedAt
Type
nullable string
required
Description
Time when the porting was last declined.
Example: 2021-01-21T19:31:13Z
Name
lastRequestedAt
Type
nullable string
required
Description
Time when the porting was last requested.
Example: 2021-01-21T19:22:31Z

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",
  "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,
  "firstName": "Jerry",
  "lastName": "Seinfeld",
  "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",
  "canceledAt": "2021-01-21T19:39:53Z",
  "completedAt": "2021-01-21T19:36:57Z",
  "createdAt": "2021-01-21T19:12:28Z",
  "expiredAt": "2021-01-21T19:39:53Z",
  "lastDeclinedAt": "2021-01-21T19:31:13Z",
  "lastRequestedAt": "2021-01-21T19:22:31Z"
}

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

Name
object
Type
string
required
Description
Type of object is always 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
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
firstName
Type
nullable string
required
Description
The first name of the account holder on the donor service provider.
Example: Jerry
Name
lastName
Type
nullable string
required
Description
The last name of the account holder on the donor service provider.
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 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
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
expiredAt
Type
nullable string
required
Description
Time when the porting was expired.
Example: 2021-01-21T19:39:53Z
Name
lastDeclinedAt
Type
nullable string
required
Description
Time when the porting was last declined.
Example: 2021-01-21T19:31:13Z
Name
lastRequestedAt
Type
nullable string
required
Description
Time when the porting was last requested.
Example: 2021-01-21T19:22:31Z

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",
  "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,
  "firstName": "Jerry",
  "lastName": "Seinfeld",
  "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",
  "canceledAt": "2021-01-21T19:39:53Z",
  "completedAt": "2021-01-21T19:36:57Z",
  "createdAt": "2021-01-21T19:12:28Z",
  "expiredAt": "2021-01-21T19:39:53Z",
  "lastDeclinedAt": "2021-01-21T19:31:13Z",
  "lastRequestedAt": "2021-01-21T19:22:31Z"
}

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

Name
object
Type
string
required
Description
Type of object is always 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",
      "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,
      "firstName": "Jerry",
      "lastName": "Seinfeld",
      "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",
      "canceledAt": "2021-01-21T19:39:53Z",
      "completedAt": "2021-01-21T19:36:57Z",
      "createdAt": "2021-01-21T19:12:28Z",
      "expiredAt": "2021-01-21T19:39:53Z",
      "lastDeclinedAt": "2021-01-21T19:31:13Z",
      "lastRequestedAt": "2021-01-21T19:22:31Z"
    }
  ],
  "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

Name
object
Type
string
required
Description
Type of object is always 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
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
firstName
Type
nullable string
required
Description
The first name of the account holder on the donor service provider.
Example: Jerry
Name
lastName
Type
nullable string
required
Description
The last name of the account holder on the donor service provider.
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 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
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
expiredAt
Type
nullable string
required
Description
Time when the porting was expired.
Example: 2021-01-21T19:39:53Z
Name
lastDeclinedAt
Type
nullable string
required
Description
Time when the porting was last declined.
Example: 2021-01-21T19:31:13Z
Name
lastRequestedAt
Type
nullable string
required
Description
Time when the porting was last requested.
Example: 2021-01-21T19:22:31Z

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",
  "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,
  "firstName": "Jerry",
  "lastName": "Seinfeld",
  "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",
  "canceledAt": "2021-01-21T19:39:53Z",
  "completedAt": "2021-01-21T19:36:57Z",
  "createdAt": "2021-01-21T19:12:28Z",
  "expiredAt": "2021-01-21T19:39:53Z",
  "lastDeclinedAt": "2021-01-21T19:31:13Z",
  "lastRequestedAt": "2021-01-21T19:22:31Z"
}

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

Name
object
Type
string
required
Description
Type of object is always 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

Name
object
Type
string
required
Description
Type of object is always 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
}